Eafatura.com API
Eafatura.com API
v2.0 Fatura İşlemleri / İade Faturası Oluştur

İade Faturası Oluştur API

Bu servis, bir firmadan aldığınız mal veya hizmeti iade ettiğinizde, o firmaya düzenlemeniz gereken iade faturasını oluşturur. İstek gövdesi create-invoice ile aynıdır; tek fark iade edilen faturaları taşıyan references dizisidir.

Kim, Kime Fatura Keser?

İade faturasını iade eden alıcı (siz) düzenlersiniz ve fatura asıl satıcıya, yani size fatura kesen firmaya kesilir. Bu yüzden gövdedeki customer alanı, faturayı size kesen firmadır. Asıl satış faturası sizin sisteminizde değil satıcının sisteminde olduğu için, faturanın numarasını ve düzenlenme tarihini references içinde siz yazarsınız.

Hangi Belge Oluşturulur?

Seçim hesabınıza göre yapılır: e-Fatura mükellefiyseniz entegratör üzerinden e-Fatura (IADE), değilseniz GİB e-Arşiv portalında e-Arşiv (IADE) iade faturası oluşturulur. Alıcının (satıcının) e-Fatura mükellefi olup olmadığı kontrolü create-invoice ile aynıdır. Gövde iki durumda da aynıdır.

Önemli Validasyon Kuralları
  • • references en az 1, en fazla 20 öğe içermelidir. Her öğede documentNumber ve issueDate zorunludur.
  • • Fatura numarası kalıbı: İade düzenlenecek faturanın geçerli ve resmi fatura numarası olmalıdır. İlk 3 karakter harf, devamı rakam olmalıdır. Aynı fatura bir istekte iki kez verilemez.
  • • Tarih alanlarında gg/aa/yyyy ve yyyy-aa-gg yazımlarının ikisi de kabul edilir. Gelecek tarih ve olmayan günler (31 Şubat gibi) reddedilir.
  • • detail.invoiceType, detail.orderNumber, detail.orderDate ve detail.internetSale bu uçta yok sayılır: tür her zaman IADE'dir, iade faturasına sipariş bilgisi yazılmaz.
  • • Müşteri, kalem, KDV ve fiyat kuralları create-invoice ile aynıdır. Fiyatlar KDV Dahil gönderilir.
  • • API anahtarınız canlı moddaysa sağdaki SEND düğmesi gerçek bir iade faturası keser.
POST https://www.eafatura.com/api/v2/create-return-invoice
Kopyalandı

Header Parametreleri

Body Parametreleri (İade Edilen Faturalar, Satıcı & Kalemler)

references (İade Edilen Faturalar — Array)
references[0].documentNumber Zorunlu
string (16 karakter)

İade ettiğiniz asıl faturanın numarası (size fatura kesen firmanın faturası). Biçim: 3 harf/rakam + yıl (20xx) + 9 haneli sıra, toplam 16 karakter. Küçük harf gönderirseniz büyüğe çevrilir. Birden fazla faturayı iade ediyorsanız sağdaki JSON'a yeni bir references öğesi ekleyin (en fazla 20).
references[0].issueDate Zorunlu
string (gg/aa/yyyy veya yyyy-aa-gg)

Asıl faturanın düzenlenme tarihi. Asıl fatura sizin sisteminizde değil satıcının sisteminde olduğu için tarihi siz yazarsınız. Bugünden ileri bir tarih olamaz.
customer (İade Faturasının Düzenlendiği Taraf = Asıl Faturayı Size Kesen Firma)
customer.taxOrIdentityNumber
string (10 veya 11 hane)

Satıcının VKN/TCKN'si. Yurt dışı bir satıcı için boş bırakın ve country alanına ülke adını yazın.
customer.name Zorunlu
string

Firma için unvan, şahıs (11 hane) için ad soyad tek alanda.
customer.city / district Zorunlu
string
customer.address Zorunlu
string

Açık adres.
customer.country
string

Varsayılan Türkiye. Yurt dışı satıcılarda ülke adı yazılır.
items (İade Edilen Kalemler — Array)
items[0].name Zorunlu
string
items[0].quantity / unitCode Zorunlu
float / string
items[0].unitPriceIncludingVat / vatRate Zorunlu
float / int

Birim fiyat KDV Dahil gönderilmelidir; iade ettiğiniz tutar pozitif yazılır.
detail ve notes (Opsiyonel)
detail.invoiceDate
string (gg/aa/yyyy)

İade faturasının tarihi (opsiyonel, varsayılan: bugünkü tarih). Asıl faturanın tarihi değildir, o references[].issueDate alanındadır.
notes[0]
string

Fatura notu. İade edilen faturalar notun sonuna otomatik eklenir.

Güvenli Tekrar Deneme: Idempotency-Key

Ağ hatası ya da zaman aşımında aynı isteği tekrar gönderdiğinizde iade faturasının iki kez kesilmesini önlemek için isteğe Idempotency-Key başlığı ekleyin. Başlık opsiyoneldir; göndermezseniz istek her seferinde yeni bir iade faturası keser. Anahtar 1-64 karakter olmalı ve yalnızca harf, rakam ve _ . : - içermelidir. Her farklı iade için yeni bir anahtar kullanın (örn. kendi iade numaranız). 

curl --request POST \
  --url https://www.eafatura.com/api/v2/create-return-invoice \
  --header 'Authorization: Basic ...' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: IADE-2026-0001' \
  --data '{ ... }'
Durum Ne olur?
Aynı anahtar, aynı içerik (önceki istek bitti) İlk cevap aynen tekrarlanır (aynı HTTP kodu ve gövde), yanıtta Idempotent-Replayed: true başlığı bulunur. Yeni fatura kesilmez. Saklama süresi 24 saattir.
Aynı anahtar, farklı içerik 422: anahtar başka bir istek için kullanılmış. Alan sırasının farkı içerik farkı sayılmaz.
İstek hâlâ işleniyor 409 ve Retry-After: 2. Birkaç saniye sonra aynı anahtarla tekrar deneyin.
Sonuç belirsiz (belge kesilmiş olabilir; zaman aşımı, bağlantı kopması) 409: aynı anahtarla kör tekrar yapılmaz. Önce fatura listenizi kontrol edin; iade faturası kesilmediyse yeni bir anahtarla tekrar deneyin.
Doğrulama hatası (400) Hata saklanır: aynı içerik aynı hatayı alır. Düzeltilmiş istek için yeni bir anahtar kullanın.
Geçici hata (örn. GİB oturumu alınamadı) Anahtar serbest bırakılır, aynı anahtarla yeniden deneyebilirsiniz.
Anahtar doğrulanamıyor 503: koruma sağlanamadığı için fatura kesilmez. Biraz sonra tekrar deneyin.

Kod Örnekleri


        

    






    
Yanıt Örnekleri