Fatura İndir

GET /v1/invoicing/invoices/{id}/download?format=pdf

Scope: invoice:read. {id} yerine belge UUID'si ya da ETTN geçebilirsiniz — bkz. Eşleştirme. ETTN eşleşmesi büyük/küçük harf duyarsızdır; sizin yerel kimliğiniz biçim olarak UUID'e benzese bile çalışmaz, 404 döner.

Biçimler

format	İçerik
pdf (varsayılan)	Belgenin PDF görünümü
html	Belgenin HTML görünümü
xml	Sağlayıcıya gönderilen imzasız UBL-TR kaynağı — bkz. aşağısı

curl "https://sandbox-api.finansfatura.com/v1/invoicing/invoices/05CF936E-D493-5010-A6C8-BDBE9FD619D3/download?format=pdf" \
  -H "X-Api-Key: $FF_KEY" -o fatura.pdf

XML/UBL indirme — imzasız kaynak

GET /v1/invoicing/invoices/{id}/download?format=xml
→ 200
  Content-Type: application/xml; charset=utf-8
  X-FF-Xml-Variant: unsigned-source-ubl

Aldığınız dosya, sağlayıcıya gönderdiğimiz UBL-TR belgesinin birebir aynısıdır. Belgeyi kesilirken sakladığımız kanonikten yeniden üretilir; üretici deterministiktir — cbc:UUID alanı Eşleştirme sayfasındaki ETTN formülüyle birebir tutar, bu bizim tarafımızda regresyon testiyle sabitlenmiştir.

Bu, imzalı nüsha değildir

Mali mühür e-belge entegratörü tarafında atılır; biz imzalı XML'i geri veren bir uç sunmuyoruz. X-FF-Xml-Variant başlığı bunu her yanıtta açıkça söyler. Yasal arşiv bu dosya değildir. İmzalı nüsha gerekiyorsa [email protected] adresine yazın, entegratörden ayrıca temin edelim.

İki ayrıntı daha:

• Dosyada cbc:ID (fatura no) boştur — fatura numarasını sağlayıcı server-side atar ve biz göndermiyoruz; indirdiğiniz dosyanın gönderdiğimizle birebir aynı kalması için sonradan doldurmuyoruz. Resmî numara invoice_number alanında ve PDF'te bulunur.
• Çok eski, kanoniği saklanmamış belgelerde 400 ERROR_INVOICE_XML_UNAVAILABLE döner — tahmin üretmek yerine açıkça reddediyoruz.

Toplu indirmede de format: "xml" artık dolu bir ZIP döner (bkz. Fatura Arama).

ubl_xml_url alanını kullanmayın

Kesim/durum yanıtlarında görebileceğiniz ubl_xml_url alanı Taxten hattında boş gelir. Ham XML için her zaman bu /download?format=xml ucunu kullanın.

Müşteriye giden bağlantı: pdf_url

Kesim ve durum sorgulama yanıtlarındaki pdf_url (https://fnsf.tr/f/<token>) oturumsuz çalışır, HMAC imzalıdır, 180 gün geçerlidir ve kimlik doğrulaması istemez.

Kullanım	Uç
Müşteriye/alıcıya gidecek bağlantı	pdf_url
Kendi tarafınızda arşivlemek için ham baytlar	GET .../download

Bağlantıyı saklamayın, her sorguda yeniden okuyun — her yanıtta taze bir token üretilir.

Hatalar

Durum	Anlamı
400 ERROR_INVOICE_NOT_READABLE	Belge yalnız DRAFT / FAILED durumunda; henüz indirilebilir değil
400 ERROR_INVOICE_XML_UNAVAILABLE	Çok eski belgede kanonik saklanmamış (yalnız format=xml)
404	Belge yok ya da başka bir mükellefe ait