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 / Reporting Simplified 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
Reporting Simplified Invoice - Documentation - API Documentation

ZATCA Integration API Documentation

Overview

This endpoint creates and reports simplified XML invoices to ZATCA (Saudi Arabian tax authority) with the given parameters.

Report Simplified Invoice

Endpoint

POST /api/ZatcaIntegration/ReportInvoice

Authentication

Requires JWT authentication with TenantId claim:

Authorization: Bearer <your-license-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 (SIMPLIFIED or TAXINVOICE) SIMPLIFIED
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-17
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-17
LatestDelivery string No Latest delivery date (yyyy-mm-dd) 2025-07-17
PaymentMethod string Yes Payment method code 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

Sample Request

{
  "UnitId": "8874454154755",
  "InvoiceNo": "000101",
  "DocType": "SIMPLIFIED",
  "DocForm": "INVOICE",
  "Note": "Direct Customer Sale",
  "IssueDate": "2025-07-17",
  "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"
    }
  ]
}

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

Sample Response

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

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 reporting

Sample Usage

cURL Example

curl -X POST \
  https://your-api.com/api/ZatcaIntegration/ReportInvoice \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "UnitId": "8874454154755",
    "InvoiceNo": "000101",
    "DocType": "SIMPLIFIED",
    "DocForm": "INVOICE",
    "IssueDate": "2025-07-17",
    "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"
      }
    ]
  }'
}