Production Ready
REST API v2

Upload Invoice to ZATCA

This API receives structured invoice data, validates compliance rules, builds a compliant UBL 2.1 XML document, generates the cryptographic hash & ECDSA digital signature, and automatically submits the invoice to the Saudi Tax Authority (ZATCA) clearance or reporting portal.

HTTP Method

POST

Content-Type

application/json

Standard Supported

ZATCA UBL 2.1

API Endpoint

POST /api/v2/upload-invoice/{type?}/{note?}

Full URL example: https://your-domain.com/api/v2/upload-invoice/Reporting/0

Authentication Headers

Requests to this endpoint are protected by the secure.api.password middleware. You must pass your configured secret API password in the Api-Password header.

Header Required Type Description
Api-Password YES string Matches the server API_PASSWORD setting in .env.
Content-Type YES string Must be application/json
Accept RECOMMENDED string Must be application/json

URL Path Parameters

Parameter Type Default Possible Values Description
{type} string Reporting Reporting | Clearance Reporting: Simplified Tax Invoice (B2C, code 0200000).
Clearance: Standard Tax Invoice (B2B, code 0100000).
{note} integer 0 0 | 1 0: Normal Tax Invoice (Type 388).
1: Credit Note (Type 383) or Debit Note (Type 381).

JSON Request Body Specification

All fields marked as required must be present in the request body.

1. Seller Information (seller)

Field Type Required Description & Validation
seller.name string YES Legal registered company name (Arabic or English).
seller.commercial_registration_number string YES Commercial Registration (CR) number (e.g. 10 digits).
seller.vat_number string YES 15-digit Tax Identification Number (must start and end with '3').
seller.building_number string YES 4-digit National Address building number (e.g. "4222").
seller.street_name string YES Street name.
seller.city_subdivision string YES District / Subdivision name.
seller.city string YES City name (e.g. "Riyadh").
seller.postal_number string YES 5-digit Saudi Postal Code (e.g. "12345").
seller.plot_identification string YES Additional 4-digit number (e.g. "1234").
seller.country string YES 2-letter ISO Country Code. Must be "SA".

2. Buyer / Client Information (client)

Field Type Required Description
client.name string YES Buyer's name or establishment title.
client.vat_number string B2B ONLY Buyer's 15-digit VAT number (Mandatory for Standard B2B Clearance).
client.commercial_registration_number string OPTIONAL Buyer CR number if available.
client.street_name, building_number, city, postal_number string B2B ONLY Buyer's national address details. Mandatory for Standard B2B.
client.country string YES 2-letter ISO Country Code (e.g. "SA").

3. Invoice Totals & Items

Field Type Required Description
invoice_number string YES Unique invoice number (e.g. "INV-2026-001").
invoice_date datetime YES ISO date format: "YYYY-MM-DDTHH:MM:SS" (e.g. "2026-10-27T14:30:00").
total_without_vat numeric YES Total taxable amount before VAT and discounts (2 decimals).
vat numeric YES Total VAT amount (typically 15% of total_without_vat - discount).
discount numeric OPTIONAL Document level discount amount (default 0).
invoice_items array YES (min 1) Array of invoice item objects (see below).
↳ name string YES Description of good or service.
↳ quantity integer YES Invoiced quantity (minimum 1).
↳ tax_class_code string YES "S" (Standard 15%), "Z" (Zero-rated), "E" (Exempt), "O" (Out of Scope).
↳ tax_percent numeric YES Tax rate percentage (e.g. 15 for standard rate).
↳ price numeric YES Unit price or line amount before VAT.
↳ vat numeric YES VAT amount for this line (price * 15%).
↳ total numeric YES Line total inclusive of VAT (price + vat).

4. Additional Fields for Credit / Debit Notes ({note} = 1)

Field Type Required Description
note_type string YES if note=1 "cn" for Credit Note (383) or "dn" for Debit Note (381).
reference_number string YES if note=1 The original invoice number being credited or debited.
reason string OPTIONAL Reason for cancellation, return, or price adjustment.

Code Examples & Payload

curl -X POST "https://your-domain.com/api/v2/upload-invoice/Reporting/0" \
  -H "Api-Password: YOUR_SECRET_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "seller": {
        "name": "شركة الانتاج المبارك للتجارة",
        "commercial_registration_number": "4650197790",
        "vat_number": "302008161400003",
        "street_name": "Main Street",
        "building_number": "4222",
        "plot_identification": "Plot 101",
        "city_subdivision": "Subdivision A",
        "city": "Riyadh",
        "postal_number": "12345",
        "country": "SA"
    },
    "client": {
        "name": "مؤسسة زاد فطور وأكثر",
        "commercial_registration_number": "7049710465",
        "vat_number": "312945008500003",
        "street_name": "النخيل",
        "building_number": "2510",
        "plot_identification": "6",
        "city_subdivision": "الاول",
        "city": "الحناكيه",
        "postal_number": "42651",
        "country": "SA"
    },
    "invoice_number": "INV-2026-001",
    "invoice_date": "2026-10-27T14:30:00",
    "total_without_vat": 126.09,
    "vat": 18.91,
    "discount": 0,
    "invoice_items": [
        {
            "name": "بيض رقم ٣ - L2",
            "quantity": 1,
            "tax_class_code": "S",
            "tax_percent": 15,
            "price": 126.09,
            "vat": 18.91,
            "total": 145.00
        }
    ]
}'

Response Payloads

200 / 202 OK Invoice Accepted & Reported to ZATCA
{
    "validationResults": {
        "infoMessages": [
            {
                "type": "INFO",
                "code": "XSD_ZATCA_VALID",
                "category": "XSD validation",
                "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                "status": "PASS"
            }
        ],
        "warningMessages": [],
        "errorMessages": [],
        "status": "PASS"
    },
    "reportingStatus": "REPORTED"
}
200 OK Invoice Already Uploaded (Idempotent)
{
    "status": "already_uploaded",
    "reportingStatus": "REPORTED",
    "message": "Invoice #INV-2026-001 has already been uploaded and Reported to ZATCA.",
    "invoice_number": "INV-2026-001",
    "current_status": "Reported",
    "invoice_hash": "J+2E5gJlvphoKAXSoU5E4PUitDDbP2UlIelTyoPpk4A=",
    "uuid": "8720db67-010f-43c0-a0ca-89fc65efdec3",
    "upload_date": "2026-10-27T09:29:33.000000Z",
    "zatca_response": {
        "validationResults": {
            "status": "PASS"
        },
        "reportingStatus": "REPORTED"
    }
}
429 Too Many Requests Concurrent / Rapid Upload Spam Blocked
{
    "status": "processing",
    "message": "Invoice #INV-2026-001 is currently being processed. Please wait a moment and do not submit multiple times."
}
400 Bad Request ZATCA Validation Rejection
{
    "validationResults": {
        "infoMessages": [],
        "warningMessages": [],
        "errorMessages": [
            {
                "type": "ERROR",
                "code": "BR-CO-14",
                "category": "EN_16931",
                "message": "Invoice total VAT amount (BT-110) must equal the sum of VAT breakdown tax amounts.",
                "status": "ERROR"
            }
        ],
        "status": "ERROR"
    },
    "reportingStatus": "NOT_REPORTED"
}
401 Unauthorized Invalid or Missing Api-Password Header
{
    "error": "Unauthorized"
}

ZATCA Compliance Rules & Best Practices

15% VAT Consistency

Ensure that each line item VAT strictly equals round(price * 15%, 2) and that the sum of line VATs equals the invoice header vat.

15-Digit VAT Number

Saudi VAT numbers must consist of exactly 15 numeric digits, starting with '3' and ending with '3' (e.g. 302008161400003).

UTC / Saudi Timezone Format

invoice_date must be provided in ISO 8601 format (YYYY-MM-DDTHH:MM:SS). Future dates are rejected by ZATCA.

Unit Price vs Line Total

When quantity > 1, our API automatically normalizes whether you pass unit price or line total to avoid taxable amount discrepancies.