e-Fatura API

Neler yapılabilir?

Desteklenen fatura türleri: satış, iade, tevkifat, tevkifatlı iade, istisna, özel matrah ve ihraç kayıtlı. Döviz olarak TL, USD, EUR ve GBP; e-Arşiv'de internet satışı bilgileri (web adresi, ödeme şekli ve tarihi, taşıyıcı) ayrı bir blokla gönderilir.

İlk fatura: tek istek

Aşağıdaki istek bireysel bir müşteriye e-Arşiv faturasını oluşturur ve gönderir. Aynı Idempotency-Key ile tekrarlanan istek ikinci bir fatura açmaz.

curl -X POST https://faturika.com/papi/v1/documents/send \
  -H "X-Api-Key: ftk_live_…" \
  -H "Idempotency-Key: siparis-10245" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "earchive",
    "invoice_type_code": "SATIS",
    "issue_date": "2026-09-28",
    "contact": {"title": "Ayşe Yılmaz", "tax_number": "11111111111", "email": "ayse@example.com"},
    "lines": [{"name": "Yıllık hosting", "quantity": 1, "unit_code": "C62", "unit_price": 1000, "vat_rate": 20}]
  }'

Belge önce kuyruğa girer; resmîleşince durumu approved olur. Sonucu GET /documents/{uuid} ile sorgulayabilir ya da webhook'la anında alabilirsiniz.

Hatayı gönderimden önce yakalar

Belge e-Belge sistemine gitmeden önce Faturika'da doğrulanır: alıcı kimlik numarasının uzunluğu ve kontrol basamağı, fatura numarası ile tarih sırası, 7 günlük düzenleme süresi, fatura türüyle vergi uyumu. Düzeltilmesi gereken durum 422 validation_failed ve kodlu bir bulguyla döner; bu durumda kontör düşmez. Onay gerektiren uyarılarda (ör. 7 günden eski tarih) aynı isteği gerekçeyle yeniden gönderirsiniz.

Başarısız her yanıt aynı zarfı taşır: {"code": "…", "message": "…"}. Mesaj Türkçedir ve son kullanıcıya gösterilebilir.

Webhook: durum sizi bulsun

Panelde bir adres tanımladığınızda şu olaylar JSON olarak gönderilir: document.sent, document.status_changed, payment.recorded, incoming.received. Her istek X-Faturika-Signature-V2 başlığında zaman damgalı HMAC-SHA256 imzası taşır; eski bir isteğin yeniden oynatılmasını 5 dakikalık pencereyle reddedersiniz. 2xx dışı yanıtta teslimat artan aralıklarla toplam 5 kez denenir; tekrarları X-Faturika-Delivery kimliğiyle ayıklarsınız.

Güvenlik ve sınırlar

• Anahtar başına dakikada 60 istek; aşımda 429 ve Retry-After başlığı.
• Anahtarlar panelden oluşturulur ve iptal edilir; her anahtar yalnız kendi firmasının verisine erişir.
• Webhook adresleri yalnız internetten erişilebilir adreslere gider; yönlendirme izlenmez.
• API'de de panelle aynı iş kuralları geçerlidir: seri tarih sırası, 7 gün kuralı, iade faturasında kaynak belge.

Belgeler ve hazır modüller

Kaydolduktan sonra Ayarlar → Entegrasyon → Modüller ve API Belgesi bölümünden OpenAPI 3.1 tanımını (YAML ve JSON) ve tüm uçları, alanları, hata kodlarını ve iş kurallarını anlatan entegrasyon rehberini indirirsiniz. Tanımı Postman, Insomnia ya da Swagger'a aktarıp istemci kodu üretebilirsiniz.

Kod yazmak istemiyorsanız ücretsiz modüllerle başlayın: WHMCS e-Fatura modülü hosting ve abonelik işletmeleri için, WooCommerce e-Fatura eklentisi WordPress mağazaları için. Trendyol Pazaryeri siparişleri için pazaryeri entegrasyonu panelde hazırdır.

Faturalarınızın görünümü API'den bağımsız olarak fatura şablonu editöründe tasarlanır; API ile kestiğiniz belge de logonuzu ve renklerinizi taşır.

Sık sorulan sorular

İlgili sayfalar