Durum Sorgula

GET /v1/integrations/{provider}/orders/status?external_ids=A,B,C

Gönderdiğiniz siparişlerin fatura durumunu toplu döner. Kendi panelinizde sipariş listesinin yanında "faturalandı / bekliyor" göstermek için tasarlanmıştır.

İstek

curl "https://sandbox-api.finansfatura.com/v1/integrations/ecomsoft/orders/status\
?external_ids=ORD-2026-00184,ORD-2026-00185" \
  -H "X-Api-Key: ff_live_xxxxxxxxxxxxxxxxxxxx"

Parametre	Açıklama
`provider`	Yol parametresi. Kaynak markanız.
`external_ids`	Virgülle ayrılmış sipariş kimlikleriniz. En fazla 50.

Sipariş başına tek tek istek atmayın; listeyi tek çağrıda sorgulayın.

Yanıt

200 OK
{
  "statuses": [
    {
      "external_id": "ORD-2026-00184",
      "transaction_id": "9f1c2d3e-...",
      "invoice_status": "ACCEPTED",
      "invoice_id": "05CF936E-D493-5010-A6C8-BDBE9FD619D3",
      "document_id": "1bed7456-e6bc-457d-b3dd-37ec0e1de9df",
      "ettn": "05CF936E-D493-5010-A6C8-BDBE9FD619D3",
      "invoice_number": "FF12026000000184",
      "document_type": "EARSIV",
      "pdf_url": "https://...",
      "invoiced_at": "2026-08-16T11:21:07Z"
    },
    {
      "external_id": "ORD-2026-00185",
      "transaction_id": "7c4d8e21-...",
      "invoice_status": "NOT_INVOICED"
    }
  ]
}

Alan	Açıklama
`external_id`	Sizin sipariş kimliğiniz.
`transaction_id`	Finans Fatura satış kimliği.
`invoice_status`	Belge durumu. Bkz. tablo.
`invoice_id`	GİB ETTN. Geriye dönük uyum için bu adla kalıyor — yeni entegrasyonlarda aşağıdaki `document_id` / `ettn` alanlarını kullanın.
`document_id`	Finans Fatura belge kimliği — fatura kesme yanıtındaki `invoice_id` ile aynı değer.
`ettn`	GİB ETTN — yukarıdaki `invoice_id` ile aynı değer, adı daha açık.
`invoice_number`	Fatura numarası — kesim sonrası kısa süre içinde dolar.
`pdf_url`	Fatura PDF bağlantısı — imzalı ve süreli. Bkz. aşağısı.

invoice_id adı iki uçta farklı şey taşır

Bu uçtaki invoice_id ETTN'dir; fatura kesme yanıtındaki invoice_id ise Finans Fatura belge UUID'sidir — aynı ad, iki farklı kimlik. Hangi alanı ne için saklayacağınızın tam tablosu için bkz. Eşleştirme.

pdf_url imzalı bir bağlantıdır

https://fnsf.tr/f/<token> biçimindedir; token belgeyi ve son kullanma tarihini taşır, 180 gün geçerlidir. Oturum ya da anahtar gerektirmez — müşteriye doğrudan iletebilirsiniz.

Bağlantıyı saklamayın, her sorguda yeniden okuyun: her yanıtta taze bir token üretilir, sakladığınız eski bağlantı bir gün sessizce ölür. Belge iptal edilirse bağlantı da servis etmeyi bırakır.

Ham baytları kendi tarafınızda saklamak isterseniz GET /v1/invoicing/invoices/{invoice_id}/download?format=pdf (ya da xml) ucunu kullanın.

Bize hiç gönderilmemiş siparişler yanıtta yer almaz

50 kimlik sorup 40 sonuç dönmesi normaldir: eksik 10'u bize hiç ulaşmamıştır. Yanıtı external_id ile eşleyin, sıraya güvenmeyin.

Durum değerleri

Durum	Anlamı
`NOT_INVOICED`	Satış var, fatura kesilmemiş
`QUEUED`	Sağlayıcıya iletildi, sonuç bekleniyor
`ISSUED`	Belge kesildi
`ACCEPTED`	Alıcı/GİB tarafından kabul edildi
`REJECTED`	Reddedildi
`CANCELLED`	İptal edildi

QUEUED ve ISSUED geçici durumlardır. Nihai durumlar ACCEPTED, REJECTED ve CANCELLED'dır.

Elinizde external_id listesi yoksa

Bu uç sizin gönderdiğiniz siparişleri sorgular. Belgeyi doğrudan ETTN, fatura numarası ya da belge UUID'siyle bulmak istiyorsanız (ör. yanıtını kaybettiğiniz bir kesim) Fatura Arama'yı kullanın.

Ne sıklıkla sorgulanmalı

Fatura kesimi genellikle saniyeler içinde sonuçlanır. Makul bir yaklaşım:

Kesimden sonraki ilk dakikada bir kez
Sonrasında nihai duruma ulaşmayan kayıtlar için birkaç dakikada bir
Bir saat sonra hâlâ QUEUED ise sorgulamayı bırakın, mükellefe panelinden bakmasını söyleyin

Sürekli kısa aralıklı sorgulama gereksizdir; durum sağlayıcı tarafında değişir, sorgulamanız süreci hızlandırmaz.

İstek​

Yanıt​

Durum değerleri​

Ne sıklıkla sorgulanmalı​

İstek

Yanıt

Durum değerleri

Ne sıklıkla sorgulanmalı