Fatura Kes

POST /v1/invoicing/invoices/

Bir satışı e-Fatura veya e-Arşiv'e dönüştürür ve GİB'e gönderir.

Bu adım zorunlu değil

Faturalandırmayı mükellefe bırakabilirsiniz — panelden tek tek ya da toplu keser. Bu ucu yalnızca sipariş anında fatura kesilmesini istiyorsanız çağırın.

Zorunlu başlık: Idempotency-Key

Idempotency-Key: ORD-2026-00184

Bu başlık olmadan istek 400 döner. Aynı anahtarla ikinci kez gönderirseniz yeni fatura kesilmez; ilk faturanın yanıtı aynen döner ve mükellefin kontöründen ikinci kez düşülmez.

Sipariş kimliğinizi anahtar olarak kullanmak en pratiğidir — retry'larınız kendiliğinden güvenli olur.

Uzunluk ve karakter kuralları

Azami uzunluk	128 karakter — aşan anahtar 400 ERROR_IDEMPOTENCY_KEY_TOO_LONG döner
İzinli karakter	Boşluksuz basılabilir ASCII — aksi 400 ERROR_IDEMPOTENCY_KEY_INVALID döner
Benzersizlik kapsamı	Mükellef bazında — (mükellef, anahtar) çifti tekildir

64 karaktere kadar olan anahtar, e-belge sağlayıcısına müşteri fatura no (CustInvID) olarak da iletilir: sağlayıcı panelinde belgeyi kendi sipariş kimliğinizle bulabilirsiniz. Daha uzun anahtarlarda bu alana, anahtarınızdan türetilmiş kararlı bir UUID yazılır — idempotanlık ve retry davranışı aynen korunur, ama sağlayıcı tarafında kendi anahtarınızı göremezsiniz.

Sipariş kimliğiniz uzunsa kısaltın

otel-<64 hane sha256> gibi 69 karakterlik bir kimlik sınırın üstünde kalır. Anahtar yalnız mükellef başına tekil olmak zorundadır; kaynak etiketi + sipariş numarası (otel-INV2026000016) hem tekildir hem sağlayıcı tarafında okunabilir kalır.

Bu anahtarın GİB belge UUID'sini (ETTN) nasıl deterministik belirlediği, aynı/farklı gövdeyle tekrar gönderimde ne olduğu ve yanıtını kaybettiğiniz bir kesimi nasıl kendiniz hesaplayacağınız için bkz. Eşleştirme.

İstek

POST /v1/invoicing/invoices/

{
  "document_type": "EARSIV",
  "transaction_header_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "canonical": {
    "Currency": "TRY",
    "RecipientAlias": "",
    "Recipient": {
      "VKNorTCKN": "11111111111",
      "Title": "Test Müşteri"
    },
    "Lines": [
      {
        "Title": "Danışmanlık hizmeti",
        "ProductCode": "SRV-001",
        "Quantity": 1,
        "UnitPrice": 1000,
        "LineTotal": 1000,
        "UnitCode": "C62",
        "VatRate": 0.2
      }
    ],
    "Totals": {
      "SubtotalExclVAT": 1000,
      "VatTotal": 200,
      "DiscountTotal": 0,
      "GrandTotal": 1200
    }
  }
}

Alan	Zorunlu	Açıklama
document_type	✅	Belge tipi. Bkz. Belge tipi.
canonical	✅	Belge içeriği.
transaction_header_id	✅	Faturalanacak satışın kimliği. Tek istisna iade — bkz. aşağısı.

Satış zorunlu

transaction_header_id olmadan istek 400 döner. Her belge bir satışın üstünde durur: ciro raporu ve stok bu bağdan işler. Önce satışı oluşturun, dönen transaction_id'yi buraya geçirin.

Tek istisna iadedir. canonical.InvoiceTypeCode = IADE gönderdiğinizde satış bağı aranmaz — iade satışa bağlanırsa aynı satış iki kez sayılır.

canonical alanları

Alan	Açıklama
Currency	Para birimi. Boşsa TRY. Satışa bağlı kesimde göndermeyin — bkz. Para birimi.
ExchangeRate	1 birim Currency kaç TL. Currency TRY değilse zorunlu.
ExchangeRateDate	Kurun ait olduğu gün (2026-09-27).
Scenario	e-Fatura senaryosu: TEMELFATURA | TICARIFATURA. Bkz. Senaryo.
InvoiceTypeCode	Fatura tipi. Çoğunlukla göndermeyin — sunucu satırlardan türetir. Bkz. Fatura tipi.
Recipient.VKNorTCKN	Alıcı vergi kimlik ya da TC kimlik numarası.
Recipient.Title	Alıcı unvanı.
RecipientAlias	GİB posta kutusu etiketi. Boş bırakın — biz çözeriz.
Lines[]	Fatura satırları.
Totals	Belge toplamları.
return_info	İade faturasında asıl fatura atfı. Bkz. İade faturası.

Satır alanları: Title, ProductCode, Quantity, UnitPrice, LineTotal, UnitCode, VatRate, TaxExemptionReasonCode, TaxExemptionReason, WithholdingCode, WithholdingName, TaxBaseAmount, TaxBaseCode, TaxBaseReason.

canonical içinde anahtar yazımı PascalCase — tek istisna return_info

canonical içindeki alanlar Currency, Lines, VKNorTCKN gibi PascalCase yazılır; snake_case bir anahtar sessizce yok sayılır.

Tek istisna return_info: o alan sunucuda farklı etiketlenmiştir ve orada doğru yazım snake_case'dir — ReturnInfo yazarsanız atıf düşer ve belge atıfsız iade olarak reddedilir. Resmî kütüphanelerimiz bunu sizin için doğru yazar.

Bu uçta fiyatlar KDV hariç

UnitPrice ve LineTotal KDV hariç tutarlardır. VatRate oran olarak verilir — %20 için 0.2 (satış ucundaki gibi 20 değil).

Yukarıdaki örnekte: 1000 TL mal bedeli + 200 TL KDV = 1200 TL genel toplam.

UnitCode birim kodudur; adet için C62 kullanın (UN/ECE Rec. 20).

Para birimi

Satışa bağlı kesimde Currency göndermeyin. Para biriminin tek kaynağı satıştır: ciro, cari ve stok satışın para biriminden işler, belgenin başka bir para biriminde çıkması defteri satıştan ayırır. Gönderseniz de satıştaki değer kazanır — kur da öyle.

Currency ve ExchangeRate yalnız satışa bağlanmayan belgede (yani iade faturasında) anlam taşır; orada tekrar edilecek bir satış yoktur.

Dövizli belge kursuz kesilemez: ExchangeRate yoksa istek ERROR_EXCHANGE_RATE_REQUIRED döner. İade faturasında asıl satışın taşıdığı kurun aynısını gönderin — bugünün kuru değil.

Senaryo

Yalnız e-Fatura için seçilir:

Değer	Anlamı
TICARIFATURA	Varsayılan. Alıcı 8 gün içinde KABUL/RED yanıtı gönderebilir.
TEMELFATURA	Alıcı yanıt veremez; belge kesindir.

Fark hukukidir, görünüm değil. Boş bırakırsanız TICARIFATURA kullanılır. e-Arşiv'de seçim yoktur: senaryo daima EARSIVFATURA'dır ve gönderdiğiniz değer ezilir.

Satışta bir senaryo seçilmişse (panelden) ve siz göndermezseniz, satıştaki seçim belgeye taşınır.

İade faturası

İade kendi belgesidir ve satışa bağlanmaz — bağlanırsa aynı satış iki kez sayılır. Bu yüzden transaction_header_id zorunluluğunun tek istisnası iade tipleridir: IADE, TEVKIFATIADE, YTBIADE.

Ama iade asıl fatura atfı olmadan kesilemez: GİB şematronu cac:BillingReference şart koşuyor.

{
  "document_type": "EARSIV",
  "canonical": {
    "InvoiceTypeCode": "IADE",
    "return_info": {
      "Originals": [
        { "Number": "FF32026000000123", "IssueDate": "2026-09-27T00:00:00Z" }
      ]
    }
  }
}

IssueDate RFC 3339 olmalıdır; çıplak 2026-09-27 ayrıştırılamaz ve anlamsız bir 400'e dönüşür. Number, GİB'in beklediği 16 haneli fatura numarasıdır. Atıf eksikse istek ERROR_INVOICE_RETURN_NEEDS_REFERENCE döner.

Kanal iadesini bizim üzerinden aktarıyorsanız bu uca hiç gelmeyin: POST /v1/integrations/refunds iadeyi satış kaydı olarak kurar, atfı ve kuru kendisi çözer.

Tevkifat, özel matrah, istisna

Üçü de satır bazında verilir ve üçü farklı şeydir:

	KDV	Nerede
İstisna	yoktur (%0)	Satırda TaxExemptionReasonCode + TaxExemptionReason (GİB 2xx/3xx)
Tevkifat	vardır, tahsilatı bölünür	Satırda WithholdingCode (GİB 6xx/8xx) + WithholdingName
Özel matrah	vardır, farklı tabandan	Satırda TaxBaseAmount + TaxBaseCode (8xx) + TaxBaseReason

Tevkifat oranını göndermeyin

Oran koddan türetilir: her GİB kodunun yasal oranı sabittir (602 → 9/10, 601 → 4/10) ve GİB bunları güncelliyor — 612 temizlik hizmeti 2023'te 7/10'dan 9/10'a çıktı. Oranı siz gönderseydiniz, GİB oranı değiştirdiğinde entegrasyonunuz yıllarca yanlış beyan üretebilirdi.

8xx kodları hem tevkifatta (801-825, tam tevkifat) hem özel matrahta (801-812) vardır ama farklı alanlardır. Kodu yanlış alana yazmak farklı bir UBL elemanı üretir; biçim kontrolü bunu ERROR_INVOICE_WITHHOLDING_INVALID_CODE / ERROR_INVOICE_TAX_BASE_INVALID_CODE ile yakalar.

Fatura tipi

InvoiceTypeCode'u göndermeyin; sunucu belgenin kendisinden türetir:

Satırda ne varsa	Tip
tevkifat	TEVKIFAT
özel matrah	OZELMATRAH
%0 KDV + istisna	ISTISNA
hiçbiri	SATIS

Tipi ekrandan göndermek, belge başka bir yoldan (API, mobil, toplu kesim) kesilince kaybolan bir bilgiydi; o yüzden tek kaynak belgenin kendisidir.

Açıkça göndermeniz gereken tek durum iadedir (bkz. yukarısı): iade, belgenin satırlarından türetilemez.

Belge tipi

Değer	Belge
EFATURA	e-Fatura (alıcı e-Fatura mükellefiyse)
EARSIV	e-Arşiv (alıcı mükellef değilse)
EIRSALIYE	e-İrsaliye
ESMM	e-Serbest Meslek Makbuzu
EMM	e-Müstahsil Makbuzu
EADISYON	e-Adisyon

Belge tipini biz düzeltiriz

E-ticarette alıcılar çoğunlukla bireyseldir, dolayısıyla EARSIV göndermeniz normaldir. Ancak alıcı e-Fatura mükellefi çıkarsa e-Arşiv kesmek mevzuata aykırıdır.

RecipientAlias boş bıraktığınızda alıcının VKN'sini GİB'e sorarız:

• Mükellefse → belge EFATURA'ya yükseltilir, posta kutusu etiketi otomatik çözülür
• Değilse → EARSIV olarak kesilir

Yani gönderdiğiniz document_type bir tercihtir, son söz değildir. Mükellef sorgusu yapmanız gerekmez.

Yanıt

200 OK

{
  "invoice_id": "1bed7456-e6bc-457d-b3dd-37ec0e1de9df",
  "status": "ISSUED",
  "document_type": "EFATURA",
  "invoice_number": "FA02026000002668",
  "mode": "GATEWAY",
  "provider": "taxten",
  "ettn": "05CF936E-D493-5010-A6C8-BDBE9FD619D3",
  "pdf_url": "https://fnsf.tr/f/..."
}

Alan	Açıklama
invoice_id	Finans Fatura belge UUID'si. Durum sorgulama ucundaki aynı adlı alandan farklıdır — bkz. Eşleştirme.
status	Belge durumu.
document_type	Kesilen belgenin nihai tipi. İstediğiniz EARSIV ise ve alıcı e-Fatura mükellefiyse burada EFATURA görürsünüz — bkz. Belge tipini biz düzeltiriz.
ettn	GİB tekil belge numarası.
pdf_url	Fatura PDF adresi — imzalı, süreli bağlantı. Ham baytlar için Fatura İndir.

Fatura numarası

e-Arşiv'de invoice_number kesimle birlikte gelir. e-Fatura'da sağlayıcı imza/sorgu adımından sonra doldurur; yanıtta boş geldiyse Durum sorgulama ucundan okuyun.

ubl_xml_url alanını kullanmayın

Bu alan Taxten hattında boş gelir. Ham UBL/XML için her zaman Fatura İndir ucunu (?format=xml) kullanın.

Diğer uçlar

İşlem	Uç
Fatura listesi	GET /v1/invoicing/invoices/?page=1&page_size=20
Kimlikle arama	GET /v1/invoicing/invoices?q=<ettn|fatura no|belge UUID> — bkz. Fatura Arama
Tek fatura	GET /v1/invoicing/invoices/{id}
İndirme (pdf/html/xml)	GET /v1/invoicing/invoices/{id}/download?format=… — bkz. Fatura İndir
İptal	POST /v1/invoicing/invoices/{id}/cancel — bkz. Fatura İptal
İade	POST /v1/integrations/refunds — bkz. İade Oluştur
Hazırlık/kontör durumu	GET /v1/integrations/account-status — bkz. Hesap Durumu

{id} yerine belge UUID'si ya da ETTN geçebilirsiniz — ikisi de kabul edilir, bkz. Eşleştirme. İptal, belgenin tipine ve durumuna göre farklı işler: e-Arşiv doğrudan iptal edilebilir, e-Fatura'da alıcının onayına bağlı bir süreç işler.