İçeriğe geç

Sipariş entegrasyonu

Özel Entegrasyon API

Kendi sitenizin siparişleri kendiliğinden faturalansın: siteniz uçları açar, eFaturan siparişleri çeker.

Kendi yazılımıyla çalışan e-ticaret siteleri ve altyapı firmaları için. Satıcı mağazayı panelde ekler.

Base URLhttps://www.siteniz.com/api/efaturanörnek
Sürüm
v1.1
Son güncelleme
Uç sayısı
7 uç
Tanım dosyaları
OpenAPI 3.1 (YAML)

Genel bakış

Siteniz aşağıdaki uçları kendi sunucusunda açar; eFaturan istemcidir. eFaturan siparişleri düzenli aralıklarla (varsayılan 15 dakikada bir) çeker, e-Fatura ya da e-Arşiv olarak faturalar ve isterseniz faturayı ve kargo bilgisini sitenize geri bildirir. İsteğe bağlı anlık bildirimle siteniz yeni siparişi beklemeden bildirebilir.

UçYönZorunlu muNe zaman
GET /pingeFaturan → siteEvetPanelde "Bağlantıyı sına"
GET /order-statuseseFaturan → siteEvetSatıcı durum seçerken ve sınamada
GET /orderseFaturan → siteEvetDüzenli çekim
GET /orders/{id} v1.1eFaturan → siteAnlık bildirim kullanılıyorsaAnlık bildirimden sonra
POST /invoiceseFaturan → siteSatıcı "fatura bağlantısı sitenize iletilsin" seçtiyseFatura GİB'e iletildikten sonra
POST /shipments v1.1eFaturan → siteSatıcı "kargo bilgisi sitenize iletilsin" seçtiyseTakip numaralı kargo gönderisi oluşunca
POST https://panel.efaturan.com/api/hooks/custom/{mağaza anahtarı} v1.1site → eFaturanHayırSipariş oluşunca / değişince

Tüm uçlar tek bir kök adresin altındadır, ör. https://www.siteniz.com/api/efaturan → …/api/efaturan/orders.

Sürümler ve değişiklikler

  • Sürüm, her istekte X-Efaturan-Protocol başlığıyla gönderilir (ör. 1.1). Siteniz /ping yanıtında kendi uyguladığı sürümü version alanıyla bildirebilir.
  • Küçük sürümler (1.x) yalnızca İSTEĞE BAĞLI alan ve uç ekler; geriye uyumludur. v1 için yazılmış bir site değişiklik yapmadan çalışmaya devam eder.
  • Bilinmeyen alanları yok sayın: eFaturan'ın gönderdiği bildirimlere ileride yeni alanlar eklenebilir.
  • Kırıcı değişiklik yeni ana sürüm (2) olur; eski ana sürüm en az 6 ay birlikte desteklenir ve değişiklik önceden duyurulur.

1.1 (2026-11-21)#

  • Yalnızca HTTPS ve 443 portu; yönlendirme izlenmez. http adresi kayıtta ve çağrıda reddedilir.
  • Zorunlu alanlar şemadan doğrulanır: eksik ya da hatalı zorunlu bilgi olan sipariş faturalanmaz, "Eksik bilgi" durumuyla satıcıya alan adıyla gösterilir (önceden KDV oranı %20, tarih "şimdi", miktar 1 sayılıyordu).
  • Sayfalama: totalPages gönderilmezse sayfa pageSize'dan kısa gelene kadar sonraki sayfa istenir; sınıra ya da tekrar eden sayfaya takılınca satıcıya uyarı düşer.
  • Yeni isteğe bağlı sipariş alanları: shippingAddress, orderDiscount, fees, items[].lineId / barcode / unit, paymentAgent, exchangeRate, note, invoiceNote, total, refund.
  • Yeni isteğe bağlı uçlar: GET /orders/{id} (anlık bildirim için), POST /shipments (kargo bildirimi).
  • Anlık bildirim (site → eFaturan): POST /api/hooks/custom/{mağaza anahtarı}, HMAC-SHA256 imzalı.
  • Faturalı sipariş iptal/iade gelirse belge kendiliğinden kesilmez; satıcının onayına düşer.
  • Kendiliğinden fatura iptali için refund.amount zorunlu ve fatura tutarıyla aynı olmalı; mağaza başına 24 saatte en çok 5 iptal; aynı çekimde olağandışı sayıda iptal/iade gelirse hiçbiri kendiliğinden uygulanmaz.
  • Anlık bildirimle gelen sipariş düzenli çekimle aynı kurallardan geçer (geriye dönük çekim süresi, faturalanacak durumlar, fatura tarihi onayı); bu kurallara takılan sipariş kaydedilir ama otomatik faturalanmaz.
  • Kök adres ve bildirim orderId kuralları sıkılaştı: eFaturan'ın kendi alan adları reddedilir; orderId yalnızca harf, rakam ve . _ : - içerebilir.
  • Hata gövdesi önerisi: { "error": { "code", "message" } }.

1 (2026-10-08)#

  • İlk sürüm: GET /ping, GET /order-statuses, GET /orders, POST /invoices.

Hızlı başlangıç ve sınama

Siteniz uçları açtıktan sonra mağaza panelde eklenir ve canlıya almadan önce şu sırayla sınanır.

  1. Panelde Mağaza Ayarları › Özel Entegrasyon › yeni mağaza: https kök adresini ve API anahtarını girin, kaydedin.
  2. "Bağlantıyı sına": adres kuralları, /ping, /order-statuses, son günlerin siparişleri ve her siparişin zorunlu alanları alan alan raporlanır. Fatura ve kargo bildirimi sitenizde kayıt oluşturduğu için sınanmaz.
  3. Otomatik faturayı kapalı tutarak siparişleri çekin; bir siparişi elle faturalayıp tutarı, KDV'yi ve alıcıyı doğrulayın. Sonra otomatik faturayı açın.

Bağlantı ve kimlik doğrulama

  • Yalnızca HTTPS ve 443 portu. http:// ya da standart dışı port (ör. :8443) içeren adres panelde kaydedilmez, kayıtlı olsa da çağrılmaz. Kök adreste sorgu dizesi (?) ve # bölümü olamaz.
  • Adres internetten erişilen (genel) bir sunucuya çözülmelidir; yerel / özel ağ adresleri ve eFaturan'ın kendi alan adları reddedilir. Bağlantı, ad çözümlemesinde denetlenen adrese kurulur.
  • Yönlendirme izlenmez. 301/302/307/308 yanıtı hata sayılır; uçların son adresini girin.
  • Kimlik doğrulama: her istekte Authorization: Bearer <API anahtarı>. Anahtarı siteniz üretir; satıcı panele girer, eFaturan şifreli saklar ve ekranda bir daha göstermez. Hatalı anahtarda 401 dönün.
  • eFaturan her istekte X-Efaturan-Protocol: 1.1 ve User-Agent: eFaturan-Ozel-Entegrasyon/1.1 gönderir.
  • İstek ve yanıtlar JSON (UTF-8). JSON dönen uçlarda (/ping, /order-statuses, /orders, /orders/{id}) yanıtın Content-Type başlığı application/json olmalıdır.
  • Süre ve boyut sınırları: /orders 30 sn ve 10 MB; diğer uçlar 20 sn ve 1 MB (/orders/{id} 2 MB).
  • Yeniden deneme: ağ hatası, 429 ve 5xx yanıtında /orders ve /order-statuses 2 kez daha, /invoices ve /shipments 1 kez daha denenir; /ping denenmez. Retry-After en çok 10 saniyeye kadar dikkate alınır.
  • eFaturan aynı mağaza için sayfaları sırayla ister; aynı anda birden fazla istek göndermez.

Sipariş alanları

İç içe alanlarda "zorunlu", üst nesne gönderildiğinde zorunlu demektir (ör. shippingAddress gönderilirse shippingAddress.address). Bilinmeyen alanlar yok sayılır.

AlanTürZorunlulukAçıklama
idmetin (≤ 64)zorunluSipariş kimliği. Siparişin sitenizdeki tekil kimliği (metin). Faturalanan birimdir; aynı kimliğe ikinci fatura kesilmez.
numbermetin (≤ 64)isteğe bağlıSipariş no. Müşteriye gösterilen sipariş numarası; faturada sipariş referansı olarak yazılır.
status"created" · "paid" · "shipped" · "delivered" · "cancelled" · "returned"zorunluDurum. created ödeme bekleniyor · paid · shipped · delivered · cancelled · returned. Yalnızca paid, shipped ve delivered faturalanır.
statusIdmetin (≤ 100)koşullu (satıcı mağaza ayarında faturalanacak durumları seçtiyse)Durum kimliği. Sitenizdeki durum kimliği (/order-statuses).
createdAttarih-saat (ISO 8601, saat dilimli)zorunluSipariş tarihi. Siparişin oluşturulduğu an, saat dilimiyle.
paidAttarih-saat (ISO 8601, saat dilimli)isteğe bağlıÖdeme tarihi. Gönderilmezse sipariş tarihi kullanılır (e-Arşiv internet satışı bilgisi).
currencymetinisteğe bağlıPara birimi. ISO 4217 (ör. TRY, USD). Gönderilmezse TRY.
exchangeRate v1.1sayı (ondalık)isteğe bağlıKur. 1 birim döviz = kaç TL. USD ve EUR'da fatura kuru hesabın kur ayarına göre TCMB'den alınır ve bu değer kullanılmaz; diğer para birimlerinde faturaya bu kur yazılır (yoksa sipariş otomatik faturalanmaz).
pricesIncludeVattrue / falseisteğe bağlıFiyatlar KDV dahil mi. Varsayılan true. Mağaza ayarında "Siteden gelen fiyatlar" seçiliyse o geçerlidir.
paymentMethod"KREDIKARTI/BANKAKARTI" · "EFT/HAVALE" · "KAPIDAODEME" · "ODEMEARACISI" · "DIGER"isteğe bağlıÖdeme yöntemi. GİB internet satışı kodu. Gönderilmezse DIGER.
paymentAgent v1.1metin (≤ 100)koşullu (paymentMethod = ODEMEARACISI)Ödeme aracısı. Ödemeyi tahsil eden kuruluşun adı (ör. iyzico). e-Arşiv internet satışı bilgisine yazılır.
customernesnezorunluAlıcı. Fatura alıcısı.
customer.type"individual" · "company"zorunluAlıcı türü. individual bireysel, company kurumsal (şirket ya da şahıs firması). Belge türü kimlik numarasından belirlenir: vergi kimliği olan alıcı e-Fatura kullanıcısıysa e-Fatura, değilse e-Arşiv kesilir.
customer.namemetin (≤ 200)zorunluAlıcı adı. Bireyde ad soyad, kurumsalda unvan.
customer.taxNumbermetinkoşullu (customer.type = company)VKN / TCKN. Şirkette 10 haneli VKN; bireyde ve şahıs firmasında 11 haneli TCKN. Bireyde kimlik yoksa göndermeyin (nihai tüketici).
customer.taxOfficemetin (≤ 100)isteğe bağlıVergi dairesi. Kurumsal alıcının vergi dairesi.
customer.emailmetin (≤ 200)isteğe bağlıE-posta. Fatura e-postası (mağaza ayarı açıksa fatura bu adrese gönderilir).
customer.phonemetin (≤ 40)isteğe bağlıTelefon
customer.addressmetin (≤ 500)isteğe bağlıFatura adresi. Açık adres (FATURA adresi; teslimat adresi shippingAddress alanındadır).
customer.districtmetin (≤ 100)isteğe bağlıİlçe
customer.citymetin (≤ 100)isteğe bağlıİl
customer.postalCodemetin (≤ 10)isteğe bağlıPosta kodu
customer.countrymetin (≤ 60)isteğe bağlıÜlke. Gönderilmezse Türkiye.
shippingAddress v1.1nesneisteğe bağlıTeslimat adresi. Kargo gönderisinin alıcısı. Faturaya YAZILMAZ; gönderilmezse kargo fatura adresine düşer ve satıcı uyarılır.
shippingAddress.namemetin (≤ 200)zorunluTeslimat alıcısı
shippingAddress.companymetin (≤ 200)isteğe bağlıFirma adı
shippingAddress.phonemetin (≤ 40)isteğe bağlıTelefon
shippingAddress.emailmetin (≤ 200)isteğe bağlıE-posta
shippingAddress.addressmetin (≤ 500)zorunluTeslimat adresi
shippingAddress.neighborhoodmetin (≤ 100)isteğe bağlıMahalle
shippingAddress.districtmetin (≤ 100)isteğe bağlıİlçe
shippingAddress.citymetin (≤ 100)zorunluİl
shippingAddress.postalCodemetin (≤ 10)isteğe bağlıPosta kodu
shippingAddress.countrymetin (≤ 60)isteğe bağlıÜlke. Gönderilmezse Türkiye.
shippingnesneisteğe bağlıKargo
shipping.feesayı (ondalık)isteğe bağlıKargo ücreti. Alıcıdan alınan kargo ücreti; "Kargo Bedeli" satırı olur. KDV oranı mağaza ayarından gelir (oranı siz göndermek için fees kullanın).
shipping.carriermetin (≤ 100)isteğe bağlıKargo firması. e-Arşiv internet satışı bilgisine taşıyıcı olarak yazılır.
shipping.trackingNumbermetin (≤ 80)isteğe bağlıTakip no. Bilgi amaçlı; faturaya yazılmaz.
shipping.shippedAttarih-saat (ISO 8601, saat dilimli)isteğe bağlıGönderim tarihi. e-Arşiv internet satışı bilgisine yazılır.
itemsdizizorunluÜrün satırları
items[].lineId v1.1metin (≤ 64)isteğe bağlıSatır kimliği. Satırın sitenizdeki kimliği; kısmi iadede refund.lines[].lineId ile bu satıra başvurulur.
items[].skumetin (≤ 100)isteğe bağlıStok kodu. Ürün kartıyla eşleştirmede kullanılır.
items[].barcode v1.1metin (≤ 64)isteğe bağlıBarkod. Stok kodu eşleşmezse ürün kartı barkodla aranır.
items[].namemetin (≤ 500)zorunluÜrün adı
items[].quantitytam sayızorunluMiktar. Tam sayı.
items[].unit v1.1"C62" · "KGM" · "GRM" · "LTR" · "MTR" · "MTK" · "BX" · "PA" · "SET" · "HUR" · "DAY" · "MON"isteğe bağlıBirim. UBL birim kodu: C62 (adet), KGM (kilogram), GRM (gram), LTR (litre), MTR (metre), MTK (metrekare), BX (kutu), PA (paket), SET (set), HUR (saat), DAY (gün), MON (ay). Gönderilmezse C62 (adet).
items[].unitPricesayı (ondalık)zorunluBirim fiyat. İndirim öncesi birim fiyat (pricesIncludeVat'e göre KDV dahil ya da hariç).
items[].vatRate0 · 1 · 10 · 20zorunluKDV oranı. Satırın KDV oranı (%). Gönderilmezse sipariş faturalanmaz; tek istisna: satıcı mağaza ayarında "tüm ürünler tek KDV oranı" seçtiyse oran oradan gelir.
items[].discountsayı (ondalık)isteğe bağlıSatır indirimi. Satırın TOPLAM indirimi (birim başına değil), fiyatla aynı KDV bazında.
orderDiscount v1.1sayı (ondalık)isteğe bağlıSipariş indirimi. Sipariş geneli indirim (kupon), fiyatlarla aynı KDV bazında. Ürün satırlarına tutarlarıyla orantılı dağıtılır; kargo ve ek ücretlere uygulanmaz.
fees v1.1diziisteğe bağlıEk ücretler. Kargo, kapıda ödeme, hizmet bedeli gibi ücretler; her biri kendi KDV oranıyla ayrı fatura satırı olur. shipping.fee ile birlikte kargo ücreti gönderilmez.
fees[].type"shipping" · "cod" · "service" · "other"zorunluÜcret türü. shipping kargo, cod kapıda ödeme, service hizmet bedeli, other diğer.
fees[].namemetin (≤ 100)isteğe bağlıFaturadaki ad. Gönderilmezse türün adı (ör. "Kapıda Ödeme Bedeli").
fees[].amountsayı (ondalık)zorunluTutar. Ücret tutarı, fiyatlarla aynı KDV bazında.
fees[].vatRate0 · 1 · 10 · 20zorunluKDV oranı. Ücretin KDV oranı (%).
total v1.1sayı (ondalık)isteğe bağlıSipariş toplamı. Alıcının ödediği toplam. Gönderilirse hesaplanan fatura toplamıyla karşılaştırılır; tutmazsa sipariş "Kontrol gerekli" olur.
note v1.1metin (≤ 1000)isteğe bağlıSipariş notu. Alıcının notu. Kaydedilir, faturaya yazılmaz.
invoiceNote v1.1metin (≤ 500)isteğe bağlıFatura açıklaması. Faturanın açıklama (not) bölümüne yazılır.
invoicedtrue / falseisteğe bağlıBaşka yerde faturalandı. true ise sipariş alınır ama faturalanmaz.
marketplacemetin (≤ 60)isteğe bağlıPazaryeri kaynağı. Sipariş bir pazaryerinden sitenize aktarıldıysa pazaryerinin adı (ör. "Trendyol"). Varsayılan olarak faturalanmaz; satıcı mağaza ayarında açarsa faturalanır.
refund v1.1nesneisteğe bağlıİptal / iade bilgisi. Yalnızca status cancelled ya da returned iken gönderilir. Faturası kesilmiş siparişte hiçbir belge kendiliğinden kesilmez: panelde onay bekleyen işlem oluşur.
refund.type"cancel" · "return"zorunluTür. cancel iptal (status: cancelled ile), return iade (status: returned ile).
refund.scope"full" · "partial"isteğe bağlıKapsam. full tamamı (varsayılan), partial kısmi.
refund.amountsayı (ondalık)koşullu (refund.scope = partial)Tutar. İptal / iade edilen toplam tutar (KDV dahil, sipariş para biriminde). Gönderilmezse fatura iptali kendiliğinden uygulanmaz; satıcının onayına düşer.
refund.linesdiziisteğe bağlıİade edilen satırlar. Kısmi iadede hangi satırdan kaç adet.
refund.lines[].lineIdmetin (≤ 64)isteğe bağlıSatır kimliği
refund.lines[].skumetin (≤ 100)isteğe bağlıStok kodu
refund.lines[].quantitytam sayızorunluMiktar
refund.reasonmetin (≤ 300)isteğe bağlıNeden
refund.attarih-saat (ISO 8601, saat dilimli)isteğe bağlıTarih. İptal / iade tarihi.

4.1 Eksik bilgi: sessiz doldurma yok#

Zorunlu bir alan gönderilmezse ya da hatalıysa sipariş kaydedilir ama faturalanmaz. Satıcının Siparişler ekranında "Eksik bilgi" durumuyla, neyin eksik olduğu alan adıyla görünür (ör. "2. ürün satırı › KDV oranı (items[1].vatRate) gönderilmedi."). Sipariş otomatik, elle ya da birleştirerek de faturalanamaz. Siteniz düzeltip yeniden gönderdiğinde (sonraki çekimde ya da anlık bildirimle) engel kendiliğinden kalkar.

  • Tek istisna KDV oranıdır: satıcı mağaza ayarında "tüm ürünler tek KDV oranı" seçtiyse satır KDV'si gönderilmese de oran oradan gelir. Bu ayar seçiliyken gönderdiğiniz satır KDV oranının yerine de o oran kullanılır (ek ücretler hariç).
  • Saat dilimi olmayan tarih (2026-10-08T10:15:00) reddedilir: fatura gününü kaydırabilir.
  • Geçerli KDV oranları 0, 1, 10 ve 20'dir. %0 satıra istisna kodu 351 yazılır.
  • Kurumsal alıcıda (customer.type: company) customer.taxNumber zorunludur. Belge türü kimlik numarasından belirlenir: 10 haneli VKN ya da 11 haneli TCKN'si olan alıcı e-Fatura kullanıcısıysa e-Fatura, değilse e-Arşiv kesilir. Bireyde kimlik yoksa nihai tüketici (11111111111) yazılır.
  • paymentMethod: "ODEMEARACISI" ise paymentAgent zorunludur.
  • Faturası kesilmiş siparişin kalemleri değişmez. Faturalı siparişe eksik/hatalı bilgiyle gelen güncelleme yok sayılır.

4.2 Tutarlar ve KDV#

  • Tutarlar ondalık sayıdır (ör. 149.90), sipariş para biriminde. Eski sürüm uyumluluğu için "149.90" / "149,90" gibi sayısal metin de kabul edilir.
  • pricesIncludeVat (varsayılan true): unitPrice, discount, orderDiscount, fees[].amount ve shipping.fee aynı KDV bazındadır. Satıcı mağaza ayarında "Siteden gelen fiyatlar"ı seçtiyse o geçerlidir; "İskonto KDV hariç gelir" ayarı indirimin bazını değiştirir.
  • KDV dahil fiyatla gelen siparişte faturanın ödenecek tutarı sipariş toplamına kuruşu kuruşuna eşittir.
  • orderDiscount ürün satırlarına, indirim sonrası tutarlarıyla orantılı dağıtılır (kalan kuruş en büyük satıra); kargo ve ek ücretlere uygulanmaz.
  • fees her biri kendi KDV oranıyla ayrı fatura satırıdır. Eski shipping.fee de "Kargo Bedeli" satırı olur; oranı satıcının mağaza ayarından gelir (sabit oran, ürünlerin oranı). Kargo ücretini ya shipping.fee ya fees içinde gönderin; ikisi birlikte "eksik bilgi" sayılır.
  • total gönderirseniz hesaplanan fatura toplamıyla karşılaştırılır (satır başına 1 kuruş tolerans); tutmazsa sipariş "Kontrol gerekli" olur ve otomatik faturalanmaz.
  • Para birimi: gönderilmezse TRY. USD ve EUR'da kur, satıcının hesabındaki kur ayarıyla TCMB'den alınır (exchangeRate kullanılmaz). Diğer para birimlerinde exchangeRate faturaya yazılır; gönderilmezse sipariş otomatik faturalanmaz.
  • Miktar tam sayıdır; birim gönderilmezse adet (C62).

4.3 Hangi siparişler faturalanır#

  • Yalnızca ödemesi alınmış durumlar: paid, shipped, delivered. created ödeme alınınca faturalanır; cancelled ve returned faturalanmaz.
  • Satıcı mağaza ayarında "faturalanacak durumlar" seçtiyse ayrıca statusId bu durumlardan biri olmalıdır (gönderilmezse sipariş faturalanmaz, nedeni listede yazar). Bu seçim çekimi süzmez; iptal ve iade bildirimleri her durumda alınır.
  • invoiced: true siparişler alınır ama faturalanmaz.
  • marketplace dolu (pazaryerinden sitenize aktarılmış) siparişler varsayılan olarak faturalanmaz; satıcı mağaza ayarında o pazaryerini açarsa faturalanır (pazaryeri mağazası ayrıca bağlıysa fatura oradan kesilir).
  • Satıcı "otomatik fatura"yı açmadıysa siparişler yalnızca çekilir; faturayı satıcı panelden keser.
  • Otomatik faturada ayrıca: sipariş tarihi mağazanın geriye dönük çekim süresinden eskiyse ya da bugünle kesilecek fatura tarih kuralı gereği onay istiyorsa (ör. 7 günden eski sipariş) sipariş kaydedilir ama kendiliğinden faturalanmaz; "Kontrol gerekli" nedeniyle satıcıya düşer.
  • Bu kuralların hepsi anlık bildirimle (bölüm 6) gelen siparişe de aynen uygulanır.

4.4 Faturaya yazılanlar#

  • Açıklama: <kanal> sipariş no: <id>, dövizli siparişte kur bilgisi, satıcının mağaza ayarındaki sabit açıklama ve siparişin invoiceNote alanı. note (alıcının notu) faturaya yazılmaz.
  • Sipariş referansı: number (yoksa id) ve sipariş tarihi.
  • e-Arşiv internet satışı bilgisi: satıcının mağaza ayarındaki web adresi, ödeme yöntemi (paymentMethod, yoksa DIGER), ödeme aracısı (paymentAgent), ödeme tarihi (paidAt, yoksa sipariş tarihi), taşıyıcı ve gönderim tarihi (shipping.carrier, shipping.shippedAt).
  • Ürün kartıyla eşleşen satıra (önce sku, sonra barcode) satıcının stok kodu ve GTİP yazılır.
  • Teslimat adresi (shippingAddress) faturaya yazılmaz; kargo gönderisinde kullanılır.

İptal ve iade

  • Faturası kesilmemiş siparişi cancelled / returned gönderdiğinizde sipariş faturalanmaz.
  • Faturası kesilmiş sipariş sonradan cancelled ya da returned gelirse hiçbir belge kendiliğinden kesilmez. Satıcının panelinde (Siparişler › İptal ve İadeler) onay bekleyen işlem oluşur ve bildirim düşer. Satıcı seçer: faturayı iptal et (yalnızca e-Arşiv), iade faturası taslağı oluştur (satıcı kontrol edip keser), işlem yapma.
  • Satıcı "bu mağazanın bundan sonraki iptallerinde / iadelerinde hep böyle yap" seçerse sonraki olaylarda seçim kendiliğinden uygulanır; ancak iade faturası yalnızca taslak olarak oluşur, fatura iptali yalnızca e-Arşiv, aynı ay, tek siparişlik fatura ve olayın tamamı için uygulanır. Bu koşullar tutmazsa olay yine satıcının onayına düşer.
  • Kendiliğinden fatura iptali için ek sınırlar: - refund.amount gönderilmeli ve fatura tutarıyla aynı olmalıdır (1 kuruş fark kabul edilir); yoksa onaya düşer. - Mağaza başına 24 saatte en çok 5 fatura kendiliğinden iptal edilir; fazlası onaya düşer ve satıcıya bildirim gider. - Aynı çekimde gelen yeni iptal/iade sayısı 3 ya da daha fazlaysa ve çekilen siparişlerin yarısından fazlasıysa hiçbiri kendiliğinden uygulanmaz; hepsi onaya düşer (sitedeki toplu durum hatasına karşı).
  • Kısmi iade için status: "returned" ile refund: { "type": "return", "scope": "partial", "amount": …, "lines": [ … ] } gönderin. refund.lines[] satırı lineId (önerilen) ya da sku ile gösterir. Aynı iade (aynı tutar ve satırlar) ikinci kez işlem açmaz; farklı bir kısmi iade yeni işlem açar (sipariş başına en çok 10 işlem).
JSON
{ "id": "10045", "status": "returned", "refund": { "type": "return", "scope": "partial", "amount": 120.00, "lines": [ { "lineId": "1", "quantity": 1 } ], "reason": "Beden uymadı" }, "…": "diğer alanlar" }

Anlık bildirim

Siteniz yeni ya da değişen siparişi anında bildirebilir; eFaturan siparişi beklemeden çeker. İsteğe bağlıdır; düzenli çekim yedek olarak sürer. Bildirim adresi ve gizli anahtar satıcının panelinde, mağaza ayarlarının "Anlık bildirim" bölümündedir (anahtar orada gösterilir ve yenilenir).

HTTP
POST /api/hooks/custom/{mağaza anahtarı} HTTP/1.1
Host: panel.efaturan.com
Content-Type: application/json
X-Efaturan-Timestamp: 1795430400
X-Efaturan-Signature: v1=<imza>

{"event":"order.created","orderId":"10045"}
  • Gövdeye güvenilmez: yalnızca orderId alınır; sipariş eFaturan tarafından sitenizin GET /orders/{id} ucundan çekilir ve normal çekimle aynı kurallarla işlenir (bölüm 4.3 ve 5). event bilgi amaçlıdır. orderId yalnızca harf, rakam ve . _ : - içerebilir (en çok 64; . ya da .. olamaz).
  • İmza: hex(HMAC-SHA256(gizli anahtar, "<zaman damgası>.<ham gövde>")), başlıkta v1= önekiyle.
  • Zaman damgası unix saniyedir ve sunucu saatinden en çok 5 dakika farklı olabilir. Aynı imza ikinci kez kabul edilmez: her bildirimde güncel zaman damgasıyla yeniden imzalayın.
  • Gövde en çok 8 KB, Content-Type: application/json. Mağaza başına dakikada 120 bildirim.
  • Yanıt 202 ise bildirim alınmıştır; sipariş kısa süre içinde çekilir.
AlanTürZorunlulukAçıklama
event"order.created" · "order.updated" · "order.cancelled" · "order.returned"zorunluOlay
orderIdmetinzorunluSipariş kimliği. Harf, rakam ve . _ : - (en çok 64). Gövdeden yalnızca bu alan kullanılır; sipariş eFaturan tarafından GET /orders/{id} ile sitenizden çekilir.

İmza hesabı örneği#

İmzalanan metin: <zaman damgası> + . + <ham gövde> (gövde, gönderdiğiniz baytların aynısı olmalı).

Metin
gizli anahtar : ornek-gizli-anahtar-bunu-kullanmayin
zaman damgası : 1795430400
gövde         : {"event":"order.created","orderId":"10045"}
imzalanan     : 1795430400.{"event":"order.created","orderId":"10045"}
X-Efaturan-Signature: v1=85fdea76e81d9b9f77e4c7088d73a1bb4665d2ec6351b99f6639e3c18d3c1012
$body = json_encode(["event" => "order.created", "orderId" => "10045"]);
$ts = (string) time();
$sig = hash_hmac("sha256", $ts . "." . $body, $secret);
// Başlıklar: Content-Type: application/json, X-Efaturan-Timestamp: $ts, X-Efaturan-Signature: v1=$sig

Hata kodları

Sitenizin hata yanıtları#

Hata durumunda aşağıdaki gövdeyi döndürmeniz önerilir. message satıcının panelinde gösterilir (en çok 300 karakter); gizli bilgi yazmayın.

JSON
{ "error": { "code": "ORDER_NOT_FOUND", "message": "Sipariş bulunamadı." } }
Sitenizin yanıtıeFaturan ne yapar
2xxBaşarılı
30xHata: yönlendirme izlenmez
401 / 403"Kimlik doğrulaması başarısız" — satıcı API anahtarını kontrol eder; çekim durur, sonraki turda yeniden denenir
404"Uç noktası bulunamadı" (GET /orders/{id}'de: sipariş yok; POST /shipments'ta: bildirim bırakılır)
429Bekleyip yeniden dener (Retry-After)
5xx, zaman aşımıYeniden dener; olmazsa sonraki turda
JSON olmayan yanıtHata: Content-Type application/json olmalı

Anlık bildirim ucunun hata kodları#

Yanıt gövdesi: { "ok": false, "error": { "code": "…", "message": "…" } }.

HTTPKodAçıklama
202—Bildirim alındı; sipariş sitenizden çekilecek.
404UNKNOWN_STOREBildirim adresi tanınmadı.
415UNSUPPORTED_MEDIA_TYPEİçerik türü application/json olmalı.
413PAYLOAD_TOO_LARGEGövde en fazla 8 KB olabilir.
401TIMESTAMP_INVALIDX-Efaturan-Timestamp başlığı unix saniye olmalı.
401TIMESTAMP_OUT_OF_RANGEZaman damgası ±5 dakika penceresinin dışında.
401INVALID_SIGNATUREİmza doğrulanamadı.
409REPLAYEDBu bildirim daha önce alındı.
422INVALID_BODYGövde geçersiz: { event, orderId } bekleniyor.
409STORE_INACTIVEMağaza pasif ya da sipariş çekimi kapalı.
429RATE_LIMITEDÇok fazla bildirim; Retry-After süresi kadar bekleyin.

Sık sorulan sorular

Aynı sipariş birden çok kez gelirse ne olur?

Sipariş kimliğiyle (id) tekilleştirilir; faturası kesilmemişse son hâliyle güncellenir, ikinci fatura kesilmez.

Şahıs firmasını nasıl gönderirim?

customer.type: "company" ve taxNumber alanına sahibinin 11 haneli TCKN'si.

Dövizli siparişi nasıl gönderirim?

currency ile (ör. "USD"). USD/EUR'da kur TCMB'den alınır; diğer para birimlerinde exchangeRate gönderin.

Kısmi iade nasıl bildirilir?

5. bölümdeki refund örneğiyle. Belge kendiliğinden kesilmez; satıcı karar verir.

KDV oranını göndermezsem?

Sipariş "Eksik bilgi" olur ve faturalanmaz; satıcı mağazada "tüm ürünler tek KDV oranı" seçtiyse o oranla faturalanır.

Fatura linki ne zaman gelir?

Fatura GİB'e iletildikten sonra POST /invoices ile; bağlantı herkese açık PDF'tir.

Sitenizde açılan uçlar

eFaturan çağırır; siz yanıt verirsiniz.

6 uç
GET

Bağlantı sınaması

GEThttps://www.siteniz.com/api/efaturan/ping

Bu ucu siz açarsınız; eFaturan çağırır. Adres, sitenizin panele girilen kök adresine eklenir.

Açıklama

version, sitenizin uyguladığı protokol sürümüdür (önerilir).

İstek şeması

GET /ping istek şeması
AlanTipDurumAçıklama
X-Efaturan-Protocolbaşlık
metinİsteğe bağlıeFaturan'ın kullandığı protokol sürümü

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Hazırapplication/jsonPingResponse
401Geçersiz anahtarapplication/jsonError

Yanıt şeması

3 alan

GET /ping yanıt şeması
AlanTipDurumAçıklama
ok
trueZorunluUçlar hazırsa true.
store
metinİsteğe bağlı—en çok 200 karakter
version
metinİsteğe bağlıSitenizin uyguladığı protokol sürümü (ör. "1.1").en çok 10 karakter

Örnek uç ve istek

cURL, eFaturan'ın sitenize göndereceği isteği taklit eder; PHP, Node.js ve C# ucun iskeletidir.

# eFaturan'ın isteğini taklit eder; ucunuzu bununla sınayın.
curl "https://www.siteniz.com/api/efaturan/ping" \
  -H "Authorization: Bearer $EFATURAN_API_KEY" \
  -H "X-Efaturan-Protocol: 1.1"

Örnek yanıt

200 · application/json
{
  "ok": true,
  "store": "Mağaza adınız",
  "version": "1.1"
}
GET

Sipariş durumları

GEThttps://www.siteniz.com/api/efaturan/order-statuses

Bu ucu siz açarsınız; eFaturan çağırır. Adres, sitenizin panele girilen kök adresine eklenir.

Açıklama

Satıcı bu listeden "faturalanacak durumları" ve "kargo çıkınca sipariş durumunu" seçer.

İstek şeması

GET /order-statuses istek şeması
AlanTipDurumAçıklama
X-Efaturan-Protocolbaşlık
metinİsteğe bağlıeFaturan'ın kullandığı protokol sürümü

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Durumlarapplication/jsonStatusesResponse
401Geçersiz anahtarapplication/jsonError

Yanıt şeması

3 alan

GET /order-statuses yanıt şeması
AlanTipDurumAçıklama
dizi|nesneZorunlu—0–500 öğe

Örnek uç ve istek

cURL, eFaturan'ın sitenize göndereceği isteği taklit eder; PHP, Node.js ve C# ucun iskeletidir.

# eFaturan'ın isteğini taklit eder; ucunuzu bununla sınayın.
curl "https://www.siteniz.com/api/efaturan/order-statuses" \
  -H "Authorization: Bearer $EFATURAN_API_KEY" \
  -H "X-Efaturan-Protocol: 1.1"

Örnek yanıt

200 · application/json
{
  "statuses": [
    {
      "id": "2",
      "name": "Onay bekliyor"
    },
    {
      "id": "3",
      "name": "Ödendi"
    },
    {
      "id": "4",
      "name": "Kargoda"
    }
  ]
}
GET

Aralıkta oluşturulan veya güncellenen siparişler (sayfalı)

GEThttps://www.siteniz.com/api/efaturan/orders

Bu ucu siz açarsınız; eFaturan çağırır. Adres, sitenizin panele girilen kök adresine eklenir.

Açıklama

  • since ve until UTC ve Z ekli ISO 8601'dir (ör. 2026-11-20T09:00:00.000Z). Bu aralıkta oluşturulan veya güncellenen siparişleri döndürün. Aynı sipariş birden çok kez gelebilir; eFaturan sipariş kimliğiyle tekilleştirir.
  • Düzenli çekim son eşitlemeden 1 saat geriden başlar. Günde bir kez son N gün (satıcının mağaza ayarı, varsayılan 7, en çok 30) yeniden istenir; sonradan ödenen, iptal ya da iade edilen siparişler böyle yakalanır.
  • page 1'den başlar, pageSize 100'dür. Sayfalama: totalPages gönderirseniz ona uyulur. Göndermezseniz eFaturan, sayfa 100 siparişten kısa gelene kadar sonraki sayfayı ister. 100'den fazla sipariş dönen sayfa ya da bir önceki sayfanın aynısı olan sayfa çekimi durdurur ve satıcıya uyarı düşer. Tek çalıştırmada en çok 100 sayfa istenir; sınıra varılırsa satıcı uyarılır ve kalanlar sonraki çalıştırmada çekilir.
  • status: yalnızca satıcının eski "çekim süzgeci" ayarı seçiliyse gönderilir (virgülle ayrılmış durum kimlikleri). Süzgeci siteniz uygular; eFaturan dönen siparişleri ayrıca süzmez.
  • Yanıt: { "orders": [ … ], "page": 1, "totalPages": 3 }. Her sipariş ayrı doğrulanır; hatalı bir sipariş diğerlerini durdurmaz. Kimliği (id) olmayan kayıt alınamaz ve satıcıya uyarı düşer.

Örnek sipariş:

JSON
{
  "id": "10045",
  "number": "SP-10045",
  "status": "paid",
  "statusId": "3",
  "createdAt": "2026-10-08T10:15:00+03:00",
  "paidAt": "2026-10-08T10:16:12+03:00",
  "currency": "TRY",
  "pricesIncludeVat": true,
  "paymentMethod": "ODEMEARACISI",
  "paymentAgent": "iyzico",
  "customer": {
    "type": "company",
    "name": "Örnek Ltd. Şti.",
    "taxNumber": "1234567890",
    "taxOffice": "Kadıköy",
    "email": "muhasebe@ornek.com",
    "address": "Moda Cad. No:1",
    "district": "Kadıköy",
    "city": "İstanbul",
    "postalCode": "34710"
  },
  "shippingAddress": { "name": "Ayşe Yılmaz", "address": "Bağdat Cad. No:5", "district": "Kadıköy", "city": "İstanbul" },
  "items": [
    { "lineId": "1", "sku": "TS-1", "barcode": "8690000000001", "name": "Pamuklu Tişört", "quantity": 2, "unit": "C62", "unitPrice": 150.00, "vatRate": 20, "discount": 30.00 }
  ],
  "orderDiscount": 10.00,
  "fees": [
    { "type": "shipping", "amount": 29.90, "vatRate": 20 },
    { "type": "cod", "amount": 15.00, "vatRate": 20 }
  ],
  "total": 304.90,
  "invoiceNote": "Sipariş kanalı: web sitesi"
}

İstek şeması

GET /orders istek şeması
AlanTipDurumAçıklama
X-Efaturan-Protocolbaşlık
metinİsteğe bağlıeFaturan'ın kullandığı protokol sürümü
sincesorgu
tarih-saat (ISO 8601)ZorunluUTC, ör. 2026-11-20T09:00:00.000Z
untilsorgu
tarih-saat (ISO 8601)Zorunlu—
pagesorgu
tam sayıZorunlu—≥ 1
pageSizesorgu
100Zorunlu—
statussorgu
metinİsteğe bağlıVirgülle ayrılmış durum kimlikleri (yalnızca eski çekim süzgeci seçiliyse). Süzgeci siteniz uygular.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Sipariş sayfasıapplication/jsonOrdersResponse
401Geçersiz anahtarapplication/jsonError
429Çok fazla istek (Retry-After başlığına uyulur, en çok 10 sn)application/jsonError

Yanıt şeması

73 alan

GET /orders yanıt şeması
AlanTipDurumAçıklama
dizi|nesne (Order)Zorunlu—
page
tam sayıİsteğe bağlı—
totalPages
tam sayıİsteğe bağlıGönderilmezse eFaturan, sayfa pageSize'dan kısa gelene kadar sonraki sayfayı ister.

Örnek uç ve istek

cURL, eFaturan'ın sitenize göndereceği isteği taklit eder; PHP, Node.js ve C# ucun iskeletidir.

# eFaturan'ın isteğini taklit eder; ucunuzu bununla sınayın.
curl "https://www.siteniz.com/api/efaturan/orders?since=2026-11-20T08:00:00.000Z&until=2026-11-20T09:00:00.000Z&page=1&pageSize=100" \
  -H "Authorization: Bearer $EFATURAN_API_KEY" \
  -H "X-Efaturan-Protocol: 1.1"

Örnek yanıt

200 · application/json
{
  "orders": [
    {
      "id": "10045",
      "number": "SP-10045",
      "status": "paid",
      "statusId": "3",
      "createdAt": "2026-10-08T10:15:00+03:00",
      "paidAt": "2026-10-08T10:16:12+03:00",
      "currency": "TRY",
      "pricesIncludeVat": true,
      "paymentMethod": "ODEMEARACISI",
      "paymentAgent": "iyzico",
      "customer": {
        "type": "company",
        "name": "Örnek Ltd. Şti.",
        "taxNumber": "1234567890",
        "taxOffice": "Kadıköy",
        "email": "muhasebe@ornek.com",
        "address": "Moda Cad. No:1",
        "district": "Kadıköy",
        "city": "İstanbul",
        "postalCode": "34710"
      },
      "shippingAddress": {
        "name": "Ayşe Yılmaz",
        "address": "Bağdat Cad. No:5",
        "district": "Kadıköy",
        "city": "İstanbul"
      },
      "items": [
        {
          "lineId": "1",
          "sku": "TS-1",
          "barcode": "8690000000001",
          "name": "Pamuklu Tişört",
          "quantity": 2,
          "unit": "C62",
          "unitPrice": 150,
          "vatRate": 20,
          "discount": 30
        }
      ],
      "orderDiscount": 10,
      "fees": [
        {
          "type": "shipping",
          "amount": 29.9,
          "vatRate": 20
        },
        {
          "type": "cod",
          "amount": 15,
          "vatRate": 20
        }
      ],
      "total": 304.9,
      "invoiceNote": "Sipariş kanalı: web sitesi"
    }
  ],
  "page": 1,
  "totalPages": 1
}
GET

Tek sipariş (v1.1; anlık bildirim kullanan sitelerde gerekli)

GEThttps://www.siteniz.com/api/efaturan/orders/{id}

Bu ucu siz açarsınız; eFaturan çağırır. Adres, sitenizin panele girilen kök adresine eklenir.

Açıklama

Tek siparişi döndürür: { "order": { … } } (alanlar /orders ile aynı). Sipariş yoksa 404. Anlık bildirim kullanıyorsanız zorunludur; dönen siparişin id'si istenen kimlikle aynı olmalıdır.

İstek şeması

GET /orders/{id} istek şeması
AlanTipDurumAçıklama
X-Efaturan-Protocolbaşlık
metinİsteğe bağlıeFaturan'ın kullandığı protokol sürümü
idyol
metinZorunlu—

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Siparişapplication/json
404Sipariş yok (ORDER_NOT_FOUND)application/jsonError

Yanıt şeması

71 alan

GET /orders/{id} yanıt şeması
AlanTipDurumAçıklama
nesne (Order)Zorunlu—

Örnek uç ve istek

cURL, eFaturan'ın sitenize göndereceği isteği taklit eder; PHP, Node.js ve C# ucun iskeletidir.

# eFaturan'ın isteğini taklit eder; ucunuzu bununla sınayın.
ID="…"
curl "https://www.siteniz.com/api/efaturan/orders/$ID" \
  -H "Authorization: Bearer $EFATURAN_API_KEY" \
  -H "X-Efaturan-Protocol: 1.1"

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "order": {
    "id": "…",
    "number": "…",
    "status": "created",
    "statusId": "…",
    "createdAt": "2026-11-20T08:00:00.000Z",
    "paidAt": "2026-11-20T09:00:00.000Z",
    "currency": "…",
    "exchangeRate": 1,
    "pricesIncludeVat": false,
    "paymentMethod": "KREDIKARTI/BANKAKARTI",
    "paymentAgent": "…",
    "customer": {
      "type": "individual",
      "name": "…",
      "taxNumber": "…",
      "taxOffice": "…",
      "email": "…",
      "phone": "…",
      "address": "…",
      "district": "…",
      "city": "…",
      "postalCode": "…",
      "country": "…"
    },
    "shippingAddress": {
      "name": "…",
      "company": "…",
      "phone": "…",
      "email": "…",
      "address": "…",
      "neighborhood": "…",
      "district": "…",
      "city": "…",
      "postalCode": "…",
      "country": "…"
    },
    "shipping": {
      "fee": 0,
      "carrier": "…",
      "trackingNumber": "…",
      "shippedAt": "2026-11-20T09:00:00.000Z"
    },
    "items": [
      {
        "lineId": "…",
        "sku": "…",
        "barcode": "…",
        "name": "…",
        "quantity": 1,
        "unit": "C62",
        "unitPrice": 0,
        "vatRate": 0,
        "discount": 0
      }
    ],
    "orderDiscount": 0,
    "fees": [
      {
        "type": "shipping",
        "name": "…",
        "amount": 0,
        "vatRate": 0
      }
    ],
    "total": 0,
    "note": "…",
    "invoiceNote": "…",
    "invoiced": false,
    "marketplace": "…",
    "refund": {
      "type": "cancel",
      "scope": "full",
      "amount": 0,
      "lines": [
        {
          "lineId": "…",
          "sku": "…",
          "quantity": 1
        }
      ],
      "reason": "…",
      "at": "2026-11-20T09:00:00.000Z"
    }
  }
}
POST

Kesilen faturanın bildirimi

POSThttps://www.siteniz.com/api/efaturan/invoices

Bu ucu siz açarsınız; eFaturan çağırır. Adres, sitenizin panele girilen kök adresine eklenir.

Açıklama

Fatura kesilip GİB'e iletildikten sonra (satıcı ayarı açıksa) gönderilir. 2xx dönün; aynı sipariş için tekrar gelirse yine 2xx dönün. Başarısız iletim 7 gün boyunca düzenli aralıklarla yeniden denenir.

AlanTürZorunlulukAçıklama
orderIdmetin (≤ 64)zorunluSipariş kimliği
invoiceNumbermetin (≤ 16)zorunluFatura no
uuidmetinzorunluETTN
issueDatetarih (YYYY-AA-GG)zorunluFatura tarihi. YYYY-AA-GG, Türkiye saatiyle.
urlmetinisteğe bağlıFatura bağlantısı. Herkese açık PDF bağlantısı (…/f/<anahtar>.pdf).
totalsayı (ondalık)zorunluTutar. Fatura ödenecek tutarı, ondalık.
currencymetinzorunluPara birimi

İstek şeması

application/json · gövde zorunlu

POST /invoices istek şeması
AlanTipDurumAçıklama
X-Efaturan-Protocolbaşlık
metinİsteğe bağlıeFaturan'ın kullandığı protokol sürümü
orderId
metinZorunlu—en çok 64 karakter
invoiceNumber
metinZorunlu—en çok 16 karakter
uuid
metinZorunlu—
issueDate
tarih (YYYY-AA-GG)ZorunluYYYY-AA-GG, Türkiye saatiyle.
url
metinİsteğe bağlıHerkese açık PDF bağlantısı (…/f/<anahtar>.pdf).
total
sayıZorunluFatura ödenecek tutarı, ondalık.
currency
metinZorunlu—

Yanıtlar

Yanıt kodları
KodNe zamanGövde
2XXAlındı (aynı sipariş tekrar gelirse de 2xx)gövde yok

Örnek uç ve istek

cURL, eFaturan'ın sitenize göndereceği isteği taklit eder; PHP, Node.js ve C# ucun iskeletidir.

# eFaturan'ın isteğini taklit eder; ucunuzu bununla sınayın.
curl -X POST "https://www.siteniz.com/api/efaturan/invoices" \
  -H "Authorization: Bearer $EFATURAN_API_KEY" \
  -H "X-Efaturan-Protocol: 1.1" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "10045",
    "invoiceNumber": "ABC2026000000123",
    "uuid": "2f7a0c1e-…",
    "issueDate": "2026-10-08",
    "url": "https://efaturan.com/f/…pdf",
    "total": 304.9,
    "currency": "TRY"
  }'
POST

Kargo gönderisinin bildirimi (v1.1; mağaza ayarı açıksa)

POSThttps://www.siteniz.com/api/efaturan/shipments

Bu ucu siz açarsınız; eFaturan çağırır. Adres, sitenizin panele girilen kök adresine eklenir.

Açıklama

Satıcı "kargo bilgisi sitenize iletilsin" seçtiyse, siparişe takip numaralı kargo gönderisi oluşunca gönderilir. Her gönderi bir kez bildirilir. setStatusId yalnızca satıcı "kargo çıkınca sipariş durumu" seçtiyse gelir; siparişi bu duruma siz geçirirsiniz. 2xx dönün. Başarısız bildirim en çok 8 kez, 5 dakikadan başlayıp iki katına çıkan aralıklarla (en çok 12 saat) ve gönderiden sonra en çok 7 gün denenir; 404, 405, 410 ya da yönlendirme yanıtında bırakılır.

AlanTürZorunlulukAçıklama
orderIdmetin (≤ 64)zorunluSipariş kimliği
carriermetinzorunluKargo firması. Firmanın adı (ör. "Yurtiçi Kargo").
carrierCodemetinzorunluKargo firması kodu. eFaturan'daki kısa kod (ör. "yurtici").
trackingNumbermetinzorunluTakip no
trackingUrlmetinisteğe bağlıTakip adresi
shippedAttarih-saat (ISO 8601, saat dilimli)zorunluTarih. Gönderinin oluşturulduğu an (ISO 8601, UTC).
setStatusIdmetinisteğe bağlıYeni durum kimliği. Satıcı "kargo çıkınca sipariş durumu" seçtiyse sitenizin bu durum kimliğine geçirmesi istenir.

İstek şeması

application/json · gövde zorunlu

POST /shipments istek şeması
AlanTipDurumAçıklama
X-Efaturan-Protocolbaşlık
metinİsteğe bağlıeFaturan'ın kullandığı protokol sürümü
orderId
metinZorunlu—en çok 64 karakter
carrier
metinZorunluFirmanın adı (ör. "Yurtiçi Kargo").
carrierCode
metinZorunlueFaturan'daki kısa kod (ör. "yurtici").
trackingNumber
metinZorunlu—
trackingUrl
metinİsteğe bağlı—
shippedAt
tarih-saat (ISO 8601)ZorunluGönderinin oluşturulduğu an (ISO 8601, UTC).
setStatusId
metinİsteğe bağlıSatıcı "kargo çıkınca sipariş durumu" seçtiyse sitenizin bu durum kimliğine geçirmesi istenir.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
404Uç yok: bildirim yeniden denenmezapplication/jsonError
2XXAlındı (aynı gönderi tekrar gelirse de 2xx)gövde yok

Örnek uç ve istek

cURL, eFaturan'ın sitenize göndereceği isteği taklit eder; PHP, Node.js ve C# ucun iskeletidir.

# eFaturan'ın isteğini taklit eder; ucunuzu bununla sınayın.
curl -X POST "https://www.siteniz.com/api/efaturan/shipments" \
  -H "Authorization: Bearer $EFATURAN_API_KEY" \
  -H "X-Efaturan-Protocol: 1.1" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "10045",
    "carrier": "Yurtiçi Kargo",
    "carrierCode": "yurtici",
    "trackingNumber": "123456789",
    "trackingUrl": "https://…",
    "shippedAt": "2026-10-09T06:00:00.000Z",
    "setStatusId": "4"
  }'

eFaturan'ın ucu

Siteniz çağırır.

1 uç
POST

Anlık bildirim (site → eFaturan, v1.1)

POSThttps://panel.efaturan.com/api/hooks/custom/{storeKey}

HMAC-SHA256 imzalı. Gövde en çok 8 KB; zaman damgası ±5 dk. Gövdeden yalnızca orderId kullanılır.

Ayrıntılar: Anlık bildirim

İstek şeması

application/json · gövde zorunlu

POST /api/hooks/custom/{storeKey} istek şeması
AlanTipDurumAçıklama
storeKeyyol
metinZorunluPaneldeki bildirim adresinin son bölümü
X-Efaturan-Timestampbaşlık
metinZorunluUnix saniyebiçim: ^\d{10}$
X-Efaturan-Signaturebaşlık
metinZorunluv1=hex(HMAC-SHA256(gizli anahtar, "<zaman damgası>.<ham gövde>"))biçim: ^v1=[0-9a-f]{64}$
event
"order.created"|"order.updated"|"order.cancelled"|"order.returned"Zorunlu—
orderId
metinZorunluHarf, rakam ve . _ : - (en çok 64). Gövdeden yalnızca bu alan kullanılır; sipariş eFaturan tarafından GET /orders/{id} ile sitenizden çekilir.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
202Alındı; sipariş sitenizden çekilecekgövde yok
401TIMESTAMP_INVALID, TIMESTAMP_OUT_OF_RANGE, INVALID_SIGNATUREapplication/jsonHookError
404UNKNOWN_STOREapplication/jsonHookError
409REPLAYED, STORE_INACTIVEapplication/jsonHookError
413PAYLOAD_TOO_LARGEapplication/jsonHookError
415UNSUPPORTED_MEDIA_TYPEapplication/jsonHookError
422INVALID_BODYapplication/jsonHookError
429RATE_LIMITEDapplication/jsonHookError

Örnek istek

İmza gizli anahtarla hesaplanır; anahtarı ortam değişkeninden okuyun.

STORE_KEY="…" # Paneldeki bildirim adresinin son bölümü
BODY='{"event":"order.created","orderId":"…"}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$EFATURAN_HOOK_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://panel.efaturan.com/api/hooks/custom/$STORE_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Efaturan-Timestamp: $TS" \
  -H "X-Efaturan-Signature: v1=$SIG" \
  -d "$BODY"