Ana içeriğe geç

Değişiklikler

API'de entegrasyonunuzu etkileyen her değişiklik burada, yenisi üstte.

Kırıcı değişiklik yapmıyoruz

Çalışan bir çağrıyı bozmamaya çalışıyoruz: yeni alanlar opsiyonel gelir, yeni kurallar daha önce geçerli belge üretmeyen isteklere uygulanır. Bir değişiklik yine de davranışı değiştiriyorsa aşağıda Davranış değişti başlığıyla ayrıca yazılır.

İstemci kütüphanelerinin kendi sürüm notları ayrıdır; bkz. İstemci Kütüphaneleri.

2026-10-11​

Eklendi​

  • Durum sorgulama yanıtına document_id ve ettn eklendi. Aynı adı (invoice_id) taşıyan iki ayrı kimliğin (Finans Fatura belge UUID'si / GİB ETTN) karışmaması için — invoice_id alanı geriye dönük uyum amacıyla değiştirilmedi. Bkz. Eşleştirme.
  • Kesim yanıtına document_type ve invoice_number eklendi. EARSIV gönderip alıcının VKN'si e-Fatura mükellefine çıktığında belgenin EFATURA'ya yükseltildiğini görmek için artık ikinci bir GET gerekmiyor. Bkz. Fatura Kes → Yanıt.
  • Belgeyi kimliğiyle arama: GET /v1/invoicing/invoices?q=<ettn|fatura no|belge UUID>. Bkz. Fatura Arama.
  • XML/UBL indirme açıldı: GET /v1/invoicing/invoices/{id}/download?format=xml artık sağlayıcıya gönderilen imzasız UBL-TR kaynağını döner (X-FF-Xml-Variant: unsigned-source-ubl). Toplu indirmede de format: "xml" dolu bir ZIP döner. Bkz. Fatura İndir.
  • Hazırlık/kontör durumu önden sorgulanabilir: GET /v1/integrations/account-status artık edocument_ready, credit_remaining, can_topup_in_app gibi alanları dönüyor. Bkz. Hesap Durumu.
  • Idempotency-Key için yeni hata kodları: ERROR_IDEMPOTENCY_KEY_TOO_LONG (128 karakteri aşan anahtar), ERROR_IDEMPOTENCY_KEY_INVALID (boşluk/çok baytlı karakter). Bkz. Hata Kodları.
  • Yeni referans sayfaları: Fatura Arama, Fatura İndir, Fatura İptal, İade Oluştur, Hesap Durumu. Ayrıca Ön Hazırlıklar bölümü: Sandbox, Üretim vs Sandbox, Eşleştirme.

Davranış değişti​

  • Idempotency-Key tekilliği mükellef bazına çekildi. Önceden global bir indeksti; iki farklı mükellefin aynı anahtarı göndermesi çakışabiliyordu. Artık (mükellef, anahtar) çifti tekildir.
  • Kesim kaydının sessiz kaybı giderildi. Belge sağlayıcıda kesildikten sonra bizdeki satır bir sebeple yazılamazsa bu durum artık yutulmuyor: anahtar kuralları kapıda doğrulanıyor ve yazma hatası hata seviyesinde loglanıp uzlaştırılabiliyor. "Kesildi ama PDF inmiyor" vakalarının en olası nedeni buydu.

2026-10-04​

Eklendi​

  • Dövizli satışta kur artık zorunlu değil. exchange_rate boş ya da 0 gelirse TCMB döviz alış kurunu biz dolduruyoruz. Kullandığımız kur yanıtta döner: currency, exchange_rate, exchange_rate_source (TCMB | MANUAL), exchange_rate_date. Kendi kurunuzu gönderirseniz aynen kullanılır ve TCMB ile karşılaştırılmaz. Bkz. Döviz ve kur.
  • KDV istisnası satış ucunda: invoice_exemption_code + invoice_exemption_reason. %0 KDV'li satır istisna sebebi olmadan faturalanamıyordu ve gönderecek bir alan yoktu. Bkz. KDV istisnası.
  • Senaryo seçimi fatura ucunda: canonical.Scenario = TEMELFATURA | TICARIFATURA (yalnız e-Fatura). Ticari faturayı reddeden alıcıya belge kesilemiyordu. Bkz. Senaryo.
  • İade atfı: canonical.return_info ile iade edilen asıl faturanın numarası ve tarihi. GİB atıfsız iadeyi reddediyor. Bkz. İade faturası.
  • Tevkifat ve özel matrah fatura satırlarında: WithholdingCode, WithholdingName, TaxBaseAmount, TaxBaseCode, TaxBaseReason. Bkz. Tevkifat, özel matrah, istisna.
  • Yeni hata kodları: ERROR_EXCHANGE_RATE_REQUIRED, ERROR_EXCHANGE_RATE_UNAVAILABLE, ERROR_INVOICE_ZERO_VAT_NEEDS_EXEMPTION, ERROR_INVOICE_EXEMPTION_INVALID_CODE, ERROR_INVOICE_WITHHOLDING_INVALID_CODE, ERROR_INVOICE_TAX_BASE_INVALID_CODE, ERROR_INVOICE_RETURN_NEEDS_REFERENCE, ERROR_ORDER_NOT_IMPORTED. Bkz. Hatalar.

Davranış değişti​

  • Tevkifat oranını artık göndermiyorsunuz. Oran GİB koduna göre sunucuda belirlenir; gövdede oran gönderirseniz yok sayılır. Her kodun yasal oranı sabittir ve GİB bunları güncelliyor (612 temizlik hizmeti 2023'te 7/10'dan 9/10'a çıktı) — oran istemciden gelseydi, bir güncelleme sonrası entegrasyonunuz farkında olmadan yanlış beyan üretebilirdi.
  • Satışa bağlı kesimde canonical.Currency gönderilmemeli. Para biriminin tek kaynağı satıştır; gönderdiğiniz değer satıştakiyle değiştirilir. Daha önce gövdedeki değer kullanılıyordu ve dövizli bir satış TRY gönderen bir istemciyle TRY etiketli belgeye dönüşüyordu.
  • Satış zorunluluğunun istisnası üç iade tipini kapsıyor: IADE, TEVKIFATIADE ve YTBIADE. Önceden yalnız IADE muaftı, bu yüzden tevkifatlı iade satışa bağlanmadan kesilemiyordu.
  • Dövizli belge kur olmadan kesilemez: önce sağlayıcı reddiyle (422) dönüyordu, artık ERROR_EXCHANGE_RATE_REQUIRED (400) ile ne eksik olduğunu söylüyor.

2026-09-22​

  • GET /v1/integrations/account-status — mükellefin kurulum durumu (e-posta onayı gibi hatırlatmaları eklentinizde gösterebilmeniz için).

2026-09-17​

  • POST /v1/integrations/orders/invoice-attached — belgeyi kendi kanalınızdaki siparişe iliştirdiğinizi bildirir. Belgede bir şey değişmez; mükellefin panelinde "kanala aktarıldı" kolonunu doldurur. Tekrarı güvenlidir.
  • GET /v1/integrations/orders/channel-sync — hangi satışların faturası kanala aktarıldı.
  • Siparişin tahsilatı: satış gövdesindeki payment alanı, satışa bağlı bir tahsilat makbuzu yazar. checkout_id mükellefin kendi kasa/banka hesaplarından biri olmalı; liste için GET /v1/integrations/checkouts.

2026-09-12​

Doküman netleştirmeleri (API değişmedi):

  • pdf_url imzalı ve süreli bir bağlantıdır; kalıcı adres değildir.
  • Idempotency-Key uzunluk sınırı yazıldı: önerilen ≤ 64, üst sınır 128 karakter.
  • Sağlayıcı reddi 422 + ret sebebiyle döner — 503 "tekrar deneyin" demektir, oysa reddedilen belge düzeltilmeden hiçbir deneme geçmez.

2026-09-03​

  • POST /v1/integrations/refunds — iade. Kendi belgesidir (IADE), kendi idempotanlık kimliğini taşır ve satışa bilerek bağlanmaz: bağlanırsa aynı satış iki kez sayılır. Satırlar pozitif tutar taşır; yönü işaret değil belge tipi söyler.

2026-08-28​

  • Belgenin müşteriye gidecek imzalı bağlantısı (fnsf.tr/f/<token>).
  • Hata gövdeleri kod döner, serbest cümle değil: {"message": "ERROR_X"}. İnsan metnini siz üretirsiniz; bkz. Hatalar.

2026-08-27​

Davranış değişti​

  • Fatura satışa bağlanır. Her belge bir satışın üzerine kesilir: ciro raporu, cari ve stok o bağdan işler. Önce satışı oluşturun, dönen transaction_id'yi fatura ucuna transaction_header_id olarak geçirin (ERROR_SALE_REQUIRED_BEFORE_INVOICE).
  • Satışta alıcı zorunlu: buyer belgenin fatura alıcısıdır ve satışın üzerine kopyalanır. Cari hesap açılmaz — tek seferlik e-ticaret alıcıları cari listesini şişiriyordu.

2026-08-22​

  • Lisansı olmayan mükellefin uçları 402 döner. Satış oluşturmak da fatura kesmek de bu kapıya tabidir.

2026-08-16​

İlk genel sürüm.

  • POST /v1/integrations/orders — tek sipariş ucu, her kaynak için. Kaynak gövdedeki provider alanından çözülür; sağlayıcıya ayrılmış uç yoktur.
  • GET /v1/integrations/:provider/orders/status — toplu fatura durumu.
  • POST /v1/invoicing/invoices/ — belge kesme (Idempotency-Key zorunlu).
  • API anahtarı (X-Api-Key) ve OAuth 2.0 (Authorization: Bearer) ile kimlik doğrulama; invoice:read / invoice:write scope'ları.