Send Signed E-Invoice XML To ZATCA

Send a valid signed E-Invoice XML file to ZATCA for clearance or reporting.

1.1 Request Method

POST

1.2 Request URL

{{BASE_URL}}/v2/einvoices/generate-with-file-offline

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Rate Limit : 1000 API requests per minute

1.3 Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	Cannot be empty	Mandatory. User auth token.
vat	String	Cannot be empty	Mandatory. VAT or Group VAT of the entity.
device-id	String	MaxLength: 36	Mandatory. The Device ID registered with ClearTax.

1.4 Request Path Params

Parameter	Data Type	Field Validations	Description

1.5 Request Query Params

Parameter	Data Type	Field Validations	Description

1.6 Request Body

Parameter	Data Type	Field Validations	Description
file	form-data	NA	Mandatory. The XML file as per ZATCA specification. Example: Reporting Signed XML

1.6.1 Requirement of Critical Fields

Fields	Comments
UUID	Mandatory. A Universal Unique Identifier is a 128-bit value used to uniquely identify an object or entity on the internet.
ICV	Mandatory. This is an atomically increasing counter.
PIH	Mandatory. Previous Invoice Hash. Hash code of the previous invoice has to be sent.
InvoiceHash	Mandatory. Hash value of current invoice xml by removing tags <ext:UBLExtensions>, <cac:AdditionalDocumentReference:QRCode>

1.7 Sample Request

Request Body

Reporting Signed XML

1.8 Response Status Codes

HTTP Status Code	Description
200	For any complete operation - pass / warning / error
400	-
401	If the user is not authenticated for the operation
403	If the user is not authorized for the operation
429	Too Many Requests
5xx	Unhandled exception

1.9 Response Schema

Parameter	Data Type	Field Validations	Description
validationResults	Object	Cannot be null	Refer below
clearedInvoice	String	-	For clearance, this field will have a base64 encoded cleared XML as string For reported, this will be null
clearanceStatus	String	REPORTED / NOT_REPORTED / ACCEPTED_WITH_WARNING / CLEARED / NOT_CLEARED, PENDING	For clearance: CLEARED, NOT_CLEARED, ACCEPTED_WITH_WARNING, PENDING For reported: REPORTED, NOT_REPORTED, ACCEPTED_WITH_WARNING, PENDING

1.9.1 Validation Results Object

Parameter	Data Type	Field Validations	Description
infoMessages	Array of Object	Cannot be null or empty	Will always have some info. Refer below for the structure.
warningMessages	Array of Object	Cannot be null or empty	This array is not empty in case of any warning at the time of reporting/clearance. Refer below for the structure.
errorMessages	Array of Object	Cannot be null or empty	This array is not empty in case of any error at the time of reporting/clearance. Refer below for the structure.
status	String	PASS / WARNING / ERROR	Indicates the response status of the complete API.

1.9.2 infoMessages/warningMessages/errorMessages Object

Parameter	Data Type	Field Validations	Description
type	String	INFO / WARNING / ERROR are the possible values	Indicates the type of the message object
code	String	Cannot be null	ZATCA specific code to identify the message object
category	String	Cannot be null	ZATCA specific category to identify the message object
message	String	Cannot be null	ZATCA specific message
status	String	PASS / WARNING / ERROR	PASS - infoMessages WARNING - warningMessages ERROR - errorMessages

1.10 Sample Response (Success with warning)

{
    "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": [
            {
                "type": "WARNING",
                "code": "BR-KSA-37",
                "category": "KSA",
                "message": "The seller address building number must contain 4 digits.",
                "status": "WARNING"
            },
            {
                "type": "WARNING",
                "code": "BR-KSA-64",
                "category": "KSA",
                "message": "Seller Address Additional number (KSA-23) must be 4 digits.",
                "status": "WARNING"
            }
        ],
        "errorMessages": [],
        "status": "WARNING"
    },
    "clearedInvoice": null,
    "clearanceStatus": "REPORTED"
}

1.11 Sample Response (Client Error)

{
    "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": [
            {
                "type": "ERROR",
                "code": "BR-KSA-64",
                "category": "KSA",
                "message": "Seller Address Additional number (KSA-23) must be 4 digits.",
                "status": "ERROR"
            },
            {
                "type": "ERROR",
                "code": "invoiceHash_QRCODE_INVALID",
                "category": "QRCODE_VALIDATION",
                "message": "Invoice xml hash does not match with qr code invoice xml hash",
                "status": "ERROR"
            }
        ],
        "status": "ERROR"
    },
    "clearedInvoice": null,
    "clearanceStatus": "NOT_REPORTED"
}

1.12 Sample Response (Server Error) - status code 500

{
    "ErrorList": [
        {
            "ErrorCode": "30040102",
            "ErrorMessage": "Was not able to report the invoice. Please try again later",
            "ErrorSource": "CLEARTAX"
        }
    ]
}

1.13 API Validations

There are no validations from Clear for this API.

1.14 API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the Authentication token is not present or is invalid, the API will return HTTP Status Code 401.

2. Each customer is allowed to send a limited number of requests per minute to prevent server overload. If the limit is exceeded, the server will respond with a 429 Too Many Requests status code.

3. If the Authentication token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose Authentication token is used, should have an “Admin” role for the particular VAT used in the request.