Eafatura.com API
Eafatura.com API
v2.0 Fatura İşlemleri / Webhook Servisi

Webhook Servisi

Faturanız hazır olduğunda ya da bir sorun çıktığında Eafatura, belirlediğiniz Webhook URL adresine otomatik bildirim gönderir. Böylece fatura durumunu sürekli sormanız gerekmez.

Bilgilendirme
  • • create-invoice yanıtındaki pdf_url adresi, PDF dosyası üretilene kadar açılmaz. PDF hazır olduğunda invoice.pdf_ready olayı gelir.
  • • Bildirimler belirlediğiniz adrese JSON gövdeli POST isteği olarak iletilir. Adres https olmalıdır.
  • • Her istek, panelinizdeki Webhook Secret ile HMAC-SHA256 imzalanır. İmzayı doğrulamadan gelen isteğe güvenmeyin.
  • • Endpointiniz başarılı işlemde 2xx yanıt vermelidir. Aksi halde teslimat otomatik yeniden denenir; aynı olay birden fazla kez gelebilir, id ile tekilleştirin.
  • • Webhook alanını panelden tanımlarsınız; Test Olayı Gönder düğmesiyle canlı fatura kesmeden deneyebilirsiniz.
POST https://siteniz.com/webhooks/eafatura
Kopyalandı

Olaylar

Fatura PDF dosyası üretildi; data.pdf_url artık açılır. Bu olay e-arşiv ve e-fatura, satış ve iade faturaları için aynıdır.

Fatura oluşturuldu ancak PDF dosyası üretilemedi ve yeniden deneme hakkı bitti. Fatura belgesi geçerlidir; yalnızca PDF dosyası yoktur. Ayrıntı data.reason ve data.message alanlarındadır.

Panelden “Test Olayı Gönder” ile gönderilen örnek olaydır; data alanı gerçek bir invoice.pdf_ready olayının alanlarını taşır (ek olarak sample_of). Tek denemedir, yeniden denenmez.

Webhook adresini panelden kaydederken adresinizin ulaşılabilir olduğunu doğrulamak için bir kez gönderilir. Aynı imza ile gelir.

Olay Gövdesi

Her olay aynı zarfla gelir. Yeni alanlar eklenebilir; mevcut alanlar silinmez ya da yeniden adlandırılmaz. Bilmediğiniz alanları yok sayın.

Olayın benzersiz kimliğidir (X-Eafatura-Delivery başlığıyla aynı). Yeniden denemelerde ve “tekrar gönder”de değişmez: işlediğiniz olayları bu kimlikle tekilleştirin.

Olay türü: invoice.pdf_ready, invoice.failed, webhook.test, ping.

Gövde biçiminin sürümü. Şu an 2.0.

Olayın oluşturulma zamanı (ISO 8601, saat dilimi ile).

Olaya göre değişen ayrıntılar. Fatura olaylarında şu alanlar bulunur:

  • • document_number: faturanın belge numarası
  • • ettn: faturanın ETTN (UUID) değeri
  • • order_number: sipariş numarası; yoksa null (iade faturalarında olmaz)
  • • invoice_type: satis, istisna ya da iade
  • • document_kind: e_arsiv ya da e_fatura
  • • pdf_url: yalnızca invoice.pdf_ready; PDF dosyasının adresi
  • • reason, message: yalnızca invoice.failed; neden kodu (şu an pdf_generation_failed) ve açıklama

Header Parametreleri

İmza: t=<unix zamanı>,v1=<imza>. Her denemede zaman damgası yenilenir.

Olay türü (gövdedeki type ile aynı).

Olay kimliği (gövdedeki id ile aynı). Tekilleştirme için kullanın.

application/json ve EafaturaAPI-Webhook/2.0.

İmza Doğrulama

Webhook Secret, panelinizde (API Bilgileri) gösterilir. İmza şöyle hesaplanır:

  1. X-Eafatura-Signature başlığından t (zaman) ve v1 (imza) değerlerini ayırın. Birden fazla v1 olabilir.
  2. Ham istek gövdesini (JSON'a çevirmeden, olduğu gibi) alın ve t + "." + gövde metnini oluşturun.
  3. Bu metnin HMAC-SHA256 değerini Webhook Secret ile hesaplayın (onaltılık/hex).
  4. Sonucu başlıktaki v1 değerlerinden biriyle sabit zamanlı karşılaştırın.
  5. t değeri şu andan 5 dakikadan fazla farklıysa isteği reddedin (yakalanmış bir isteğin tekrar oynatılmasını önler).

Secret yenileme: Panelden secret'ı yenilediğinizde eski secret 24 saat boyunca da imzaya eklenir; başlıkta iki v1 bulunur. Yeni secret'ı kendi sisteminize bu sürede kesintisiz alabilirsiniz. Secret'ı kimseyle paylaşmayın ve kodunuza ya da günlüklerinize yazmayın.

Teslimat ve Yeniden Deneme

  • • Başarı: 2xx yanıt. Yanıtınız 10 saniye içinde gelmelidir; ağır işleri kuyruğa alıp hemen 2xx dönün. Yönlendirmeler (3xx) izlenmez ve başarısız sayılır.
  • • Yeniden deneme: Başarısız teslimat 1 dk, 5 dk, 30 dk, 2 saat ve 12 saat sonra yeniden denenir (toplam 6 deneme). Hepsi başarısız olursa teslimat “Başarısız” kalır; panelden Tekrar gönder diyebilirsiniz.
  • • Tekilleştirme: Ağ sorunları nedeniyle aynı olay birden fazla kez gelebilir. İşlediğiniz id değerlerini saklayın; tekrar gelirse yine 2xx dönüp yok sayın.
  • • Sıra: Olayların gönderim sırası garanti edilmez. Sıraya ihtiyacınız varsa created_at değerini kullanın.
  • • Devre kesici: Art arda 30 başarısız denemeden sonra adresiniz devre dışı bırakılır ve mobil uygulamanıza bildirim gider. Olaylar kaybolmaz; sorunu giderip panelden yeniden etkinleştirdiğinizde gönderilir.
  • • Adres kuralları: Adres https olmalı, herkese açık bir alan adına çözülmeli (IP adresi, yerel ağ ve iç adresler kabul edilmez) ve en fazla 500 karakter olmalıdır.
  • • Teslimat geçmişi: Panelde son teslimatları, gönderilen içeriği, her denemenin sonucunu ve yanıtınızın ilk kısmını görebilirsiniz.

Kod Örnekleri


        

    






    
Endpointinizin Yanıtı