Kurumsal ERP yazılımlarında e-Fatura ve e-İrsaliye entegrasyonu: GİB standartları, UBL-TR 2.1 XML şeması, mali mühür ve web servis mimarisi detayları.
Hızlı Özet (TL;DR)
Türkiye’de Gelir İdaresi Başkanlığı (GİB) tarafından yürütülen e-Dönüşüm mevzuatı; e-Fatura, e-Arşiv Fatura, e-İrsaliye ve e-Müstahsil belgelerinin evrensel OASIS UBL 2.1 (Universal Business Language) standardının Türkiye özelleştirmesi olan UBL-TR 1.2.1 / 2.1 XML formatında üretilmesini, XSLT şablonuyla görselleştirilmesini ve mali mühür / nitelikli elektronik sertifika ile kriptografik olarak imzalanmasını şart koşar. Özel ERP, üretim ve muhasebe yazılımlarında bu süreç; doğrudan GİB sunucularıyla haberleşmek yerine yüksek erişilebilirlikli Özel Entegratör REST/SOAP API’leri üzerinden asenkron mesaj kuyruğu (Message Queue) yapısıyla entegre edilerek operasyonel ve vergisel riskler sıfırlanmalıdır.
e-Dönüşüm Süreç Bileşenleri ve Teknik Mimari Matrisi
Bir e-Fatura veya e-İrsaliye belgesinin ERP veritabanındaki sipariş ve sevkiyat kayıtlarından doğup GİB merkez sisteminde yasal geçerlilik kazanması için geçmesi gereken teknik aşamalar şunlardır:
| Aşama | Teknik Standart | Kullanılan Teknoloji / Format | Kritik Doğrulama ve Kontroller |
|---|---|---|---|
| Mükellef Sorgulama | GİB PK / GB Listesi | Güncel Mükellef Cache / API | Alıcı VKN/TCKN’nin e-Fatura mı yoksa e-Arşiv mükellefi mi olduğunun tespiti |
| Veri Üretimi | UBL-TR 2.1 Standardı | XML (UTF-8 Karakter Kodlaması) | XSD (XML Schema Definition) yapısal doğrulaması |
| İş Kuralları Denetimi | GİB Schematron | XPath ve XSLT Tabanlı Kurallar | Vergi kodları, tevkifat oranları ve alt toplam kuruş dengesi |
| Görselleştirme | GİB Uyumlu Tasarım | XSLT (Base64 Gömülü Şablon) | Karekod (QR), GİB logosu, zorunlu iban ve mersis bilgileri |
| Elektronik İmza | XAdES-BES / EPES | Kriptografik Mali Mühür (HSM) | Sertifika zinciri, OCSP/CRL iptal kontrolü ve zaman damgası |
| Zarf Hazırlama | SBDH Standardı | Standard Business Document Header | Zarf ETTN benzersizliği, ZIP sıkıştırma ve alıcı Posta Kutusu (PK) etiketi |
| İletim ve Yanıt | SOAP / REST Web Servis | HTTPS TLS 1.3 + Asenkron Kuyruk | 1200 Zarf Başarıyla İşlendi veya 1300 Başarıyla Tamamlandı durum kodu |
UBL-TR XML Şemasında ve Schematron Denetiminde En Sık Yapılan Hatalar
GİB sistemine veya özel entegratör servislerine gönderilen elektronik belgelerin 1160 - XML Şema Kontrolünden Geçemedi ya da 1163 - Schematron Kontrolünden Geçemedi hatalarıyla reddedilmesine yol açan temel teknik uyumsuzluklar şunlardır:
- Vergi Muafiyet ve İstisna Kodu Eksikliği (
TaxExemptionReasonCode): Eğer bir faturada veya fatura satırında KDV oranı%0olarak uygulanmışsa, UBL-TR şemasında mutlaka geçerli bir GİB muafiyet kodu ve açıklaması bulunmak zorundadır (Örn:301 - 11/1-a Mal İhracatı,351 - İstisna Olmayan Diğer,250 - Diğer İndirimler). Benzer şekilde tevkifatlı faturalarda (Örn: fason tekstil, metal işleme veya yapım işleri)WithholdingTaxTotaldüğümünde hem tevkifat oranı hem de GİB tevkifat kodu eksiksiz yer almalıdır. - Kuruş Yuvarlama ve Matrah Uyuşmazlıkları (
LegalMonetaryTotal): İskontolu veya dövizli birim fiyatların kullanıldığı çok satırlı sanayi faturalarında, satır net tutarlarının (LineExtensionAmount) toplamı ile fatura alt toplamı arasında 1 kuruştan fazla yuvarlama farkı oluşması durumunda GİB Schematron kuralları faturayı anında reddeder. Bu sorunu önlemek için ERP içinde birim fiyatlar 4 veya 6 ondalık basamakla tutulurken, satır toplamları ve vergi matrahlarıHalf-Even (Banker's Rounding)veya GİB yuvarlama tolerans algoritmasına göre 2 ondalık basamağa normalize edilmelidir. - ETTN (UUID v4) Benzersizliği ve Belge Numarası Formatı: Her elektronik belgenin kendine ait, RFC 4122 standardına uygun üretilmiş 36 karakterlik bir UUID (
cbc:UUID) değeri ve 16 haneli standart belge numarası (3 haneli birim kodu + 4 haneli yıl + 9 haneli müteselsil sıra numarası, örn:MYS2026000001452) olmalıdır. Aynı ETTN veya aynı fatura numarasıyla ikinci bir gönderim yapılması mükerrer kayıt hatasına düşer. - Ölçü Birimi Kodlarının Evrensel Standarttan Sapması (
unitCode): ERP içindeki yerel stok birimlerinin (“Adet”, “Kg”, “Metre”, “Koli”) XML içine Türkçe metin olarak yazılması şema hatası üretir. Tüm birimler UN/ECE Recommendation 20 uluslararası kodlarıyla (C62= Adet,KGM= Kilogram,MTR= Metre,LTR= Litre,SET= Takım) eşleştirilerek gönderilmelidir.
Asenkron Kuyruk Mimarisi ve Zarf Durum Kodlarının Yönetimi
Kurumsal bir ERP yazılımında kullanıcı “Faturayı Gönder” veya “İrsaliyeyi Onayla” butonuna bastığında, arayüzün özel entegratör veya GİB sunucusundan senkron yanıt bekleyerek ekranı dondurması (Blocking Call) büyük bir mimari hatadır. Resmi tatil dönüşlerinde, ay sonu yoğunluklarında veya GİB bakım saatlerinde web servis yanıt süreleri uzayabilir.
Maysa Yazılım’ın geliştirdiği kurumsal entegrasyon katmanında tüm e-belge trafiği Asenkron İş Kuyruğu (Background Worker & Retry Queue) üzerinden yürütülür:
- Adım 1 (Kuyruğa Alma ve Ön Doğrulama): Belge ERP içinde onaylandığı saniyede yerel Schematron motorumuz XML’i milisaniyeler içinde denetler. Hata varsa kullanıcıya anında Türkçe ve anlaşılır bir uyarıyla hangi satırda eksiklik olduğunu gösterir.
- Adım 2 (İletim ve Zarf Takibi): Doğrulanan belge arka planda entegratör API’sine iletilir. Sistem belirli aralıklarla (Polling veya Webhook) zarf durumunu sorgular.
- Adım 3 (Durum Kodlarına Göre Otomatik Aksiyon):
1100(Zarf işleniyor) veya1220(Hedef sistemden yanıt bekleniyor) kodlarında sistem beklemeye devam eder. Eğer1210(Doküman bulunan adrese gönderilemedi) hatası alınırsa sistem otomatik yeniden gönderim (Exponential Backoff Retry) tetikler;1300(Başarıyla tamamlandı) kodu alındığında ise belge kilitlenerek muhasebe fişi kesinleştirilir.
Ticari Fatura, Temel Fatura ve İhracat e-Fatura Senaryoları
ERP entegrasyonunda profil seçimi (ProfileID) iş akışını doğrudan belirler. TEMELFATURA senaryosunda alıcı faturayı sistem üzerinden reddedemez (ancak KEP veya noter kanalıyla itiraz edebilir); TICARIFATURA senaryosunda ise alıcının faturayı 8 gün içinde sistem üzerinden “Kabul” veya “Ret” uygulama yanıtı (ApplicationResponse) ile cevaplama hakkı vardır. Sistemimiz gelen uygulama yanıtlarını otomatik dinleyerek, reddedilen bir ticari faturanın muhasebe ve cari bakiye kaydını anında uyarı durumuna geçirir. Mal ihracatı işlemlerinde ise IHRACAT profiliyle kesilen faturalar Gümrük ve Ticaret Bakanlığı (GTB) sistemine düşer, GTİP (Gümrük Tarife İstatistik Pozisyonu) kodları ve teslim şekli (Incoterms: FOB, CIF, EXW) XML içine zorunlu alan olarak işlenir.
Fabrika Sahasında Canlı e-İrsaliye, Karekod ve Sevkiyat Doğrulaması
İmalat sanayisinde sevkiyat kamyonu fabrika kapısından çıkmadan önce e-İrsaliyenin GİB sistemine iletilmiş, doğrulamadan geçmiş ve üzerinde GİB karekodu bulunan nüshanın (veya dijital görüntüsünün) hazır olması yasal zorunluluktur. Yolda yapılacak bir maliye veya jandarma denetiminde irsaliyesiz mal taşınması ağır vergi cezalarına neden olur.
Maysa Stok Takip ve Barkodlu Depo Yazılımı ile tam entegre çalışan Özel ERP & CRM ve İmalat Çözümleri altyapımızda; sevkiyat sorumlusu el terminaliyle kamyona yüklenen paletlerin barkodlarını okutup “Yükleme Tamamlandı” butonuna bastığı anda sistem taşıyıcı firma VKN’sini, kamyon plakasını, dorse plakasını ve şoför TCKN/ad-soyad bilgilerini otomatik olarak DespatchAdvice (e-İrsaliye XML) şemasına yerleştirir. 3 saniye içinde GİB onaylı karekodlu irsaliye çıktısı sevkiyat rampasındaki yazıcıdan dökülür ve şoför beklemeden yola çıkar.
Gelen e-İrsaliye ve e-Faturaların Otomatik İçeri Alınması (Inbound)
Entegrasyon yalnızca giden belgelerle sınırlı değildir. Hammadde tedarikçilerinizden veya fasoncularınızdan gelen e-İrsaliyeler, kamyon henüz yoldayken sistem ekranınıza düşer. Mal kabul personeli tedarikçinin e-İrsaliyesini el terminalinde açarak gelen kalemleri sayar; eksik veya hasarlı mal varsa GİB standartlarına uygun “e-İrsaliye Yanıtı (ReceiptAdvice)” belgesini tek tuşla göndererek kısmi kabul veya ret miktarını resmi olarak karşı tarafa bildirir.
İşletmenizin ERP, depo ve üretim süreçleriyle tam entegre, hatasız e-Fatura ve e-İrsaliye altyapısı kurmak için Özel Yazılım Geliştirme sayfamızı inceleyebilirsiniz.
Sıkça Sorulan Sorular
Fabrika sahasında internet kesildiğinde veya GİB sistemlerinde arıza olduğunda sevkiyat kamyonu nasıl çıkış yapar?
GİB mevzuatına göre teknik imkansızlık veya internet kesintisi durumlarında matbu (kağıt) sevk irsaliyesi düzenlenerek araç yola çıkarılabilir; ancak internet bağlantısı sağlandığı anda (en geç izleyen gün içinde) bu matbu irsaliyenin bilgileri “Matbudan Dönüştürülen e-İrsaliye” tipiyle ve kağıt irsaliyenin seri/sıra numarası referans gösterilerek GİB sistemine elektronik olarak iletilmek zorundadır. Yazılımımız çevrimdışı modda bu referans takibini otomatik yapar.
Özel entegratör değiştirmek istediğimizde geçmiş yıllara ait e-Fatura ve e-İrsaliye arşivimiz kaybolur mu?
Hayır, Maysa ERP mimarisinde üretilen ve gelen tüm elektronik belgelerin imzalı orijinal XML zarfları ve XSLT görüntüleri, özel entegratör arşivine ek olarak kendi yerel sunucunuzda ve kurumsal bulut yedeklerinizde 10 yıllık yasal saklama süresine uygun şekilde indeksli olarak arşivlenir. Entegratör değiştirseniz dahi tüm geçmiş arşiviniz ERP ekranlarınızdan kesintisiz görüntülenmeye devam eder.
Müşterinin e-Fatura mükellefi olup olmadığı fatura kesilirken nasıl anlaşılır?
Sistemimiz her gün GİB tarafından yayınlanan güncel “Kayıtlı Kullanıcılar Listesi (PK Listesi)” veritabanını arka planda otomatik olarak senkronize eder ve ayrıca fatura kesim anında canlı VKN/TCKN sorgulaması yapar. Eğer alıcı e-Fatura mükellefi ise sistem belgeyi otomatik olarak e-Fatura (TICARIFATURA veya TEMELFATURA) kuyruğuna, mükellef değilse doğrudan EARSIVFATURA kuyruğuna yönlendirerek kullanıcı hatasını tamamen ortadan kaldırır.