sa: add Saudi Arabia tax regime

[enrique-fernandez-polo]

Why Saudi Arabia

Saudi Arabia is the strongest next candidate for GOBL regime expansion, scoring highest across commercial urgency, technical fit, documentation quality, and strategic leverage.

Market opportunity. The ZATCA e-invoicing market is valued at $143M (2024), projected to reach $594M by 2033 at 15.3% CAGR. Phase 2 integration has reached Wave 24 (SAR 375K threshold, June 2026), approaching universal coverage of all VAT-registered businesses.

Technical fit. ZATCA uses UBL 2.1 XML based on EN 16931 — GOBL's existing gobl.ubl converter handles the bulk of XML generation. The regime sits cleanly in GOBL's architecture: 15% VAT, 15-digit TIN validation, ZATCA-specific identity types, and well-documented business rules (BR-KSA series).

Strategic multiplier. Every GCC country is following Saudi Arabia's lead: UAE mandates e-invoicing from January 2027, Oman launches its Fawtara pilot in August 2026, Bahrain has active consultations, and Qatar has issued platform tenders. Building the SA regime directly accelerates five additional country implementations.

Documentation quality. All specifications are published in English at zatca.gov.sa, including the XML Implementation Standard v1.2, Data Dictionary, and Developer Portal Manual. The sandbox environment provides full API testing.

Changes

This PR adds the foundational Saudi Arabia tax regime (regimes/sa/) covering:

• VAT tax categories: 15% standard rate (effective July 2020, previously 5% from January 2018), plus zero-rated, exempt, reverse-charge, export, and outside-scope categories mapped to standard GOBL tax keys
• TIN validation: 15-digit format with Luhn check digit verification per ZATCA requirements
• Seller identity types (BT-29-1): CRN (Commercial Registration), MOM (MOMRAH License), MLS (MHRSD License), 700 (Unified Number), SAG (MISA License), OTH (Other)
• Buyer identity types (BT-46-1): TIN, NAT (National ID), IQA (Iqama), PAS (Passport), GCC (GCC ID), OTH — plus all seller codes per BR-KSA-14
• Invoice validation rules: Supplier TaxID required (BR-KSA-39), supplier name required (BR-06), customer name and identification required on standard invoices (BR-KSA-42, BR-KSA-81), simplified invoices skip customer requirements
• Invoice scenarios: Automatic correction type mapping for credit/debit notes
• 5 example invoices: standard, simplified, credit note, exempt, and reverse-charge — with calculated output envelopes

Out of Scope

The following ZATCA Phase 2 compliance areas are intentionally not covered by this regime PR:

1. ZATCA tax category mappings and exemption reason codes — UNTDID 5305 tax category codes, VATEX-SA exemption codes, and document type scenarios
2. UBL 2.1 XML generation — ZATCA-compliant UBL 2.1 output with KSA extensions and schematron validation
3. Cryptographic signing — XAdES-BES digital signatures, CSID certificate management, and SHA-256 invoice hash chaining
4. QR code generation — TLV-encoded Base64 QR codes with the 9 mandatory ZATCA tags
5. Fatoora platform API integration — EGS onboarding, CSID lifecycle, clearance (B2B) and reporting (B2C) API submission
6. Additional compliance requirements — Archival, sandbox certification, and wave-based rollout compliance

Sources

• ZATCA E-Invoicing Portal
• ZATCA XML Implementation Standard v1.2
• SA TIN Guide (LookupTax)
• ERPGulf ZATCA Tax Categories

Test coverage

• regimes/sa/: 94.0% statement coverage
• All tests pass: go test ./regimes/sa/...
• Full suite: go test ./... passes (no regressions)

Pre-Review Checklist

• Opened this PR as a draft
• Read the CONTRIBUTING.md guide.
• Performed a self-review of my code.
• Added thorough tests with at least 90% code coverage.
• Modified or created example GOBL documents to show my changes in use, if appropriate.
• Added links to the source of the changes in tax regimes or addons, either structured or in the comments.
• Run go generate . to ensure that the Schemas and Regime data are up to date.
• Reviewed and fixed all linter warnings.
• Been obsessive with pointer nil checks to avoid panics.
• Updated the CHANGELOG.md with an overview of my changes.
• Requested a review from Copilot and fixed or dismissed (with a reason) all the feedback raised.

Only after checking off all the previous items:

• Marked this PR as ready for review and requested one from @samlown.

[codecov]

Codecov Report

❌ Patch coverage is 96.07843% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.89%. Comparing base (8ca0f6c) to head (5901a1d).

Files with missing lines	Patch %	Lines
regimes/sa/invoices.go	93.22%	2 Missing and 2 partials ⚠️
regimes/sa/identities.go	90.47%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #740      +/-   ##
==========================================
+ Coverage   92.86%   92.89%   +0.02%     
==========================================
  Files         331      335       +4     
  Lines       17260    17413     +153     
==========================================
+ Hits        16029    16176     +147     
- Misses        867      870       +3     
- Partials      364      367       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds a new Saudi Arabia (SA) tax regime to GOBL, including VAT category definitions, identity types, invoice validation rules, and example documents/data artifacts to support regime expansion.

Changes:

• Introduces regimes/sa/ with regime registration, VAT category/rates, identity definitions/normalization, scenario notes, and invoice validation rules.
• Adds SA to the regimes registry and to the tax regime code schema; generates data/regimes/sa.json.
• Adds SA invoice examples (YAML inputs + generated JSON envelopes) and updates CHANGELOG.md.

Reviewed changes

Copilot reviewed 21 out of 26 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
regimes/sa/sa.go	Defines and registers the SA regime (currency, timezone, validators/normalizers, scenarios, corrections).
regimes/sa/tax_categories.go	Adds SA VAT category using global VAT keys and historical standard rates (15%/5%).
regimes/sa/tax_categories_test.go	Tests SA VAT rate definitions and effective dates.
regimes/sa/tax_identity.go	Adds SA TIN format validation (currently regex-only).
regimes/sa/tax_identity_test.go	Tests SA TIN validation and normalization behaviors.
regimes/sa/identities.go	Defines seller/buyer identity type codes, normalization, and type-specific validation.
regimes/sa/identities_test.go	Tests identity type constants, validation, and normalization.
regimes/sa/invoices.go	Implements SA invoice validation rules for supplier/customer requirements and simplified behavior.
regimes/sa/invoices_test.go	Tests invoice validation scenarios (supplier/customer requirements; simplified vs standard; zero/exempt lines).
regimes/sa/scenarios.go	Adds scenario-driven legal notes for reverse-charge and simplified invoices.
regimes/sa/scenarios_test.go	Tests scenario notes are applied as expected.
regimes/regimes.go	Registers the SA regime via side-effect import.
data/schemas/tax/regime-code.json	Adds "SA" to the allowed regime codes schema.
data/regimes/sa.json	Generated SA regime definition data.
examples/sa/invoice-sa-*.yaml	Adds SA example invoice inputs (standard, simplified, reverse-charge, exempt, credit-note).
examples/sa/out/invoice-sa-*.json	Adds generated envelopes for the SA example invoices.
CHANGELOG.md	Notes addition of the new SA regime.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[samlown]

Thanks for this! Looks good, although I think the sources of data need to be double checked. For example, where can the latest tax rates be found? What is the source for the list of identity types? Copilot also came up with a few suggestions.

[samlown]

There is no short version of the name?

[enrique-fernandez-polo]

It looks like there is one "ض.ق.م" Updated

[samlown]

This breaks away from the standard pattern of using ValidateStruct and looses the field attribution. Also, as stated by Copilot, the it appears to be missing a Luhn check.

[enrique-fernandez-polo]

I misunderstood a comment in another PR about how to use validation.Match My mistake

[samlown]

Are you completely sure about this? Some countries often apply thresholds before registering for a VAT number.

[enrique-fernandez-polo]

I struggled with this one. There is a mandatory VAT registration threshold of SAR 375,000 (and SAR 187,500 for voluntary), so not all businesses issuing invoices have a TIN.

At the same time, BR-KSA-39 requires the supplier's VAT registration number on all e-invoices.

The required TaxID should reside in the ZATCA add-on that verifies its presence when creating the e-invoice, not in the base regime. I think I mixed law and e-invoicing in some other requirements

[samlown]

Not sure I understand this... this code is not the same as the Tax ID?

[samlown]

I couldn't see any details in this page about VAT tax rates specifically. The objective here is to know where to look exactly when a tax rate change is expected.

[enrique-fernandez-polo]

You're right, that page was about e-invoicing and didn't have VAT rate details. Updated the source URL to the ZATCA VAT Rules & Regulations page

[samlown]

Just in general here, this codes feel very specific for an implementation as opposed to a tax Regime which is mostly focussed on tax law. Are these all standard Type codes? I don't see a source document to be able to verify. Passport for example already has a specific key (passport) inside the org.Identity definition.

[enrique-fernandez-polo]

Ok now I get it. These codes (TIN, NAT, IQA, PAS, GCC, OTH) are ZATCA e-invoicing scheme IDs for BT-29-1/BT-46-1 They're implementation-specific, not tax law