PHP ile E-Fatura Entegrasyonu: Teknik Rehber
Mimari yaklaşım
E-fatura kodunu sipariş veya muhasebe kodunun içine gömmek, ileride entegratör değiştirmeyi ve hata ayıklamayı zorlaştırır. Önerilen yapı:
- Fatura modeli: Uygulamanın kendi fatura ve fatura satırı tabloları
- Dönüştürücü (mapper): Fatura modelini UBL-TR yapısına çeviren sınıf
- Entegratör istemcisi: Entegratörün API'sini (genellikle SOAP veya REST) saran, bir arayüzü uygulayan sınıf
- Kuyruk işçisi: Gönderim ve durum sorgulamayı arka planda yapan iş
UBL-TR XML üretimi
Bazı entegratörler JSON alıp XML'i kendisi üretir; bazıları doğrudan UBL-TR XML bekler. XML üretiyorsanız PHP'nin DOMDocument veya XMLWriter sınıfları kullanılabilir. Dikkat edilmesi gerekenler:
- Para alanlarında ondalık hassasiyet ve yuvarlama (satır toplamı ile genel toplam tutarlılığı)
- KDV oranı, istisna ve tevkifat kodlarının GİB kod listelerine uygunluğu
- Birim kodları (C62 adet, KGM kilogram gibi UN/ECE kodları)
- Fatura senaryosu (temel/ticari) ve tipi (satış, iade, tevkifat vb.)
- Benzersiz UUID (ETTN) üretimi
Gönderim akışı
- Fatura onaylanınca durum “gönderilecek” yapılır ve kuyruğa iş eklenir
- İşçi, alıcının e-fatura mükellefiyetini sorgular; sonuca göre e-fatura veya e-arşiv akışını seçer
- Fatura entegratöre gönderilir, dönen kimlik ve durum kaydedilir
- Belirli aralıklarla durum sorgulanır; son durum ve PDF saklanır
Hata yönetimi
- İdempotentlik: Ağ zaman aşımında fatura gerçekten gitti mi bilinmez; tekrar göndermeden önce ETTN ile durum sorgulanmalı
- Ayrıntılı log: Gönderilen istek ve dönen yanıt (kişisel veriler maskelenerek) saklanmalı
- Bildirim: Reddedilen veya hata alan faturalar sorumluya bildirilmeli
- Tekrar deneme: Geçici hatalarda artan bekleme süresiyle yeniden deneme
Güvenlik
Entegratör kullanıcı adı, parola ve API anahtarları kod deposuna yazılmamalı; ortam değişkenlerinde veya bir gizli bilgi kasasında tutulmalıdır.
Test
Entegratörlerin test ortamında; farklı KDV oranları, istisnalı satış, iade faturası, döviz cinsinden fatura ve e-arşiv senaryoları ayrı ayrı denenmelidir.
Sonuç
Doğru kurgulanmış bir e-fatura entegrasyonu yıllarca sorunsuz çalışır. PHP veya başka bir altyapıda entegrasyon için entegrasyon ve API geliştirme hizmetimizi inceleyebilir veya ücretsiz keşif görüşmesi talep edebilirsiniz.