Eşleştirme

Bu sayfa tek bir soruyu yanıtlar: bizden dönen hangi alanı saklayıp hangi alanla sorgulama yapacaksınız? En sık karışıklık buradan çıkıyor çünkü iki ayrı sistemin kendi kimliği var ve ikisi de bazı yanıtlarda invoice_id adını taşıyor.

İki ayrı kimlik, aynı ad

Uç	Alan	Ne taşıyor
POST /v1/invoicing/invoices/ yanıtı	invoice_id	Finans Fatura belge kimliği (UUID)
POST /v1/invoicing/invoices/ yanıtı	ettn	GİB ETTN
GET /v1/integrations/{provider}/orders/status yanıtı	invoice_id	GİB ETTN (yukarıdakiyle aynı değer, farklı adla)

Kimlik "değişmiyor" — aynı ada sahip iki ayrı kimlik görüyorsunuz. Durum sorgusu yanıtı artık bunu tahmine bırakmıyor, aynı anda üç alan dönüyor:

GET /v1/integrations/{provider}/orders/status

{
  "external_id": "...",
  "transaction_id": "...",
  "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": "FA02026000002668",
  "document_type": "EFATURA",
  "pdf_url": "https://fnsf.tr/f/..."
}

invoice_id alanı geriye dönük uyum için ETTN ile dolu kalmaya devam ediyor — değiştirmiyoruz. Kendi tarafınızda sakladığınız alanı seçerken:

• Yeni entegrasyon yazıyorsanız document_id ve ettn alanlarını ayrı ayrı saklayın, invoice_id adını taşıyan iki değeri üst üste yazmayın.
• Download ve iptal uçları ikisini de kabul eder — hangisini sakladığınız pratikte fark etmez, bkz. aşağısı.

{id} bekleyen uçlar ikisini de kabul eder

GET  /v1/invoicing/invoices/{id}
GET  /v1/invoicing/invoices/{id}/download?format=…
POST /v1/invoicing/invoices/{id}/cancel

{id} yerine belge UUID'si ya da ETTN geçebilirsiniz; belge çözümleyici önce ETTN'e, bulamazsa UUID'ye bakar. ETTN eşleşmesi büyük/küçük harf duyarsızdır.

Kendi yerel ID'niz çalışmaz

Biçim UUID olsa bile sizin tarafınızdaki yerel kimlik bizde karşılık bulmaz ve 404 döner. {id} olarak yalnız bizim döndürdüğümüz document_id veya ettn değerini kullanın.

Alan eşlemesi — tam tablo

Alan	Ne	Nerede saklanır
Sizin yerel sipariş/kayıt ID'niz	size ait, bize gitmez	sizde
Idempotency-Key	belgenin GİB UUID'sini belirler — bkz. aşağısı	sizde, fatura isteğinde gönderilir
external_id (satış ucu)	(entegrasyon, varlık tipi, external_id) üçlüsünde tekil	sizde ve bizde
transaction_id	satış kaydı (transaction_header)	bizde, fatura isteğine transaction_header_id olarak geçirilir
invoice_id / document_id	Finans Fatura belge UUID'si	bizde
ettn	GİB ETTN — alt sağlayıcıdaki belge UUID'si ile aynı değer	bizde
invoice_number	resmî fatura numarası (FA0…)	bizde

"Finans Fatura belge ID" ile "alt sağlayıcı belge ID" ayrı iki şey değildir: alt sağlayıcıdaki (e-belge entegratörü) belge UUID'si = ETTN'in ta kendisi.

Idempotency-Key kuralları

POST /v1/invoicing/invoices/ için zorunlu başlık.

Konu	Kural
Azami uzunluk	128 karakter. Aşan anahtar 400 ERROR_IDEMPOTENCY_KEY_TOO_LONG döner — sağlayıcıya hiç gitmeden.
İzinli karakter	Boşluksuz basılabilir ASCII (0x21–0x7E). Boşluk, satır sonu ya da çok baytlı karakter → 400 ERROR_IDEMPOTENCY_KEY_INVALID.
Eksikse	400 ERROR_IDEMPOTENCY_KEY_REQUIRED
Benzersizlik kapsamı	Mükellef bazında — (mükellef, anahtar) çifti tekildir.
Saklama süresi	Süresiz, belge kaydıyla kalıcıdır.

Karakter sınırının sebebi: anahtar, aşağıdaki formülle ETTN'e bayt olarak giriyor. Kodlamaya bağlı bir anahtar, sizin yeniden üretemeyeceğiniz bir ETTN üretirdi.

Tekrar davranışı

• Aynı anahtar + aynı gövde → ilk belgenin yanıtı birebir döner. İkinci fatura kesilmez, ikinci kontör düşümü olmaz.
• Aynı anahtar + farklı gövde → yine ilk belgenin yanıtı döner; yeni gövde yok sayılır, 409 dönmez. "Farklı gövde göndermem gerekiyorsa yeni anahtar kullanırım" kuralını kendi tarafınızda uygulayın.
• Hatalı denemeler saklanmaz. 400 / 412 / 422 / 503 alan bir istekte belge kaydı oluşmaz — aynı anahtarla, düzeltilmiş gövdeyle tekrar deneyebilirsiniz. 422 (sağlayıcı reddi) sonrası tercih edilen yol budur: GİB belge UUID'si sabit kalır.
• 503 / zaman aşımı "belge kesilmedi" demek değildir. Aynı anahtarla tekrar deneyin; belge gerçekten kesilmişse aynı UUID yeniden üretilir, mükerrer belge oluşmaz.

Yanıtı kaybederseniz: ETTN'i kendiniz hesaplayın

Belgenin GİB UUID'si, Idempotency-Key'den deterministik türetilir:

ETTN = UPPERCASE( UUIDv5( ns = 1b671a64-40d5-491e-99b0-da01ff1f3341, Idempotency-Key ) )

Örnek:

"otel-9536e76b31bc62e61f4f475fb3dbddf3"  →  05CF936E-D493-5010-A6C8-BDBE9FD619D3

Bu formül bizim tarafımızda regresyon testiyle sabitlenmiştir: üretilen UBL belgesinin cbc:UUID alanı bu değerden saparsa testimiz kırılır — yani üretim davranışı budur, dokümantasyon varsayımı değil.

Sonuçları:

• Yanıtını kaybettiğiniz her kesimin ETTN'ini yeniden hesaplayabilirsiniz.
• Aynı anahtarla tekrar denerseniz GİB belge UUID'si de aynı çıkar — mükerrer belgeye karşı ikinci bir emniyet katmanıdır.

Belgeyi kimliğiyle arayın

Tarih aralığı tarayıp istemci tarafında eşleştirmek yerine doğrudan arayın:

GET /v1/invoicing/invoices?q=05CF936E-D493-5010-A6C8-BDBE9FD619D3
GET /v1/invoicing/invoices?q=FA02026000002668
GET /v1/invoicing/invoices?q=1bed7456-e6bc-457d-b3dd-37ec0e1de9df

Ayrıntı ve filtrelerle birlikte kullanım için bkz. Fatura Arama.

Mükerrer kesim yapmadan uzlaştırma

Yanıtını kaybettiğiniz, "satışı var ama faturası bizde görünmüyor" kayıtlar için izlenecek sıra:

1. Eski kayıt için yukarıdaki formülle ETTN'i hesaplayın.
2. GET /v1/invoicing/invoices?q=<ETTN> ile sorgulayın.
   • Varsa → belge kesilmiştir; kendi kaydınızı o satırın id (document kimliği) + ettn + invoice_number değerleriyle güncelleyin, yeniden kesmeyin.
   • Yoksa → iki ihtimal var: belge hiç kesilmedi ya da kesildi ama kayıt bir yerde oluşamadı. Hemen yeniden kesmeyin. Bu ETTN listesini [email protected] adresine gönderin; sağlayıcı tarafında tek tek doğrulayalım. Kesilmediği teyit edilen kayıtları, mevcut satışın transaction_header_id'si ve yeni, kısa bir anahtarla yeniden keselim.