# 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 ``` {% hint style="info" %} Replace the `{{BASE_URL}}` with the one mentioned [here](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference) based on whether you are using sandbox or production. {% endhint %} {% hint style="danger" %} Rate Limit : 1000 API requests per minute {% endhint %} ### 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](https://drive.google.com/file/d/1wdhQ3kgJAkOdjVDrIR_9wqISYuuk5qEV/view) | ### 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 \,

\

| ### 1.7 **Sample Request** Request Body [**Reporting Signed XML**](https://drive.google.com/file/d/1wdhQ3kgJAkOdjVDrIR_9wqISYuuk5qEV/view?usp=sharing) ### **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) ```json { "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)** ```json { "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** ```json { "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.