API ile e-Fatura Entegrasyonu

Kısaca

Belge türünü (e-Fatura / e-Arşiv) gönderim anındaki güncel mükellefiyet sorgusuyla belirleyin.
Fatura tarihini 7 gün kuralına göre verin (VUK m.231/5); geç kalan siparişte tarihi sessizce geriye atmayın.
İnternet satışında web adresi, ödeme ve taşıyıcı bilgilerini gönderin (VUK 509).
Tekillik anahtarı ile çift faturayı, webhook ile durum takibini çözün.

1. Hazırlık: hesabınız fatura kesmeye hazır mı?

API çağrısı yapmadan önce firmanın e-Fatura ve e-Arşiv kullanıcısı olduğundan, fatura şablonunun yayında olduğundan, firma bilgilerinin (adres, vergi dairesi) tam olduğundan ve kontör bulunduğundan emin olun. Faturika'da GET /account bu koşulları tek çağrıda döndürür; eksik varsa blockers[] listesi ne yapılacağını söyler. Kurulum ekranınızda bu listeyi göstermek, destek taleplerinin çoğunu önler.

2. Doğru belge türü: e-Fatura mı, e-Arşiv mi?

Alıcı GİB'in e-Fatura kayıtlı kullanıcı listesindeyse belge e-Fatura olarak alıcının posta kutusuna gider; listede değilse e-Arşiv düzenlenir. Mükellefiyet her gün değişebilir: dün e-Arşiv kestiğiniz müşteri bugün e-Fatura kullanıcısı olmuş olabilir. Bu yüzden kararı cari kaydınızdaki eski bir işarete göre değil, gönderim anındaki sorguya göre verin. Faturika'da POST /taxpayers/query mükellefiyeti, unvanı ve önerilen belge türünü döndürür.

Bireysel alıcının TC kimlik numarası bilinmiyorsa nihai tüketici numarası (11111111111) kullanılır; yurt dışı alıcıda ülke bilgisini gönderin.

3. Tarih: 7 gün kuralı

Vergi Usul Kanunu'nun 231. maddesinin 5. bendine göre fatura, malın teslimi ya da hizmetin yapıldığı tarihten itibaren azami yedi gün içinde düzenlenir; bu süre içinde düzenlenmeyen fatura hiç düzenlenmemiş sayılır. Entegrasyonda bunun anlamı:

Ödeme ya da teslim bugünden 7 gün içindeyse belge o güne kesilebilir.
Daha eskiyse tarih ya kullanıcının bilgisiyle bu sürenin içine çekilir ya da kullanıcı riski açıkça onaylar. Sessizce eski tarihle göndermek de, sessizce bugüne çekmek de yanlıştır.
Aynı seride daha büyük numaralı fatura daha eski tarih taşıyamaz; geç açılan taslakların tarihi serideki son faturadan önce olmamalıdır.

Faturika bu kontrolleri gönderimde yapar; geç kalan taslağın tarihi PATCH /documents/{uuid} ile yerinde güncellenir.

4. İnternet satışı bilgileri

İnternet üzerinden satışta VUK Genel Tebliği Sıra No 509 kapsamında faturada satışın yapıldığı web adresi, ödeme şekli ve tarihi, kargolu gönderide taşıyıcının unvanı ve vergi numarası gibi bilgiler bulunmalı ve e-Arşiv fatura alıcıya elektronik ortamda iletilmelidir. Mağazanızdan gelen siparişte bu bilgileri belgeyle birlikte gönderin. Ayrıntı: internet satışında e-Arşiv rehberi.

5. Çift faturayı önleyin

Ağ zaman aşımında istemci isteğin ulaşıp ulaşmadığını bilemez; körlemesine yeniden denemek aynı siparişe iki fatura keser. Her belge isteğine siparişe özgü bir tekillik anahtarı ekleyin (ör. Idempotency-Key: siparis-10245). Faturika aynı anahtarla gelen ikinci isteği yeniden işlemez, ilk sonucun kendisini döndürür.

6. Durumu izleyin: gönderim asenkrondur

Gönderim isteği belgeyi kuyruğa alır; e-Belge sistemindeki sonuç sonra gelir. Belgeyi müşterinize "kesildi" diye göstermeden önce onaylandığını görün. İki yol vardır: belge detayını makul aralıklarla (bir dakikadan sık değil) sorgulamak ya da webhook ile durum değişikliğini anında almak. Webhook alan ucunuz imzayı doğrulamalı, eski zaman damgalı istekleri reddetmeli ve aynı teslimat kimliği iki kez gelirse ikinciyi yok saymalıdır.

7. Hataları kullanıcıya anlaşılır gösterin

Gönderim öncesi doğrulamada takılan belge kodlu bir hatayla döner ve kontör harcamaz. Mesajları kendi ekranınızda gösterin; onay isteyen uyarıları (ör. 7 günden eski tarih) kullanıcının kararına bırakın. Başarısız belgeyi düzeltip yeniden gönderebilir ya da silebilirsiniz.

8. İade ve iptal

e-Arşiv: hatalı belge iptal edilir; iptal geri alınamaz, gerekçe kaydedin.
e-Fatura: satıcı tek taraflı iptal edemez; alıcı ticari faturayı reddeder ya da iade faturası düzenlenir. Ayrıntı: fatura iptali ve itiraz, iade faturası.

Kod yazmadan başlamak

Faturika'nın e-Fatura API'si bu listedeki her adımı destekler ve ek ücret gerektirmez. Hosting ve abonelik işletmeleri için WHMCS modülü, WordPress mağazaları için WooCommerce eklentisi bu kuralları hazır uygular ve ücretsizdir.

Sık sorulan sorular

e-Faturayı API ile kesmek için ne gerekir?

Bir e-belge hesabı (e-Fatura ve e-Arşiv kullanıcılığı), yayında bir fatura şablonu, yeterli kontör ve API anahtarı. Faturika'da hazırlık ucu bu dört koşulu tek çağrıda kontrol eder.

Alıcıya e-Fatura mı e-Arşiv mi keseceğimi nasıl bilirim?

Alıcı GİB'in e-Fatura kayıtlı kullanıcı listesindeyse e-Fatura, değilse e-Arşiv düzenlenir. Liste her gün değişebildiği için karar, gönderim anındaki güncel sorguyla verilmelidir; eski bir kayda güvenmek yanlış belge türüne yol açar.

Geç ödenen siparişin faturası hangi tarihle kesilir?

VUK m.231/5'e göre fatura, malın teslimi ya da hizmetin yapıldığı tarihten itibaren azami yedi gün içinde düzenlenir. Entegrasyon, 7 günden eski bir tarihle belge göndermemeli; tarihi bu süre içine çekmeli ya da kullanıcıdan açık onay almalıdır.

Aynı siparişe iki fatura kesilmesini nasıl önlerim?

Her belge isteğine siparişe özgü bir tekillik anahtarı (Idempotency-Key) ekleyin. Zaman aşımında aynı anahtarla yeniden denediğinizde ikinci belge açılmaz.

Belgenin onaylandığını nasıl anlarım?

Gönderim asenkrondur: istek belgeyi kuyruğa alır, sonuç sonra gelir. Durumu belge detayını sorgulayarak ya da webhook ile öğrenirsiniz; onaylanana dek belgeyi müşteriye "kesildi" diye göstermeyin.

Kaynaklar

Son gözden geçirme: 28.09.2026. Bu içerik genel bilgilendirme amaçlıdır; mevzuat değişebilir. Kendi durumunuz için mali müşavirinize danışın.