1
المرحلة 1: التحضير والتسجيل (الأسبوع 1)
- تحقق من إن شركتك ضمن الـwave الحالي — راجع ZATCA portal لتاريخ الـeffective date لشركتك
- احضّر الـCommercial Registration — لازم يكون active وصحيح
- سجّل المسؤول التقني في الـZATCA portal
- راجع الـVAT registration — التأكد من VAT number صحيح
- اختر solution provider معتمد — Odoo Enterprise، SAP، Oracle، إلخ
- حدد موعد الـtest environment access — ZATCA Sandbox
2
المرحلة 2: الإعداد التقني (الأسبوع 1-2)
- احصل على CSID (Cryptographic Stamp Identifier) من ZATCA Sandbox
- configure الـdigital certificate في الـERP
- setup الـCSR (Certificate Signing Request)
- اختبر Sandbox endpoints: /compliance/invoices/clearance + /compliance/invoices/reporting
- configure UBL 2.1 XML templates للفواتير
- generate QR code templates بـBase64 format
- setup UUID generation لكل فاتورة (UUID v4)
- setup hash chain للـimmutability
- configure invoice numbering sequence (لازم sequential بدون gaps)
3
المرحلة 3: Mapping البيانات (الأسبوع 2)
- Map customer data: VAT number، address، contact
- Map product data: UNSPSC codes، VAT category، unit of measure
- Map tax rates: 15% standard، 0% (zero-rated)، exempt
- Map fiscal categories: B2B clearance، B2C reporting، export
- Map currency codes ISO 4217 (SAR، USD، إلخ)
- Map payment methods حسب ZATCA standards
- Map invoice types: standard، credit note، debit note، prepayment
4
المرحلة 4: الاختبار (الأسبوع 2-3)
- اختبر standard invoice (B2B clearance)
- اختبر simplified invoice (B2C reporting)
- اختبر credit note generation
- اختبر debit note generation
- اختبر prepayment invoice
- اختبر invoice cancellation workflow
- تأكد من XML schema validation ضد ZATCA XSD
- تأكد من QR code readable بأي scanner
- تأكد من cryptographic stamp valid ضد public key
- اختبر offline scenario — لو الـZATCA API down، الفاتورة لازم تـcache وتـretry
- اختبر concurrent invoices (100+ في الـsecond)
5
المرحلة 5: Edge Cases
- Export of services — الـVAT 0%، الـcustomer outside KSA
- Reverse charge mechanism — للـimports
- Multiple line items with different tax rates
- Discounts — line-level + invoice-level
- Foreign currency invoices — exchange rate snapshot
- Long-form invoices (50+ line items)
- Customer with no VAT (B2C)
- Customer with foreign VAT (GCC + non-GCC)
6
المرحلة 6: Go-Live (الأسبوع 3-4)
- احصل على Production CSID من ZATCA portal
- switch endpoints من Sandbox لـProduction
- Issue test invoice في production + verify clearance
- setup monitoring + alerts للـfailed submissions
- train accounting team على الـnew workflow
- تأكد من backup + retention policy (8 سنين كحد أدنى)
7
الـTroubleshooting الشائع
1. الفاتورة rejected بـerror "Invalid Signature"
السبب: الـprivate key أو الـcertificate غير صحيح. الحل: regenerate CSID + re-upload certificate.
2. QR Code لا يفتح بأي scanner
السبب: الـbase64 encoding خطأ أو الـTLV format غلط. الحل: استخدم ZATCA's official TLV generator لـvalidation.
3. الـsequence numbers بها gaps
السبب: فواتير اتلغت في الـmiddle. الحل: ZATCA بيتطلب reason للـgap في الـmonthly report.
4. الـtimeout على الـclearance endpoint
السبب: ZATCA API بطيء في الـpeak hours. الحل: retry logic مع exponential backoff (max 3 retries).