ZATCA e-fatura QR (Suudi FATOORA)
Suudi Arabistan'ın ZATCA (Zekat, Vergi ve Gümrük İdaresi), Krallık'ta düzenlenen her vergi faturasına QR zorunlu kılar. Faz 1 basit TLV'dir; Faz 2 FATOORA platformuyla entegrasyon yoluyla kriptografik mühürleme ekler. Uyumsuz faturalar alıcının muhasebe yazılımı tarafından reddedilir ve KDV iadesi için geçersizdir.
Kanonik teknik özellik:ZATCA E-Invoicing Resolution & Implementing Regulations, 2026'ya kadar geçerli.
Faz 1 (Üretim): 4 Aralık 2021'den itibaren yürürlükte. KDV mükellefi tüm işletmeler QR içeren dijital fatura düzenlemek zorundadır.
Faz 2 (Entegrasyon): 1 Ocak 2023'ten itibaren işletme büyüklüğüne göre aşamalı devreye alım. Standart faturalar için dijital imza + ZATCA kleranse, basit faturalar için gerçek zamanlı raporlama ekler.
Faz 1 (Üretim): 4 Aralık 2021'den itibaren yürürlükte. KDV mükellefi tüm işletmeler QR içeren dijital fatura düzenlemek zorundadır.
Faz 2 (Entegrasyon): 1 Ocak 2023'ten itibaren işletme büyüklüğüne göre aşamalı devreye alım. Standart faturalar için dijital imza + ZATCA kleranse, basit faturalar için gerçek zamanlı raporlama ekler.
Nedir
QR bir Base64 dizesini kodlar. Sabit sırayla 5 zorunlu alan içeren ikili bir TLV dizisi elde etmek için Base64'ü çözün:
| Tag | Alan | Tür | Notlar |
|---|---|---|---|
01 | Satıcı adı | UTF-8 dizesi | Satıcının ticari adı. Arapça ve Latince her ikisi de kabul edilir. |
02 | KDV kayıt numarası | 15 basamak | Suudi kuruluşları için 3 ile başlar. Format: 3XXXXXXXXXXXXX3. |
03 | Fatura zaman damgası | ISO 8601 | Örn. 2026-04-18T10:30:00Z. Saat dilimi içermeli. |
04 | Fatura toplamı (KDV dahil) | Ondalık dize | Örn. 115.00. Para birimi örtük olarak SAR. |
05 | KDV tutarı | Ondalık dize | Örn. 15.00. Mevcut standart oran %15. |
06 | Fatura özeti (Faz 2) | Base64 SHA-256 | Kanonik fatura XML'inin SHA-256'sı. |
07 | Dijital imza (Faz 2) | Base64 | Satıcının CSID sertifikasını kullanan fatura özeti üzerindeki ECDSA. |
08 | Açık anahtar (Faz 2) | Base64 X.509 | Satıcının ECDSA açık anahtarı (CSID'den). |
09 | ZATCA damgası (Faz 2) | Base64 | ZATCA'nın karşı imzası. Yalnızca ZATCA kleranse sonrası mevcut. |
Her TLV kaydı 1 tag baytı + 1 uzunluk baytı + <uzunluk> değer baytıdır. Tüm dizi ardından QR yükü olmak üzere Base64 ile kodlanır.
Faz 1 (basit) - Faz 2 (entegrasyon) karşılaştırması
| Konu | Faz 1 | Faz 2 |
|---|---|---|
| QR içeriği | Yalnızca tag 01–05 | Tag 01–05 artı 06, 07, 08, isteğe bağlı 09 |
| ZATCA entegrasyonu | Yok, çevrimdışı | Basit faturalar için gerçek zamanlı API, standart faturalar için kleranse akışı |
| Gereken sertifikalar | Hayır | Evet, ZATCA tarafından verilen CSID (Cryptographic Stamp Identifier) |
| Yürürlük tarihi | 2021-12-04 (tüm işletmeler) | 2023-01-01 (gelire göre aşamalı dalgalar) |
| Fatura kapsamı | B2C (basit) + B2B (standart) | B2C basit: gerçek zamanlı rapor. B2B standart: düzenlemeden önce kleranse (ön doğrulama). |
Kanonik test vektörleri
TLV örneği (Base64 öncesi):
01 0A "Acme Saudi" 02 0F "300000000000003" 03 14 "2026-04-18T10:30:00Z" 04 06 "115.00" 05 05 "15.00"Base64 kodlamasından sonra:
AQpBY21lIFNhdWRpAg8zMDAwMDAwMDAwMDAwMDMDFDIwMjYtMDQtMThUMTA6MzA6MDBaBAYxMTUuMDAFBTE1LjAw| Durum | Girdiler | Base64 öneki |
|---|---|---|
| Faz 1, minimum basit | seller=Acme Saudi | AQpBY21lIFNhdWRp... |
| Arapça satıcı adı | seller=شركة أكمي | Satıcı adı, Base64 öncesinde TLV içinde UTF-8 kodlamalı. |
| Faz 2 standart fatura | Yukarıdakilerin hepsi artı hash=<SHA-256 Base64> | Çok daha uzun Base64. Çözücüler 05'ten sonraki ekstra tagları tolere etmelidir. |
Yaygın tuzaklar
- KDV numarası uzunluğu. ZATCA KDV numaraları tam olarak 15 basamaklıdır,
3ile başlar ve biter. Bunun dışındaki her şey fatura alım tarafında doğrulamada başarısız olur. - Saat dilimi olmadan zaman damgası. Teknik özellik, açık bölge (
Zveya+03:00) içeren ISO 8601 gerektirir. Naif yerel zaman damgaları reddedilir. - Kodlama sırası. TLV alanları tag numarası sırasına göre (01, 02, 03, 04, 05, …) görünmelidir. Yeniden sıralama QR'ın başarılı biçimde çözülmesini sağlar, ancak bazı doğrulayıcılar bunu kanonik olmayan olarak işaretler.
- Ondalık biçimlendirme. Fatura toplamı ve KDV tutarı noktalı ondalık (
115.00) kullanır, virgüllü ondalık (115,00) değil. Ayrıca binlik ayırıcı da yoktur. - Para birimi örtük olarak SAR. Dövizli faturalar QR alanı için yine de SAR'a dönüştürülür. Temel XML orijinal para birimini taşıyabilir; QR taşımaz.
- Faz 2 kleranse hataları. ZATCA'nın kleranse API'sine gönderilen standart fatura reddedilebilir (hatalı CSID, bozuk XML, yanlış vergi hesabı). Fatura kleranse edilene kadar yasal olarak geçersizdir. Üstel geri çekilmeli yeniden deneme döngüsü tutun; kleranse başarılı olana kadar fatura düzenlemeyin.
- CSID sertifikası rotasyonu. Faz 2 CSID'leri sona erer (genellikle 1 yıl). E-faturalama sisteminize yenileme denetimi ekleyin, aksi hâlde aniden fatura düzenleyemez hâle gelirsiniz.
Tarayıcı uyumluluğu
| Okuyucu | Destek | Notlar |
|---|---|---|
| ZATCA FATOORA uygulaması | Yerel | Resmi Bakanlık uygulaması; Faz 2 imzalarını ZATCA PKI'a göre doğrular. |
| Suudi muhasebe yazılımı (SAP B1, Oracle, Microsoft Dynamics) | Yerel (2023 sonrası) | Yerelleştirilmiş Suudi sürümlerinde AP ardışık düzeninde ZATCA ayrıştırma bulunur. |
| iOS Kamera | Ham Base64 | Vergi faturası olarak tanınmaz. Kullanıcı FATOORA uygulamasını açmalıdır. |
| Android Kamera / Google Lens | Ham Base64 | Aynı, yerel ayrıştırma yok. |
| Üçüncü taraf denetim araçları (PwC, KPMG, Deloitte Suudi birimleri) | Yerel | Denetim teknolojisi paketleri Faz 2 imzalarını ayrıştırır ve doğrular. |
Ayrıca bakın
- /zatca-saudi-einvoice-qr-code/, oluşturucu.
- /standards/, standartlar dizinine geri dön.
- ZATCA Geliştiriciler Portalı, yetkili kaynaklar ve FATOORA kum havuzu.