E-fatura entegrasyonu: kurarken karşılaşacağınız yedi sorun

E-fatura entegrasyonu dokümantasyonda basit görünür: fatura verisini gönderirsiniz, karşılık gelen belge oluşur. Uygulamada zaman kaybettiren şey uç durumlardır. Bu yazı, birden fazla pazaryeri platformu için e-fatura entegrasyonu kurarken karşılaştığımız yedi noktayı topluyor.

1. E-fatura mı, e-arşiv mi?

Alıcı e-fatura mükellefiyse e-fatura, değilse e-arşiv düzenlenir. Bu ayrımı satış anında yapmanız gerekir ve karar alıcının vergi numarasına bağlıdır.

Yapılacak: her fatura öncesi mükellef sorgusu çalıştırın, sonucu önbelleğe alın ama süresiz tutmayın. Mükellefiyet durumu değişebilir; günlük yenilenen bir önbellek makul bir dengedir.

2. Senaryo ve fatura tipi seçimi

Temel fatura, ticari fatura, iade, tevkifatlı, istisna... Yanlış senaryo seçilen fatura alıcı tarafından reddedilir ve düzeltmesi manuel iş çıkarır.

Karar tablosunu koda gömmeyin; yapılandırılabilir bırakın. Mevzuat değiştiğinde dağıtım yapmadan güncelleyebilmeniz gerekir.

3. Yuvarlama farkları

En sık karşılaşılan ret sebeplerinden biri. Satır bazında hesaplanan KDV toplamı ile toplam üzerinden hesaplanan KDV birbirini tutmayabilir; aradaki bir kuruşluk fark faturayı geçersiz kılar.

// Yanlış: her satırda ayrı yuvarlama, sonra topla
const kdv = satirlar.reduce((t, s) => t + Math.round(s.tutar * s.oran) / 100, 0)

// Doğru: hesabı kuruş cinsinden tamsayıyla yap, sonda bir kez yuvarla
// (float aritmetiği para hesabında kullanılmaz)
const kdvKurus = satirlar.reduce(
  (toplam, s) => toplam + Math.round((s.tutarKurus * s.oranBinde) / 1000),
  0
)

// Satır toplamları ile genel toplam arasındaki farkı gönderim öncesi doğrula
if (Math.abs(kdvKurus - beklenenKdvKurus) > 1) {
  throw new Error('KDV tutarsizligi: fatura gonderilmeden once incelenmeli')
}

4. İptal ve düzeltme pencereleri

E-arşiv faturası belirli bir süre içinde iptal edilebilir; e-fatura ise gönderildikten sonra iptal edilemez, iade faturası kesilmesi gerekir. Bu ayrımı uygulamanızın bilmesi ve kullanıcıya doğru seçeneği göstermesi gerekir.

Sık yapılan hata: arayüzde her fatura için "iptal et" düğmesi göstermek. Kullanıcı basar, sağlayıcı reddeder, kimse ne olduğunu anlamaz.

5. Aynı faturanın iki kez kesilmesi

Ağ zaman aşımı yaşandığında isteğin karşı tarafa ulaşıp ulaşmadığını bilemezsiniz. Yeniden denerseniz mükerrer fatura riski doğar.

Çözüm: her fatura için kendi tarafınızda benzersiz bir anahtar üretin ve gönderimde taşıyın. Yeniden denemede aynı anahtar kullanılır; sağlayıcı bunu tekrar olarak tanır. Sağlayıcı idempotency desteklemiyorsa, yeniden denemeden önce belge numarasıyla sorgu atıp durumu doğrulayın.

6. Hata mesajlarını olduğu gibi göstermeyin

Sağlayıcıdan dönen hata kodları teknik ve çoğu zaman anlaşılmaz. Bunları kullanıcıya doğrudan yansıtmak destek yükü üretir.

Sık görülen kodları eşleyip anlaşılır mesaja çevirin, teknik detayı loga yazın. Eşlenmemiş kod için genel bir mesaj gösterin ama log kaydına referans numarası koyun — destek ekibi o numarayla gerçek hatayı bulabilsin.

7. Mutabakat işi olmadan sistem eksiktir

Kaçınılmaz olarak bazı faturalar arada kalır: gönderildi sanılan ama oluşmayan, oluşan ama sizin kayıtta işaretlenmeyen. Bunları elle fark etmek imkânsızdır.

Günlük çalışan bir mutabakat işi kurun: kendi kayıtlarınızdaki fatura listesiyle sağlayıcıdaki listeyi karşılaştırsın, farkları rapor etsin. Bu iş, entegrasyonun kendisi kadar önemlidir ve genelde en son yazılıp ilk unutulan parçadır.

Test ortamından canlıya

1. Test ortamında her senaryo tipini en az bir kez uçtan uca geçirin — temel, ticari, iade, istisna.
2. Yuvarlama sınırlarını özellikle test edin: küsuratlı adet, çoklu KDV oranı, indirimli satır.
3. Zaman aşımı ve yeniden deneme davranışını yapay olarak tetikleyip mükerrer oluşmadığını doğrulayın.
4. Canlıya geçişte önce düşük hacimli bir kanalla başlayın, birkaç gün izleyin.
5. Mutabakat işini canlıya geçişle aynı gün devreye alın, sonraya bırakmayın.

Doğru kurulduğunda e-fatura entegrasyonu görünmez bir altyapıya dönüşür: sipariş gelir, fatura oluşur, kimse uğraşmaz. Yarım kurulduğunda ise her ay kapanışta elle düzeltilen bir tabloya dönüşür.

• e-fatura
• entegrasyon
• e-ticaret
• muhasebe