Generate E-Invoice
Generate a valid E-Invoice with JSON payload and send it to ZATCA for clearance or reporting.
Request Method
POST
Request URL
Replace the {{BASE_URL}}
with the one mentioned here based on whether you are using sandbox or production.
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. |
branch | String | Should be a valid branch from the user account | Optional. Branch name (store name) added in the user account which maps to a VAT or Group VAT of the entity. |
accept-language | String | Enum: ar, en | Optional. Language of error message from ZATCA. ar - Arabic en - English Default: en. |
Request Path Params
There are no path parameters for this API.
Request Query Params
There are no query parameters for this API.
Request Body
Parameter | Data Type | Field Validation | Description |
---|---|---|---|
DeviceId | String | MaxLength: 36 | Mandatory. The Device ID registered with ClearTax. Refer to How to get a Device ID? |
EInvoice | Object | NA | Mandatory. E-Invoice object |
CustomFields | Object | NA | Optional. Custom Fields object |
Custom Fields Object
This is a custom object of key-value pairs that can be used to display custom fields in custom output PDF templates or in certain reports. For example:
Requirement of Critical Fields
Fields | Generate E-Invoice API (via JSON) | Generate E-Invoice via XML API |
---|---|---|
UUID | Optional. Will be generated by ClearTax if not sent in input. | Optional. Will be generated by ClearTax if not sent in input. |
ICV | Read Only. Will be ignored if sent in input. | Read Only. Will be ignored if sent in input. |
PIH | Read Only. Will be ignored if sent in input. | Read Only. Will be ignored if sent in input. |
InvoiceHash | Read Only. Will be ignored if sent in input. | Read Only. Will be ignored if sent in input. |
Signature | Read Only. Will be ignored if sent in input. | Read Only. Will be ignored if sent in input. |
RawQRCode | Read Only. Will be ignored if sent in input. | Read Only. Will be ignored if sent in input. |
InvoiceXml | NA. Not available in the input schema. | NA. Not available in the input schema. The XML received will be enhanced before sending to ZATCA. The use case where generation CSID (at customer side) and reporting CSID (at ClearTax side) is different, is not supported at the moment. |
Sample Request
Additional E-Invoice examples:
Standard (B2B)
Additional Standard (B2B) E-Invoice ExamplesSimplified (B2C)
Additional Simplified (B2C) E-Invoice ExamplesResponse Status Codes
HTTP Status Code | Description |
---|---|
200 | For a successfully reported or cleared document. |
400 | For any kind of validation issues either from ClearTax or ZATCA. |
401 | If the user is not authenticated for the operation. |
403 | If the user is not authorized for the operation. |
Response Schema
Parameter | Data Type | Field Validations | Description |
---|---|---|---|
DeviceId | String | MaxLength: 36 | Optional. Device ID registered in ClearTax. |
Status | String | Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED | Mandatory. Status of E-Invoice QR Code Generation and acceptance by ZATCA. Explained below. |
QrCodeStatus | String | Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED | Mandatory. Status of E-Invoice QR Code. GENERATED, NOT_GENERATED, GENERATION_FAILED |
InvoiceStatus | String | Enum NOT_SUBMITTED, FAILED. NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED. ACCEPTED_WITH_WARNING, PENDING | Mandatory. Status of submission to ZATCA. NOT_SUBMITTED, FAILED NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED ACCEPTED_WITH_WARNING, PENDING |
QRCode | String | NA | Optional. Rendered QR Code image in base64encoded PNG format. If clearance fails, this will be null. |
RawQRCode | String | NA | Optional. QR Code payload in base64encoded TLV format. For reporting, this will be generated by ClearTax, if not received in the input. For clearance, this will be generated by ZATCA. If clearance fails, this will be null. |
InvoiceXml | String | NA | Optional. In case of Standard invoices, XML returned by ZATCA. In case of Simplified invoices, XML used for reporting. |
UUID | String | NA | Optional. UUID sent to ZATCA ClearTax generates this before sending to ZATCA, if not sent in input. |
ICV | String | NA | Optional. Invoice counter value sent to ZATCA ClearTax generates this before sending to ZATCA. |
PIH | String | NA | Optional. Previous hash value, Invoice hash value of previous invoice reported/cleared for same deviceId |
InvoiceHash | String | NA | Optional. Invoice hash value, Hash value of current invoice xml by removing tags ext:UBLExtensions, cac:AdditionalDocumentReference:QRCode |
InvoiceType | String | Enum: INV, CRN, DBN, RECEIPT | Mandatory. Document Type. INV - Invoice, CRN - Credit Note, DBN - Debit Note, RECEIPT - Receipt. |
InvoiceNumber | String | Cannot be null. | Mandatory. Invoice number (ID) as per the input. |
IssueDate | String | Cannot be null. | Mandatory. Issue Date as per the input. |
IssueTime | String | Format: HH:mm:ss (24 hr format) | Mandatory. Invoice issue time. The time when the invoice was issued. |
GeneratedDate | String | Cannot be null. | Mandatory. Date on which the invoice was generated. |
GeneratedTime | String | Format: HH:mm:ss (24 hr format) | Mandatory. Invoice generation time. The time when the invoice was generated. |
SellerVatNumber | String | Cannot be null. | Mandatory. Seller VAT identification number. |
BuyerVatNumber | String | Cannot be null. | Optional. Buyer VAT identification number. |
ErrorList | Array | NA | Optional. Validation Errors. An array of Error Details Objects. In case there are no errors, this will be an empty Array ([]). |
WarningList | Array | NA | Optional. Warnings from ZATCA. An array of Error Details Objects. In case there are no warnings, this will be an empty Array ([]). |
Message | String | NA | Optional. Message received from ZATCA. |
Explanation of QrCodeStatus
ClearTax generated ICV, IH, PIH, etc | Transmission from ClearTax to ZATCA | ZATCA accepted (cleared or reported) | QrCodeStatus for Standard | QrCodeStatus for Simplified |
---|---|---|---|---|
SUCCESS | SUCCESS | SUCCESS | GENERATED | GENERATED |
SUCCESS | SUCCESS | FAILED | GENERATION_FAILED | GENERATED |
SUCCESS | FAILED | NA | GENERATION_FAILED | GENERATED |
FAILED | NA | NA | GENERATION_FAILED | GENERATION_FAILED |
NA | NA | NA | NOT_GENERATED | NOT_GENERATED |
If QrCodeStatus
is GENERATED, then the invoice can be issued.
Explanation of InvoiceStatus
ClearTax generated ICV, IH, PIH, etc | Transmission with ZATCA | ZATCA accepted (cleared or reported) | InvoiceStatus for Standard | InvoiceStatus for Simplified |
---|---|---|---|---|
SUCCESS | SUCCESS | SUCCESS | CLEARED | REPORTED / ACCEPTED_WITH_WARNING |
SUCCESS | SUCCESS | FAILED | NOT_CLEARED | NOT_REPORTED |
SUCCESS | FAILED | NA | PENDING | PENDING |
FAILED | NA | NA | FAILED | FAILED |
NA | NA | NA | NOT_SUBMITTED | NOT_SUBMITTED |
If InvoiceStatus
is CLEARED or REPORTED or ACCEPTEDWITHWARNING, then no further action is required. NOT_SUBMITTED may be returned only in the case of Excel upload on the Web UI. Else, an invoice with valid data needs to be sent to ClearTax.
Sample Response
Success for Simplified Document - HTTP Status Code - 200
Success for Standard Document - HTTP Status Code - 200