Use this skill with your AI agent
Paste this skill into your AI agent's context, or save the file to your project. Works with any AI agent that reads markdown.
saudi-einvoice.md356 lines14.0 KB
v10Saudi Arabia
Not yet verified by an accountantContact accountant
| 1 | --- |
| 2 | name: saudi-einvoice |
| 3 | description: > |
| 4 | Use this skill whenever asked about Saudi Arabia e-invoicing, ZATCA FATOORA platform, Phase 1 generation, Phase 2 integration, e-invoice clearance, e-invoice reporting, ZATCA API, UBL 2.1 XML for Saudi invoices, cryptographic stamp, QR code TLV encoding, ECDSA signing, CSID certificate, onboarding OTP, Simplified vs Standard tax invoice, B2B clearance, B2C reporting, or any question about generating, submitting, or troubleshooting Saudi e-invoices. Also trigger when advising on ZATCA compliance waves, XML structure, digital signature requirements, or integration architecture. ALWAYS read this skill before touching any Saudi e-invoice work. |
| 5 | version: 1.0 |
| 6 | jurisdiction: SA |
| 7 | category: invoicing |
| 8 | depends_on: |
| 9 | - einvoice-workflow-base |
| 10 | --- |
| 11 | |
| 12 | # Saudi Arabia ZATCA E-Invoice (FATOORA) Skill v1.0 |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Section 1 -- Quick Reference |
| 17 | |
| 18 | | Field | Value | |
| 19 | |---|---| |
| 20 | | Country | Kingdom of Saudi Arabia (KSA) | |
| 21 | | Currency | SAR (Saudi Riyal) | |
| 22 | | E-Invoicing System | FATOORA Platform | |
| 23 | | Governing Body | Zakat, Tax and Customs Authority (ZATCA) | |
| 24 | | Key Legislation | E-Invoicing Regulation (issued 4 December 2021); VAT Implementing Regulations | |
| 25 | | Schema Standard | UBL 2.1 (Universal Business Language) XML | |
| 26 | | Cryptographic Standard | ECDSA secp256k1 digital signature | |
| 27 | | Phase 1 (Generation) | Mandatory from 4 December 2021 (all VAT-registered taxpayers) | |
| 28 | | Phase 2 (Integration) | Rolling waves from 1 January 2023, based on revenue thresholds | |
| 29 | | Current Status | Phase 2 waves ongoing through 2026; smaller thresholds being added progressively | |
| 30 | | Portal | fatoora.zatca.gov.sa | |
| 31 | |
| 32 | ### Phase 2 Integration Waves |
| 33 | |
| 34 | | Wave | Effective Date | Revenue Threshold | |
| 35 | |---|---|---| |
| 36 | | Wave 1 | 1 January 2023 | > SAR 3 billion | |
| 37 | | Wave 2 | 1 July 2023 | > SAR 500 million | |
| 38 | | Wave 3 | 1 October 2023 | > SAR 250 million | |
| 39 | | Wave 4 | 1 November 2023 | > SAR 150 million | |
| 40 | | Wave 5 | 1 December 2023 | > SAR 100 million | |
| 41 | | Wave 6 | 1 March 2024 | > SAR 70 million | |
| 42 | | Wave 7 | 1 June 2024 | > SAR 50 million | |
| 43 | | Wave 8 | 1 October 2024 | > SAR 40 million | |
| 44 | | Wave 9 | 1 December 2024 | > SAR 30 million | |
| 45 | | Wave 10+ | 2025-2026 | Progressively lower thresholds | |
| 46 | |
| 47 | --- |
| 48 | |
| 49 | ## Section 2 -- Mandate Scope |
| 50 | |
| 51 | ### Phase 1 -- Generation (All Taxpayers Since Dec 2021) |
| 52 | |
| 53 | - ALL VAT-registered taxpayers in KSA |
| 54 | - Must generate e-invoices (and credit/debit notes) using a compliant electronic system |
| 55 | - Paper invoices no longer legally valid |
| 56 | - Basic QR code required on simplified (B2C) invoices |
| 57 | - No system-to-system integration required |
| 58 | |
| 59 | ### Phase 2 -- Integration (Wave-Based) |
| 60 | |
| 61 | - System must integrate with ZATCA's FATOORA platform via API |
| 62 | - **Standard Tax Invoice (B2B)**: Must be cleared by ZATCA before delivery to buyer |
| 63 | - **Simplified Tax Invoice (B2C)**: Must be reported to ZATCA within 24 hours |
| 64 | - Cryptographic stamp (digital signature) required on all invoices |
| 65 | - Enhanced QR code with TLV-encoded cryptographic data |
| 66 | |
| 67 | ### Document Types |
| 68 | |
| 69 | | Type | Code | SubType Code | Clearance Model | |
| 70 | |---|---|---|---| |
| 71 | | Standard Tax Invoice (B2B) | 388 | 0100000 | Real-time clearance (before sharing with buyer) | |
| 72 | | Simplified Tax Invoice (B2C) | 388 | 0200000 | Near-real-time reporting (within 24 hours) | |
| 73 | | Standard Credit Note | 381 | 0100000 | Clearance | |
| 74 | | Simplified Credit Note | 381 | 0200000 | Reporting | |
| 75 | | Standard Debit Note | 383 | 0100000 | Clearance | |
| 76 | | Simplified Debit Note | 383 | 0200000 | Reporting | |
| 77 | |
| 78 | ### Exemptions |
| 79 | |
| 80 | - None for Phase 1 — all VAT-registered taxpayers must comply |
| 81 | - Phase 2 integration is wave-based by revenue; ZATCA notifies targeted groups 6 months in advance |
| 82 | |
| 83 | --- |
| 84 | |
| 85 | ## Section 3 -- Technical Format |
| 86 | |
| 87 | ### XML Specification |
| 88 | |
| 89 | | Aspect | Detail | |
| 90 | |---|---| |
| 91 | | Format | XML | |
| 92 | | Standard | UBL 2.1 (ISO/IEC 19845:2015) | |
| 93 | | Root Element | `<Invoice>` or `<CreditNote>` or `<DebitNote>` | |
| 94 | | Namespace (UBL) | urn:oasis:names:specification:ubl:schema:xsd:Invoice-2 | |
| 95 | | Namespace (cac) | urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2 | |
| 96 | | Namespace (cbc) | urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2 | |
| 97 | | Namespace (ext) | urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2 | |
| 98 | | CIUS | ZATCA Saudi Arabia CIUS (country-specific extensions within UBL) | |
| 99 | | Encoding | UTF-8 | |
| 100 | |
| 101 | ### Cryptographic Requirements (Phase 2) |
| 102 | |
| 103 | | Component | Specification | |
| 104 | |---|---| |
| 105 | | Signing Algorithm | ECDSA with secp256k1 curve | |
| 106 | | Hash Algorithm | SHA-256 | |
| 107 | | Certificate | X.509 issued by ZATCA via CSR/CSID process | |
| 108 | | Invoice Hash | Base64-encoded SHA-256 of canonical XML (before signing) | |
| 109 | | Previous Invoice Hash | Hash of the previously issued invoice (chain integrity) | |
| 110 | | UUID | RFC 4122 v4 (randomly generated 128-bit identifier per document) | |
| 111 | |
| 112 | ### QR Code Structure (Phase 2) |
| 113 | |
| 114 | TLV (Tag-Length-Value) encoding with Base64: |
| 115 | |
| 116 | | Tag | Field | Data Type | |
| 117 | |---|---|---| |
| 118 | | 1 | Seller Name | UTF-8 String | |
| 119 | | 2 | VAT Registration Number | UTF-8 String | |
| 120 | | 3 | Invoice Timestamp | ISO 8601 (YYYY-MM-DDThh:mm:ssZ) | |
| 121 | | 4 | Invoice Total (with VAT) | Decimal String | |
| 122 | | 5 | VAT Amount | Decimal String | |
| 123 | | 6 | Invoice Hash (SHA-256) | Base64 | |
| 124 | | 7 | ECDSA Signature | Base64 | |
| 125 | | 8 | Public Key | Base64 (DER-encoded) | |
| 126 | | 9 | Certificate Signature | Base64 | |
| 127 | |
| 128 | --- |
| 129 | |
| 130 | ## Section 4 -- Mandatory Fields |
| 131 | |
| 132 | ### Invoice-Level Fields |
| 133 | |
| 134 | | UBL Path | Description | Example | |
| 135 | |---|---|---| |
| 136 | | cbc:ID | Invoice number | INV-2026-001 | |
| 137 | | cbc:UUID | RFC 4122 UUID | 8d487816-... | |
| 138 | | cbc:IssueDate | Issue date | 2026-05-22 | |
| 139 | | cbc:IssueTime | Issue time | 14:30:00 | |
| 140 | | cbc:InvoiceTypeCode | Document type | 388 | |
| 141 | | cbc:InvoiceTypeCode/@name | SubType code | 0100000 (standard) or 0200000 (simplified) | |
| 142 | | cbc:DocumentCurrencyCode | Currency | SAR | |
| 143 | | cbc:TaxCurrencyCode | Tax currency | SAR | |
| 144 | | cac:AdditionalDocumentReference (ICV) | Invoice Counter Value | Sequential integer | |
| 145 | | cac:AdditionalDocumentReference (PIH) | Previous Invoice Hash | Base64 SHA-256 | |
| 146 | |
| 147 | ### Supplier (cac:AccountingSupplierParty) |
| 148 | |
| 149 | | Path | Description | |
| 150 | |---|---| |
| 151 | | cac:Party/cac:PartyIdentification/cbc:ID (@schemeID="CRN") | Commercial Registration Number | |
| 152 | | cac:Party/cac:PartyTaxScheme/cbc:CompanyID | VAT Registration Number (15 digits) | |
| 153 | | cac:Party/cac:PartyLegalEntity/cbc:RegistrationName | Legal name (Arabic required) | |
| 154 | | cac:Party/cac:PostalAddress/cbc:StreetName | Street | |
| 155 | | cac:Party/cac:PostalAddress/cbc:BuildingNumber | Building number | |
| 156 | | cac:Party/cac:PostalAddress/cbc:CityName | City | |
| 157 | | cac:Party/cac:PostalAddress/cbc:PostalZone | Postal code | |
| 158 | | cac:Party/cac:PostalAddress/cac:Country/cbc:IdentificationCode | SA | |
| 159 | |
| 160 | ### Buyer (cac:AccountingCustomerParty) — Standard Invoice |
| 161 | |
| 162 | | Path | Description | |
| 163 | |---|---| |
| 164 | | cac:Party/cac:PartyTaxScheme/cbc:CompanyID | Buyer VAT number | |
| 165 | | cac:Party/cac:PartyLegalEntity/cbc:RegistrationName | Buyer legal name | |
| 166 | | cac:Party/cac:PostalAddress | Full address (street, city, postal code) | |
| 167 | |
| 168 | ### Tax Total (cac:TaxTotal) |
| 169 | |
| 170 | | Path | Description | |
| 171 | |---|---| |
| 172 | | cbc:TaxAmount | Total VAT amount | |
| 173 | | cac:TaxSubtotal/cbc:TaxableAmount | Taxable amount per rate | |
| 174 | | cac:TaxSubtotal/cbc:TaxAmount | Tax amount per rate | |
| 175 | | cac:TaxSubtotal/cac:TaxCategory/cbc:ID | Tax category (S, Z, E, O) | |
| 176 | | cac:TaxSubtotal/cac:TaxCategory/cbc:Percent | VAT rate (15, 0, etc.) | |
| 177 | |
| 178 | ### Line Items (cac:InvoiceLine) |
| 179 | |
| 180 | | Path | Description | |
| 181 | |---|---| |
| 182 | | cbc:ID | Line number | |
| 183 | | cbc:InvoicedQuantity | Quantity | |
| 184 | | cbc:LineExtensionAmount | Line net amount | |
| 185 | | cac:Item/cbc:Name | Item name | |
| 186 | | cac:Item/cac:ClassifiedTaxCategory/cbc:ID | Tax category | |
| 187 | | cac:Item/cac:ClassifiedTaxCategory/cbc:Percent | VAT rate | |
| 188 | | cac:Price/cbc:PriceAmount | Unit price | |
| 189 | |
| 190 | --- |
| 191 | |
| 192 | ## Section 5 -- Transmission Method |
| 193 | |
| 194 | ### Onboarding Process |
| 195 | |
| 196 | 1. Register on FATOORA portal (fatoora.zatca.gov.sa) using ZATCA credentials |
| 197 | 2. Generate OTP (One-Time Password) per EGS device |
| 198 | 3. EGS generates ECDSA private key (secp256k1) and Certificate Signing Request (CSR) |
| 199 | 4. Submit CSR + OTP to Compliance CSID API → receive Compliance CSID (temporary certificate) |
| 200 | 5. Run 3 compliance checks (standard invoice, simplified invoice, credit note) |
| 201 | 6. Submit compliance check results → receive Production CSID (permanent certificate) |
| 202 | 7. Begin production clearance/reporting |
| 203 | |
| 204 | ### API Endpoints |
| 205 | |
| 206 | | Endpoint | Method | Purpose | |
| 207 | |---|---|---| |
| 208 | | /compliance | POST | Onboarding — get Compliance CSID | |
| 209 | | /production/csids | POST | Get Production CSID | |
| 210 | | /compliance/invoices | POST | Submit compliance test invoices | |
| 211 | | /invoices/clearance | POST | Clear standard (B2B) invoices | |
| 212 | | /invoices/reporting | POST | Report simplified (B2C) invoices | |
| 213 | |
| 214 | ### Production Base URL |
| 215 | |
| 216 | ``` |
| 217 | https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal |
| 218 | ``` |
| 219 | |
| 220 | ### Authentication |
| 221 | |
| 222 | - HTTP Basic Auth using Base64-encoded `{CSID_binary_token}:{secret}` |
| 223 | - Each EGS device has its own certificate and credentials |
| 224 | - Certificate renewal required before expiry |
| 225 | |
| 226 | --- |
| 227 | |
| 228 | ## Section 6 -- Validation Rules |
| 229 | |
| 230 | ### ZATCA Server-Side Validation |
| 231 | |
| 232 | 1. XML schema validation against UBL 2.1 + ZATCA CIUS |
| 233 | 2. Cryptographic signature verification (ECDSA secp256k1) |
| 234 | 3. Certificate chain validation (must be ZATCA-issued) |
| 235 | 4. Invoice hash verification (SHA-256 of canonical form) |
| 236 | 5. Previous invoice hash chain integrity |
| 237 | 6. UUID uniqueness check |
| 238 | 7. Invoice Counter Value (ICV) sequence validation |
| 239 | 8. Tax calculation verification (line totals, tax amounts) |
| 240 | 9. Seller VAT number validity |
| 241 | 10. Buyer VAT number validity (standard invoices) |
| 242 | |
| 243 | ### Common Rejection Reasons |
| 244 | |
| 245 | | Code | Description | Resolution | |
| 246 | |---|---|---| |
| 247 | | INVALID-SIGNATURE | Signature verification failed | Regenerate signature with correct private key | |
| 248 | | INVALID-CERTIFICATE | Certificate not issued by ZATCA | Re-onboard the EGS device | |
| 249 | | DUPLICATE-UUID | UUID already submitted | Generate new UUID per RFC 4122 | |
| 250 | | INVALID-HASH | Invoice hash does not match content | Recompute SHA-256 on canonical XML | |
| 251 | | PIH-MISMATCH | Previous invoice hash incorrect | Use hash of actual last invoice | |
| 252 | | TAX-CALC-ERROR | Tax amounts do not compute | Verify: TaxAmount = TaxableAmount × Rate | |
| 253 | | MISSING-FIELD | Required field absent | Add missing UBL element | |
| 254 | |
| 255 | ### Validation Statuses |
| 256 | |
| 257 | | Status | Meaning | |
| 258 | |---|---| |
| 259 | | CLEARED | Standard invoice accepted (can share with buyer) | |
| 260 | | REPORTED | Simplified invoice acknowledged | |
| 261 | | REJECTED | Validation failed — must fix and resubmit | |
| 262 | | WARNING | Non-blocking issue — invoice accepted but flagged | |
| 263 | |
| 264 | --- |
| 265 | |
| 266 | ## Section 7 -- Tax Computation Rules |
| 267 | |
| 268 | ### VAT Rates in KSA |
| 269 | |
| 270 | | Category | Code | Rate | Description | |
| 271 | |---|---|---|---| |
| 272 | | Standard | S | 15% | Default rate | |
| 273 | | Zero-rated | Z | 0% | Exports, international transport | |
| 274 | | Exempt | E | 0% | Financial services, residential rent | |
| 275 | | Out of scope | O | 0% | Government services | |
| 276 | |
| 277 | ### Calculation Rules |
| 278 | |
| 279 | - Line Extension Amount = Quantity × Unit Price - Discount |
| 280 | - Tax Amount per line = Line Extension Amount × Tax Rate / 100 |
| 281 | - Rounding: 2 decimal places (round half-up) |
| 282 | - Document-level TaxTotal must equal sum of all line tax amounts (tolerance: SAR 0.01) |
| 283 | - TaxInclusiveAmount = TaxExclusiveAmount + TaxTotal |
| 284 | |
| 285 | ### Multi-Rate Invoice |
| 286 | |
| 287 | - Each line item carries its own TaxCategory and Percent |
| 288 | - TaxTotal contains multiple TaxSubtotal elements (one per distinct rate) |
| 289 | - Each TaxSubtotal aggregates TaxableAmount and TaxAmount for that rate |
| 290 | |
| 291 | --- |
| 292 | |
| 293 | ## Section 8 -- Archiving Requirements |
| 294 | |
| 295 | | Requirement | Detail | |
| 296 | |---|---| |
| 297 | | Retention Period | Minimum 6 years from end of tax period (VAT Implementing Regulations Art. 66) | |
| 298 | | Format | Original XML (signed) + ZATCA response | |
| 299 | | Digital Signature | Must retain the signed XML with embedded UBL Extensions containing the signature | |
| 300 | | Integrity | Invoice hash chain provides tamper evidence | |
| 301 | | Medium | Electronic storage; must be accessible on demand by ZATCA | |
| 302 | | QR Code | Physical/PDF copies must display the complete TLV QR code | |
| 303 | | Language | Arabic required for invoice content; bilingual (Arabic + English) permitted | |
| 304 | |
| 305 | --- |
| 306 | |
| 307 | ## Section 9 -- Penalties for Non-Compliance |
| 308 | |
| 309 | | Violation | Penalty (SAR) | |
| 310 | |---|---| |
| 311 | | Not issuing e-invoices | 5,000 -- 50,000 per violation | |
| 312 | | Not including required fields | 5,000 -- 50,000 per violation | |
| 313 | | Not integrating with FATOORA (Phase 2) | 5,000 -- 50,000 per violation | |
| 314 | | Deleting or modifying e-invoices after issuance | 10,000 -- 50,000 per violation | |
| 315 | | Not storing e-invoices per requirements | 5,000 -- 50,000 per violation | |
| 316 | | Obstructing ZATCA officials | 5,000 -- 50,000 per violation | |
| 317 | | Repeated violations | Penalty doubled; potential business suspension | |
| 318 | |
| 319 | ZATCA may also publish violator names publicly and may suspend tax registration for severe/repeated non-compliance. |
| 320 | |
| 321 | --- |
| 322 | |
| 323 | ## Section 10 -- Interaction with Tax Skills |
| 324 | |
| 325 | ### VAT Return Integration |
| 326 | |
| 327 | - Cleared B2B invoices feed directly into ZATCA's VAT return pre-population |
| 328 | - Reported B2C invoices aggregated for VAT return box totals |
| 329 | - VAT return data (Box 1: standard-rated sales, Box 2: zero-rated, etc.) can be cross-referenced against FATOORA submission records |
| 330 | - Discrepancies between submitted e-invoices and VAT return values trigger ZATCA risk-assessment flags |
| 331 | |
| 332 | ### Credit Note Handling |
| 333 | |
| 334 | - Credit notes must reference the original invoice UUID |
| 335 | - Tax adjustments in VAT return derived from cleared credit notes |
| 336 | - ZATCA validates that credit note does not exceed original invoice value |
| 337 | |
| 338 | ### Withholding Tax |
| 339 | |
| 340 | - If withholding tax applies (certain services), the invoice must still show full VAT amount |
| 341 | - Withholding is a separate mechanism; e-invoice shows gross amounts |
| 342 | |
| 343 | ### Audit Trail |
| 344 | |
| 345 | - ZATCA maintains complete record of all cleared/reported invoices |
| 346 | - Taxpayer's records must match ZATCA's records exactly |
| 347 | - UUID + ICV provide unique identification for audit queries |
| 348 | |
| 349 | --- |
| 350 | |
| 351 | ## Disclaimer |
| 352 | |
| 353 | This skill and its outputs are provided for informational and computational purposes only and do not constitute tax, legal, or financial advice. Open Accountants and its contributors accept no liability for any errors, omissions, or outcomes arising from the use of this skill. All outputs must be reviewed and signed off by a qualified professional (such as a CPA, SOCPA member, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon. |
| 354 | |
| 355 | The most up-to-date, verified version of this skill is maintained at [openaccountants.com](https://openaccountants.com). |
| 356 |
Run this skill, then get an accountant to check it
After running the full skill pack in your AI agent, sign up and upload your worksheet. We'll connect you with a trusted accountant in our network who can review your numbers before you file.
Verification status
Research-verified
Drafted from authoritative sources (tax authority sites, Big-4 summaries). Awaiting credentialed sign-off.
Needs section-by-section practitioner review to reach accountant-verified.
Section review progress
0/33
About
Use this skill whenever asked about Saudi Arabia e-invoicing, ZATCA FATOORA platform, Phase 1 generation, Phase 2 integration, e-invoice clearance, e-invoice reporting, ZATCA API, UBL 2.1 XML for Saudi invoices, cryptographic stamp, QR code TLV encoding, ECDSA signing, CSID certificate, onboarding OTP, Simplified vs Standard tax invoice, B2B clearance, B2C reporting, or any question about generating, submitting, or troubleshooting Saudi e-invoices. Also trigger when advising on ZATCA compliance waves, XML structure, digital signature requirements, or integration architecture. ALWAYS read this skill before touching any Saudi e-invoice work.
SAty-2025
Use this skill
This skill is open source and free to use in any AI agent. Copy it, download it, or clone the repo. If you find an error, report an issue — a licensed accountant will review.