Fatoora API Integration Guide — Connect Your System to ZATCA Phase 2

What is Fatoora API integration?

Fatoora is ZATCA's e-invoicing platform. Phase 2 integration means your E-Invoice Generation Solution (EGS) talks to Fatoora's APIs — not just generating QR codes locally like Phase 1.

Integration covers:

• Registering EGS units (one per branch/device that issues invoices)
• Obtaining CSID certificates (compliance + production)
• Signing invoices with ECDSA (secp256k1)
• Clearing B2B (Standard) invoices before delivery
• Reporting B2C (Simplified) invoices within 24 hours
• Maintaining the PIH chain (Previous Invoice Hash) per EGS unit

Fatoora integration paths

Path	Best for	Time to first cleared invoice
In-house	Large ERP teams with crypto/XML expertise	Weeks to months
Middleware API (Esnad)	SaaS, POS, agencies, mid-size IT	Hours
Off-the-shelf ERP module	Businesses on supported ERPs	Days (if module exists)

Most teams underestimate UBL 2.1 Saudi profile details, certificate renewal, retry logic when Fatoora is slow, and B2B vs B2C routing.

Step 1: Fatoora portal & EGS unit

1. Log in to Fatoora with your VAT registration.
2. Confirm your Phase 2 wave and deadline (see our Wave 24 guide).
3. Create an EGS unit for each issuing device or logical branch.
4. During onboarding you'll receive an OTP — needed to obtain production CSID.

With Esnad, you create the EGS via API or dashboard; we generate keys, CSR, and run the compliance flow — you paste the OTP once.

Step 2: CSID certificates

ZATCA uses a two-step certificate flow:

1. Compliance CSID — issue test invoices in sandbox; ZATCA validates format and signing.
2. Production CSID — after compliance checks pass, switch to live clearance/reporting.

Certificates expire (typically one year). Missing renewal breaks all submissions — plan alerts and an API-driven renewal path.

Step 3: Invoice format & signing

Each invoice must be:

• UBL 2.1 XML with the Saudi e-invoicing profile (namespaces, field order, tax categories)
• Digitally signed (ECDSA secp256k1, embedded in UBL extension)
• QR code (TLV for B2C; includes hash/signature tags in Phase 2)

DIY teams often spend the most time here. Middleware APIs accept JSON and return cleared XML + UUID + QR.

Step 4: Clearance (B2B) vs reporting (B2C)

• B2B Standard — Submit to Fatoora before sending the invoice to the buyer. Only deliver after clearance (HTTP 200 + cleared status).
• B2C Simplified — Issue first; report to ZATCA within 24 hours.

Read more: B2B vs B2C clearance and reporting.

Step 5: Sandbox → production

Always test in ZATCA sandbox:

• Wrong VAT category or missing buyer ID → rejection
• PIH mismatch → chain break on next invoice
• Clock skew → timestamp validation errors

When ready, swap to production CSID and EGS. Monitor first live invoices closely.

See the dashboard before you integrate

Not sure what a production-ready setup looks like? Explore our live dashboard demo — read-only portal with sample invoices, analytics, EGS units, and API keys. No signup.

When Esnad is the faster Fatoora integration

If you want Fatoora API integration without owning XML, crypto, and retry queues:

curl -X POST https://api.esnadapi.com/v1/invoices \
  -H "Authorization: Bearer zatca_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "invoice_number": "INV-001", ... }'

We handle UBL, signing, PIH, clearance/reporting, webhooks, and 6-year archive. You integrate once.

---

Request sandbox trial → · Explore live demo →