ERPNext e-Fatura entegrasyonu nasıl yapılır?
UBL-TR formatı, özel entegratör seçimi, GİB akışı ve en sık karşılaşılan hata mesajlarının pratik çözümleri.
Akışın özeti
ERPNext'te bir satış faturası kesildiğinde şu zincir çalışmalıdır:
- Fatura kaydı oluşturulur ve muhasebe kaydı atılır.
- Fatura UBL-TR şemasına uygun XML'e dönüştürülür.
- XML, GİB onaylı özel entegratör API'sine gönderilir.
- Entegratör yanıtı (ETTN/UUID, onay kodu, durum) faturaya yazılır.
- Gönderim logu ve hata durumu kullanıcıya gösterilir.
1. Entegratör seçimi
ERPNext GİB'e doğrudan bağlanmaz. Aşağıdaki kriterlere bakın:
- API erişimi: REST/SOAP servisleri dokümante edilmiş mi?
- ERP entegrasyon ücreti: API kullanımı ayrı pakette mi?
- e-Arşiv ve e-İrsaliye: aynı sözleşme kapsamında mı?
- Test ortamı: canlıya çıkmadan deneme yapılabiliyor mu?
- SLA: kesinti durumunda yanıt süresi nedir?
2. UBL-TR dönüşümünde dikkat edilecekler
XML üretimi teknik olarak standart bir iş gibi görünür ama hata payı yüksektir. Zorunlu alanlar şunlardır:
- ETTN: her belge için tekil; veritabanında unique constraint olmalı.
- VKN/TCKN: alıcı ve satıcı için doğru formatta (10/11 hane).
- Vergi detayları: KDV oranı ve matrah, fatura satırlarıyla birebir eşleşmeli.
- Toplamlar: satır toplamları ile fatura toplamı kuruş farkı vermemeli.
- Senaryo: TICARIFATURA, IHRACAT, ISTISNA gibi doğru senaryo seçilmeli.
Kuruş farkı, e-Fatura'da en sık reddedilme nedenidir. Yuvarlama kurallarını (satır bazında mı, toplam bazında mı) baştan belirleyin ve test edin.
3. Gönderim ve yeniden deneme
Entegratör kesintileri olur. Bu yüzden gönderim akışı şu şekilde kurgulanmalıdır:
- Gönderim kuyruk üzerinden yapılır, kullanıcıyı bekletmez.
- Başarısız gönderimler otomatik yeniden denenir (artan bekleme süresiyle).
- Kalıcı hatalar hata kuyruğuna düşer ve kullanıcıya bildirilir.
- Her deneme loglanır: istek, yanıt, süre, hata kodu.
4. Sık karşılaşılan hatalar
| Belirti | Olası neden | Çözüm |
|---|---|---|
| Aynı ETTN reddi | Belge iki kez gönderilmiş | ETTN için unique constraint |
| Kuruş farkı hatası | Yuvarlama tutarsızlığı | Yuvarlama kuralını tekilleştir |
| VKN geçersiz | Boşluk/format hatası | Gönderim öncesi doğrulama |
| Zaman aşımı | Entegratör yavaşlığı | Kuyruk + yeniden deneme |
| Senaryo hatası | Yanlış fatura tipi | Müşteri tipine göre senaryo seçimi |
| İptal edilemiyor | Süre aşılmış | İade faturası akışı |
5. Test stratejisi
Canlıya geçmeden önce en az şu senaryolar denenmelidir: tek satırlı fatura, çok satırlı fatura, farklı KDV oranları, iskontolu fatura, ihracat faturası, iade faturası ve e-Arşiv kapsamındaki satış. Her senaryo için XML çıktısı saklanmalı; ileride çıkan uyuşmazlıklarda referans olur.
Sonuç
e-Fatura entegrasyonu, "XML üretip göndermek"ten fazlasıdır: tekil numara garantisi, kuyruk yönetimi, hata görünürlüğü ve test disiplini gerekir. Bu dört şey kurulmadan canlıya geçen sistemler, ilk entegratör kesintisinde fatura kaybeder.