Documentation Topics

Quick Start Guide Signup & Account Management Free Tenant & Subscriptions Add EGS Unit Reporting Simplified Invoice C# Code Samples of Reporting Api Python Code Samples of Reporting Api Clearing Standard Invoice C# Code Samples of Clearing Api Python Code Samples of Clearing Api Additional Zatca Utiilities Add Customers Download Invoices Subscriptions and License aqusition
Documentation / Clearing Standard Invoice
Welcome to the system documentation. Select a topic from the sidebar to learn more.

Quick Start

Get up and running quickly with our step-by-step guides.

Get Started

Video Tutorials

Watch our video tutorials to see the system in action.

Watch Videos
Clearing Standard Invoice - Documentation - API Documentation

ZATCA Integration API Documentation

Overview

This endpoint creates and clears standard XML invoices with ZATCA (Saudi Arabian tax authority) compliance.

Clear Standard Invoice

Endpoint

POST /api/ZatcaIntegration/ClearInvoice

Authentication

Requires JWT authentication with TenantId claim:

Authorization: Bearer <your-jwt-token>

Content-Type

application/json

Request Parameters

Parameter Type Required Description Example
UnitId string Yes EGS Unit ID 8874454154755
InvoiceNo string Yes Invoice number 000101
DocType string Yes Document type (TAXINVOICE) TAXINVOICE
DocForm string Yes Document form (INVOICE, CREDITNOTE, DEBITNOTE) INVOICE
Note string No Invoice note Direct Customer Sale
IssueDate string Yes Invoice issue date (yyyy-mm-dd) 2025-07-20
IssueTime string Yes Invoice issue time 03:06:14
DocCurrency string Yes Document currency SAR
ActualDelivery string No Actual delivery date (yyyy-mm-dd) 2025-07-20
LatestDelivery string No Latest delivery date (yyyy-mm-dd) 2025-07-20
PaymentMethod string Yes Payment method (Cash/CreditCard/BankTransfer) Cash
CustomerName string No Customer name Cash Customer
PreviousInvoiceRef string No Previous invoice reference for credit/debit note INV-00020

AllowanceCharges

Parameter Type Required Description Example
Type string Yes ALLOWANCE or CHARGE ALLOWANCE
Reason string No Allowance/charge reason Seasonal Discount
Amount decimal Yes Allowance/charge amount 1.00
TaxRate decimal Yes Tax rate 15.00
TaxCategory string Yes Tax category (S, Z, or E) S

InvoiceLines

Parameter Type Required Description Example
LineNo int Yes Line number 1
ItemName string Yes Item description Laptop Dell Latitude E5450
Quantity decimal Yes Item quantity 1
UnitCode string Yes Unit code NOS
TaxCategory string Yes Tax category (S, Z, or E) S
TaxRate decimal Yes Tax rate 15
ItemPrice decimal Yes Unit price 750
Currency string Yes Currency code SAR
BaseQuantity decimal No Item base quantity 1
BaseUnitCode string No Base unit code NOS

PrePayments

Parameter Type Required Description Example
Amount decimal Yes Prepaid amount 10.00
Quantity decimal Yes Prepaid quantity 1
UnitCode string Yes Unit code PCE
ItemName string Yes Item description Laptop Charger
TaxCategory string Yes Tax category (S, Z, or E) S
Rate string Yes VAT rate 15
Currency string Yes Currency code SAR
BaseQuantity decimal Yes Base quantity 1
BaseUnit string Yes Base unit code PCE
PrePaidInvoiceNo string Yes Prepaid invoice number 000454
PrePaidInvoiceIssueDate string Yes Prepaid invoice issue date (dd/MM/yyyy) 07/05/2025
PrePaidInvoiceIssueTime string Yes Prepaid invoice issue time 06:08:14

Sample Request

{
  "UnitId": "8874454154755",
  "InvoiceNo": "000101",
  "DocType": "TAXINVOICE",
  "DocForm": "INVOICE",
  "Note": "Direct Customer Sale",
  "IssueDate": "2025-07-20",
  "IssueTime": "03:06:14",
  "DocCurrency": "SAR",
  "PaymentMethod": "Cash",
  "CustomerName": "Cash Customer",
  "AllowanceCharges": [
    {
      "Type": "ALLOWANCE",
      "Reason": "Seasonal Discount",
      "Amount": 1.00,
      "TaxRate": 15.00,
      "TaxCategory": "S"
    }
  ],
  "InvoiceLines": [
    {
      "LineNo": 1,
      "ItemName": "Laptop Dell Latitude E5450",
      "Quantity": 1,
      "UnitCode": "NOS",
      "TaxCategory": "S",
      "TaxRate": 15,
      "ItemPrice": 750,
      "Currency": "SAR"
    }
  ],
  "PrePayments": [
    {
      "Amount": 10.00,
      "Quantity": 1,
      "UnitCode": "PCE",
      "ItemName": "Laptop Charger",
      "TaxCategory": "S",
      "Rate": "15",
      "Currency": "SAR",
      "BaseQuantity": 1,
      "BaseUnit": "PCE",
      "PrePaidInvoiceNo": "000454",
      "PrePaidInvoiceIssueDate": "07/05/2025",
      "PrePaidInvoiceIssueTime": "06:08:14"
    }
  ]
}

Response

Field Type Description Example
status string Status of reporting success
message string Error or success message reported
icv string Invoice counter value 1
hash string Invoice hash value a1b2c3d4e5
uuid string Invoice unique ID 123e4567-e89b-12d3-a456-426614174000
qrcodeValue string QR code value base64 encoded string
ClearedInvoice string Cleared invoice in Base64 base64 encoded XML

Sample Response

{
  "status": "success",
  "message": "reported",
  "icv": "1",
  "hash": "a1b2c3d4e5",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "qrcodeValue": "base64encodedstring...",
  "ClearedInvoice": "base64encodedXML..."
}

Error Responses

Status Code Description
400 Bad Request Invalid input data or validation errors
401 Unauthorized Missing or invalid JWT token
500 Internal Server Error Server-side error during invoice clearing

Sample Usage

cURL Example

curl -X POST \
  https://your-api.com/api/ZatcaIntegration/ClearInvoice \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "UnitId": "8874454154755",
    "InvoiceNo": "000101",
    "DocType": "TAXINVOICE",
    "DocForm": "INVOICE",
    "IssueDate": "2025-07-20",
    "IssueTime": "03:06:14",
    "DocCurrency": "SAR",
    "PaymentMethod": "Cash",
    "InvoiceLines": [
      {
        "LineNo": 1,
        "ItemName": "Laptop Dell Latitude E5450",
        "Quantity": 1,
        "UnitCode": "NOS",
        "TaxCategory": "S",
        "TaxRate": 15,
        "ItemPrice": 750,
        "Currency": "SAR"
      }
    ]
  }'
}