ZATCA Fatoora Portal Integration

Complete API Guide for Phase 2 E-Invoicing Compliance

Last updated: March 30, 2026

📋 Prerequisites for Integration

Active ZATCA taxpayer account with valid TRN (Tax Registration Number)
CSD certificate from ZATCA-approved provider (Geotrust, Digicert, etc.)
Technical team with API development experience (PHP, cURL, REST APIs)
Sandbox environment access for testing before production
XML generation capability for UBL 2.1 format
QR code generation with TLV encoding and Base64

🔗 Fatoora API Endpoints

Endpoint Name	Endpoint URL	Method	Description
Clearance (B2B)	https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance	POST	Real-time validation for B2B invoices
Reporting (B2C)	https://api.fatoora.zatca.gov.sa/api/v1/invoice/reporting	POST	24-hour submission for B2C invoices
CSR Generation	https://api.fatoora.zatca.gov.sa/api/v1/csr	POST	Generate Certificate Signing Request
Compliance Check	https://sandbox.fatoora.zatca.gov.sa/api/v1/compliance	POST	Validate XML before submission

🔐 Authentication (OAuth 2.0)

Fatoora APIs use OAuth 2.0 with client credentials flow. After CSD certificate installation, you must obtain credentials from ZATCA portal:

Login to ZATCA Fatoora portal with your taxpayer account
Navigate to Developer Settings → API Credentials
Generate new client_id and client_secret
Store credentials securely (they will not be shown again)
Use credentials to obtain access_token via OAuth 2.0 endpoint
Include access_token in Authorization header for all API calls

Token endpoint: https://api.fatoora.zatca.gov.sa/oauth2/token

⚙️ Step-by-Step Integration Process

✓ 1. Register in ZATCA Fatoora portal and obtain CSR (Certificate Signing Request)

✓ 2. Purchase and install CSD certificate from approved provider (5-10 business days)

✓ 3. Generate API credentials (client_id, client_secret) from ZATCA portal

✓ 4. Test all API calls in Sandbox environment before production

✓ 5. Implement XML invoice generation in UBL 2.1 format with all mandatory fields

✓ 6. Generate QR code with cryptographic stamp (TLV encoding + Base64)

✓ 7. Submit invoices via Clearance endpoint (B2B) or Reporting endpoint (B2C)

✓ 8. Handle ZATCA responses appropriately (cleared/rejected/reported status)

✓ 9. Implement webhook or callback URL for asynchronous responses

✓ 10. Move to production after successful sandbox testing

💻 Sample API Call (PHP cURL)

Here is a complete PHP cURL example for submitting an invoice to the Clearance endpoint:

<?php
// ZATCA Fatoora API - Clearance Invoice Submission
$access_token = "YOUR_ACCESS_TOKEN";
$xml_invoice_data = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice>...</Invoice>";
$qr_base64 = "Base64EncodedQRDataHere";

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $access_token,
        "Content-Type: application/json",
        "Accept-Language: en"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "invoice" => base64_encode($xml_invoice_data),
        "qr_code" => $qr_base64
    ])
]);

$response = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$curl_error = curl_error($curl);
curl_close($curl);

if ($http_code == 200) {
    $result = json_decode($response, true);
    echo "Invoice Status: " . $result["status"];
} else {
    echo "Error: HTTP $http_code - $curl_error";
}
?>

📨 Understanding ZATCA API Responses

CLEARED

Invoice accepted by ZATCA. You can share it with buyer.

Action: Proceed with delivery

REJECTED

Invoice failed validation. Check XML structure and fields.

Action: Correct and resubmit new invoice

REPORTED

Invoice accepted for reporting (no real-time validation).

Action: No further action needed

PENDING

Invoice under review. Wait for final status.

Action: Implement webhook to receive update

⚠️ Error Handling & Status Codes

HTTP Code	Meaning	Solution
200	Success - Invoice processed correctly	Continue normal flow
400	Bad Request - Invalid XML format or missing mandatory fields	Validate XML against UBL 2.1 schema
401	Unauthorized - Authentication failed	Check access_token validity and regenerate if expired
403	Forbidden - CSD certificate expired or invalid	Renew CSD certificate immediately
429	Rate Limit Exceeded - Too many requests	Implement exponential backoff and reduce request rate
500	Internal Server Error - ZATCA server issue	Retry with exponential backoff (max 3 attempts)
503	Service Unavailable - Maintenance or overload	Wait and retry after 5-10 minutes

🧪 Sandbox Environment (Testing)

Always test your integration in the ZATCA Sandbox before going live:

Test CSD certificates available for free
Simulated API responses for all endpoints
No real tax validation - safe for testing
Same API structure as production

🔗 https://sandbox.fatoora.zatca.gov.sa

✅ Best Practices for Production

Implement automatic token refresh before expiry (tokens last 1 hour)
Store all API responses in database for audit trail
Implement retry logic with exponential backoff for failed requests
Monitor rate limits and implement queue system for high volume
Use webhooks for asynchronous status updates
Keep CSD certificate expiry reminders (renew 60 days before expiry)
Test all changes in sandbox before production deployment
Maintain detailed logs of all API calls and responses

❓ Frequently Asked Questions

Q: How long does API response take?

A: Clearance endpoint: 2-5 seconds (synchronous). Reporting endpoint: Response within seconds (asynchronous), but invoice status may update later via webhook or status check endpoint.

Q: What is the rate limit for Fatoora APIs?

A: Standard limit is 10 requests per second. For higher volumes (enterprise), contact ZATCA support to request increased limits. Implement queue system for bulk submissions.

Q: Can I use the same access token for multiple requests?

A: Yes, access tokens typically expire after 1 hour. Implement auto-refresh logic to obtain new token before expiry. Do not request new token for every request.

Q: What if my invoice is rejected?

A: You cannot edit a rejected invoice. You must correct the issue in your system and submit a brand new invoice with a new invoice number. Rejected invoices cannot be resubmitted.

Q: How do I get a test CSD certificate for sandbox?

A: ZATCA Sandbox provides test CSD certificates for free. You can generate them directly from the sandbox portal without purchasing from commercial providers.

Q: What is the difference between synchronous and asynchronous APIs?

A: Clearance is synchronous - you wait for immediate response. Reporting is asynchronous - you submit and receive acknowledgement, but final status comes later via webhook.

Q: Do I need static IP for Fatoora API?

A: No, static IP is not required. However, ensure your server's outbound IP is not blocked by ZATCA firewall. Use reliable hosting provider.

Q: What webhook URL format is accepted?

A: ZATCA accepts HTTPS endpoints only. URL must be publicly accessible. Use POST method to receive JSON payloads with invoice status updates.

📚 Related ZATCA Resources

📘 Complete Guide 🔐 CSD Certificate ⚖️ Clearance vs Reporting 📄 Tax Invoice Format