# 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
```
{{BASE_URL}}/v2/einvoices/generate
```
{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference.md) based on whether you are using sandbox or production.
{% endhint %}
{% hint style="danger" %}
Rate Limit : 1000 API requests per minute
{% endhint %}
### Request Headers
| Parameter | Data Type | Field Validations | Description |
| --------------------- | --------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| x-cleartax-auth-token | String | Cannot be empty. | Mandatory. [User auth token](/cleartax-docs/e-invoicing-ksa-api/learn-e-invoicing-ksa-api-basics/how-to-get-e-invoicing-ksa-auth-token.md). |
| 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:
```json
{
"country_of_origin": "IN",
"total_containers": "3"
}
```
#### 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
{% code lineNumbers="true" %}
```json
{
"DeviceId": "{{DeviceId}}",
"EInvoice": {
"ProfileID": "reporting:1.0",
"ID": {
"en": "Test179",
"ar": "Test179"
},
"InvoiceTypeCode": {
"name": "0100000",
"value": "388"
},
"IssueDate": "2023-10-27",
"IssueTime": "12:15:48",
"Delivery": [
{
"ActualDeliveryDate": "2023-10-27",
"LatestDeliveryDate": "2023-10-27"
}
],
"BillingReference": [
{
"InvoiceDocumentReference": {
"ID": {
"ar": null,
"en": "156166151"
}
}
}
],
"OrderReference": {
"ID": {
"ar": null,
"en": "161313031"
}
},
"ContractDocumentReference": [
{
"ID": {
"ar": null,
"en": "1771313066"
}
}
],
"DocumentCurrencyCode": "USD",
"TaxCurrencyCode": "SAR",
"AccountingSupplierParty": {
"Party": {
"PartyLegalEntity": {
"RegistrationName": {
"en": "ClearTax LCC",
"ar": "كليرتاكس ذ.م.م"
}
},
"PartyTaxScheme": {
"CompanyID": "{{vat}}",
"TaxScheme": {
"ID": "VAT"
}
},
"PartyIdentification": {
"ID": {
"schemeID": "CRN",
"value": "1010182239"
}
},
"PostalAddress": {
"StreetName": {
"en": "AlAlmin Street",
"ar": "شارع العلمين"
},
"AdditionalStreetName": {
"en": null,
"ar": null
},
"BuildingNumber": {
"en": "6623",
"ar": "6623"
},
"PlotIdentification": {
"en": "2892",
"ar": "2892"
},
"CityName": {
"en": "Riyadh",
"ar": "الرياض"
},
"CitySubdivisionName": {
"en": "Al Shohda Dist.",
"ar": "حي الشهداء"
},
"PostalZone": "13241",
"CountrySubentity": {
"en": "Riyadh Region",
"ar": "منطقة الرياض"
},
"Country": {
"IdentificationCode": "SA"
}
}
}
},
"AccountingCustomerParty": {
"Party": {
"PartyLegalEntity": {
"RegistrationName": {
"en": "ALMARAI COMPANY",
"ar": " شركة المراعي"
}
},
"PartyTaxScheme": {
"CompanyID": "{{buyervat}}",
"TaxScheme": {
"ID": "VAT"
}
},
"PartyIdentification": null,
"PostalAddress": {
"StreetName": {
"en": "STREET NAME EN:Riyadh1",
"ar": "أسم الش"
},
"AdditionalStreetName": null,
"BuildingNumber": {
"en": "1212",
"ar": "1212"
},
"PlotIdentification": {
"en": "1210",
"ar": "1210"
},
"CityName": {
"en": "CITY NAME EN",
"ar": "أسم المدينة"
},
"CitySubdivisionName": {
"en": "CITY S.DIVISION EN ",
"ar": "المدينة - قطاع "
},
"PostalZone": "12345",
"CountrySubentity": {
"en": "COUNTRY EN",
"ar": "COUNTRY EN"
},
"Country": {
"IdentificationCode": "SA"
}
}
}
},
"InvoiceLine": [
{
"ID": "1",
"Item": {
"Name": {
"en": "Item A",
"ar": "البند أ"
},
"BuyersItemIdentification": {
"ID": {
"en": "PRD789",
"ar": null
}
},
"SellersItemIdentification": {
"ID": {
"en": "ITM123",
"ar": null
}
},
"StandardItemIdentification": {
"ID": {
"en": "9067845",
"ar": null
}
},
"ClassifiedTaxCategory": {
"ID": "S",
"Percent": "15.00",
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"AllowanceCharge": {
"ChargeIndicator": "false",
"BaseAmount": {
"currencyID": "USD",
"value": "55.00"
},
"Amount": {
"currencyID": "USD",
"value": "5"
}
},
"PriceAmount": {
"currencyID": "USD",
"value": "50.00"
},
"BaseQuantity": {
"unitCode": "HMO",
"value": "1"
}
},
"InvoicedQuantity": {
"unitCode": "HMO",
"value": "10"
},
"AllowanceCharge": [
{
"ChargeIndicator": "false",
"BaseAmount": {
"currencyID": "USD",
"value": "500"
},
"MultiplierFactorNumeric": "20",
"Amount": {
"currencyID": "USD",
"value": "100"
},
"AllowanceChargeReason": {
"ar": "خصم",
"en": "Discount"
},
"AllowanceChargeReasonCode": null
}
],
"LineExtensionAmount": {
"currencyID": "USD",
"value": "400.00"
},
"TaxTotal": {
"TaxAmount": {
"currencyID": "USD",
"value": "60.00"
},
"RoundingAmount": {
"currencyID": "USD",
"value": "460.00"
}
}
},
{
"ID": "2",
"Item": {
"Name": {
"en": "Item B",
"ar": "البند ب"
},
"ClassifiedTaxCategory": {
"ID": "S",
"Percent": "15.00",
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"PriceAmount": {
"currencyID": "USD",
"value": "300.00"
}
},
"InvoicedQuantity": {
"value": "2"
},
"LineExtensionAmount": {
"currencyID": "USD",
"value": "600.00"
},
"TaxTotal": {
"TaxAmount": {
"currencyID": "USD",
"value": "90.00"
},
"RoundingAmount": {
"currencyID": "USD",
"value": "690.00"
}
}
},
{
"ID": "3",
"Item": {
"Name": {
"en": "Item C",
"ar": "البند ج"
},
"ClassifiedTaxCategory": {
"ID": "Z",
"Percent": "0.00",
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"PriceAmount": {
"currencyID": "USD",
"value": "50.00"
}
},
"InvoicedQuantity": {
"value": "2"
},
"LineExtensionAmount": {
"currencyID": "USD",
"value": "100.00"
},
"TaxTotal": {
"TaxAmount": {
"currencyID": "USD",
"value": "0.00"
},
"RoundingAmount": {
"currencyID": "USD",
"value": "100.00"
}
}
},
{
"ID": "4",
"Item": {
"Name": {
"en": "Prepayment adjustment",
"ar": "تعديل الدفع المسبق"
},
"ClassifiedTaxCategory": {
"ID": "S",
"Percent": "15.00",
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"PriceAmount": {
"currencyID": "USD",
"value": "0.00"
}
},
"DocumentReference": {
"ID": "Advance-test100",
"UUID": "5a8a6b8c-2712-4032-9c3a-5e1bc7243e7d",
"IssueDate": "2023-08-01",
"IssueTime": "12:15:48",
"InvoiceTypeCode": "386"
},
"InvoicedQuantity": {
"unitCode": "EA",
"value": "0.00"
},
"LineExtensionAmount": {
"currencyID": "USD",
"value": "0.00"
},
"TaxTotal": {
"TaxAmount": {
"value": "0.00",
"currencyID": "USD"
},
"RoundingAmount": {
"currencyID": "USD",
"value": "0.00"
},
"TaxSubtotal": [
{
"TaxableAmount": {
"value": "86.96",
"currencyID": "USD"
},
"TaxAmount": {
"value": "13.04",
"currencyID": "USD"
},
"TaxCategory": {
"ID": "S",
"Percent": "15.00",
"TaxScheme": {
"ID": "VAT"
},
"TaxExemptionReasonCode": "",
"TaxExemptionReason": {
"ar": "",
"en": ""
}
}
}
]
}
}
],
"AllowanceCharge": [
{
"ChargeIndicator": "false",
"BaseAmount": {
"currencyID": "USD",
"value": "1000"
},
"MultiplierFactorNumeric": "10",
"Amount": {
"currencyID": "USD",
"value": "100"
},
"TaxCategory": {
"ID": "S",
"Percent": "15",
"TaxScheme": {
"ID": "VAT"
}
}
}
],
"TaxTotal": [
{
"TaxAmount": {
"currencyID": "SAR",
"value": "25.01"
}
},
{
"TaxAmount": {
"currencyID": "USD",
"value": "135.00"
},
"TaxSubtotal": [
{
"TaxableAmount": {
"currencyID": "USD",
"value": "900.00"
},
"TaxAmount": {
"currencyID": "USD",
"value": "135.00"
},
"TaxCategory": {
"ID": "S",
"Percent": "15.00",
"TaxScheme": {
"ID": "VAT"
}
}
},
{
"TaxableAmount": {
"currencyID": "USD",
"value": "100.00"
},
"TaxAmount": {
"currencyID": "USD",
"value": "0"
},
"TaxCategory": {
"ID": "Z",
"Percent": "0.00",
"TaxScheme": {
"ID": "VAT"
},
"TaxExemptionReasonCode": "VATEX-SA-34-4",
"TaxExemptionReason": {
"en": "Supply of a qualifying means of transport.",
"ar": null
}
}
}
]
}
],
"LegalMonetaryTotal": {
"LineExtensionAmount": {
"currencyID": "USD",
"value": "1100"
},
"AllowanceTotalAmount": {
"currencyID": "USD",
"value": "100"
},
"TaxExclusiveAmount": {
"currencyID": "USD",
"value": "1000.00"
},
"TaxInclusiveAmount": {
"currencyID": "USD",
"value": "1135.00"
},
"PrepaidAmount": {
"currencyID": "USD",
"value": "100.00"
},
"PaybleRoundingAmount": {
"currencyID": "USD",
"value": "0"
},
"PayableAmount": {
"currencyID": "USD",
"value": "1035.00"
}
},
"PaymentMeans": [
{
"PaymentMeansCode": 10,
"InstructionNote": {
"en": "",
"ar": ""
},
"PayeeFinancialAccount": {
"PaymentNote": {
"en": "",
"ar": ""
}
}
}
],
"Note": {
"en": "This is a computer generated invoice.",
"ar": null
}
}
}
```
{% endcode %}
#### Additional E-Invoice examples:
Standard (B2B)
{% content-ref url="/pages/kptmCHGojEwbdnMSz4TS" %}
[Additional Standard (B2B) E-Invoice Examples](/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice/additional-standard-b2b-e-invoice-examples.md)
{% endcontent-ref %}
Simplified (B2C)
{% content-ref url="/pages/CsKuoAbyFs2gdrpnDqtT" %}
[Additional Simplified (B2C) E-Invoice Examples](/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice/additional-simplified-b2c-e-invoice-examples.md)
{% endcontent-ref %}
### Response 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. |
| 429 | Too many requests |
### 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](/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/resources-and-masters/error-details-object.md). 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](/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/resources-and-masters/error-details-object.md). 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 |
{% hint style="info" %}
If `QrCodeStatus` is GENERATED, then the invoice can be issued.
{% endhint %}
#### 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 | SUCCESS | FAILED | FAILED | FAILED |
| SUCCESS | FAILED | NA | PENDING | PENDING |
| FAILED | NA | NA | FAILED | FAILED |
| NA | NA | NA | NOT\_SUBMITTED | NOT\_SUBMITTED |
{% hint style="info" %}
If `InvoiceStatus` is CLEARED or REPORTED or ACCEPTED*WITHWARNING, 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.
{% endhint %}
### Sample Response
Success for Simplified Document - HTTP Status Code - 200
{% code lineNumbers="true" %}
```json
{
"DeviceId": "625410e387173015f7e5a4c6",
"Status": "GENERATED",
"QrCodeStatus": "GENERATED",
"InvoiceStatus": "REPORTED",
"QRCode": "MjAsSIy1….",
"RawQRCode": "ARlBb….",
"InvoiceXml": "ASsdfkf...",
"UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
"ICV": "61",
"PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
"InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
"InvoiceType": "INV",
"InvoiceNumber": "315",
"IssueDate": "2021-04-25",
"IssueTime": "16:42:25",
"GeneratedDate": "2021-04-25",
"GeneratedTime": "16:42:25",
"SellerVatNumber": "300492946900003",
"BuyerVatNumber": null,
"ErrorList": [],
"WarningList":[],
"Message": null
}
```
{% endcode %}
Success for Standard Document - HTTP Status Code - 200
{% code lineNumbers="true" %}
```json
{
"DeviceId": "625410e387173015f7e5a4c6",
"Status": "GENERATED",
"QrCodeStatus": "GENERATED",
"InvoiceStatus": "CLEARED",
"QRCode": "iBU5ul8ZaHcbmWYy3zL.....",
"RawQRCode": "ARlBbCBTYWxhbSBTdXB.......",
"InvoiceXml": "PD94PC....",
"UUID": "ed7d6a63-e650-425d-b1eb-f54187a0ccca",
"ICV": "62",
"PIH": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
"InvoiceHash": "u+zU7f/JDKpjoKrNUMF5Z3Kho3cqb1VUoNSCIphyZu8=",
"InvoiceType": "INV",
"InvoiceNumber": "130",
"IssueDate": "2021-04-25",
"IssueTime": "16:42:25",
"GeneratedDate": "2021-04-25",
"GeneratedTime": "16:42:25",
"SellerVatNumber": "300492946900003",
"BuyerVatNumber": null,
"ErrorList":[],
"WarningList": [],
"Message": null
}
```
{% endcode %}
Success with Warning - HTTP Status Code - 200
{% code lineNumbers="true" %}
```json
{
"DeviceId": "625410e387173015f7e5a4c6",
"Status": "GENERATED",
"QrCodeStatus": "GENERATED",
"InvoiceStatus": "ACCEPTED_WITH_WARNING",
"QRCode": "i+GdAUnzMJS.....",
"RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
"InvoiceXml": "ASsdfkf...",
"UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
"ICV": "61",
"PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
"InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
"InvoiceType": "INV",
"InvoiceNumber": "315",
"IssueDate": "2021-04-25",
"IssueTime": "16:42:25",
"GeneratedDate": "2021-04-25",
"GeneratedTime": "16:42:25",
"SellerVatNumber": "300492946900003",
"BuyerVatNumber": null,
"ErrorList": [],
"WarningList": [
{
"ErrorCode": "BR-KSA-09",
"ErrorMessage": "Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n For more information please access this link: https://www.address.gov.sa/en/address-format/overview",
"ErrorSource": "ZATCA"
}
],
"Message": null
}
```
{% endcode %}
Error from ClearTax - HTTP Status Code - 400
{% code lineNumbers="true" %}
```json
{
"InvoiceType": "INV",
"InvoiceNumber": "2022",
"IssueDate": "2021-04-25",
"IssueTime": "16:42:25",
"SellerVatNumber": "300492946900003",
"Status": "GENERATION_FAILED",
"QrCodeStatus": "GENERATION_FAILED",
"InvoiceStatus": "FAILED",
"ErrorList": [
{
"ErrorCode": "6002",
"ErrorMessage": "If Supplier Group Vat number is provided, scheme id must be HQ",
"ErrorSource": "CLEARTAX",
"Path": "EInvoice.AccountingSupplierParty.Party.PartyIdentification.ID.schemeID"
},
{
"ErrorCode": "6002",
"ErrorMessage": "Payment means code in an invoice must contain one of the values (10, 30, 42, 48, 1). In the simplified tax invoice and associated credit notes and debit notes this value is optional.",
"ErrorSource": "CLEARTAX",
"Path": "EInvoice.PaymentMeans.PaymentMeansCode"
}
],
}
```
{% endcode %}
Error from ZATCA - HTTP Status Code - 200 (Sample Simplified invoice where QR code is generated by ClearTax and then sent to ZATCA for reporting which is not approved by ZATCA).
{% hint style="info" %}
Note: In case a document is validated by ClearTax but failed at ZATCA, then the HTTP Status Code will be 200 and not 400.
{% endhint %}
{% code lineNumbers="true" %}
```json
{
"DeviceId": "625410e387173015f7e5a4c6",
"Status": "GENERATED",
"QrCodeStatus": "GENERATED",
"InvoiceStatus": "NOT_REPORTED",
"QRCode": "i+GdAUnzMJS.....",
"RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
"InvoiceXml": null,
"UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
"ICV": "61",
"PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
"InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
"InvoiceType": "INV",
"InvoiceNumber": "315",
"IssueDate": "2021-04-25",
"IssueTime": "16:42:25",
"SellerVatNumber": "300492946900003",
"BuyerVatNumber": null,
"ErrorList": [
{
"ErrorCode": "Invalid-Invoice-Hash",
"ErrorMessage": "The provided invoice hash is invalid",
"ErrorSource": "ZATCA"
}
],
"WarningList": [],
"Message": null
}
```
{% endcode %}
Error from ZATCA - Sample Standard invoice with multiple errors which is not approved by Zatca and hence the InvoiceStatus will be "NOT\_CLEARED" and QrCodeStatus will be "NOT\_GENERATED".
{% code lineNumbers="true" %}
```json
{
"DeviceId": "09569f97-dd87-4b50-b226-a644b0cb0ab8",
"Status": "NOT_GENERATED",
"QrCodeStatus": "NOT_GENERATED",
"InvoiceStatus": "NOT_CLEARED",
"QRCode": null,
"RawQRCode": null,
"InvoiceXml": null,
"UUID": "e6791446-844d-4fd1-b4d3-1ae2d111abf8",
"ICV": "36",
"PIH": "a+ae0fY+MBboXiFPkZicCIF8ceL2sEnU/fBeQpWEPP4=",
"InvoiceHash": "+EYiXktJtVeAEqitiJBxNGlO9Hm29/r8l21Z8LGTbCQ=",
"InvoiceType": "INV",
"InvoiceNumber": "S-INV-0004",
"IssueDate": "2021-04-25",
"IssueTime": "16:42:25",
"SellerVatNumber": "300492946900003",
"BuyerVatNumber": "300526201800003",
"ErrorList": [
{
"ErrorCode": "BR-CO-15",
"ErrorMessage": "Invoice total amount with VAT (BT-112) ",
"ErrorSource": "ZATCA"
},
{
"ErrorCode": "BR-DEC-20",
"ErrorMessage": "The allowed maximum number of decimals for the VAT category tax amount (BT-117) is 2.",
"ErrorSource": "ZATCA"
},
{
"ErrorCode": "BR-DEC-13",
"ErrorMessage": "The allowed maximum number of decimals for the Invoice total VAT amount (BT-110) is 2.-BR-DEC-15",
"ErrorSource": "ZATCA"
},
{
"ErrorCode": "BR-DEC-14",
"ErrorMessage": "The allowed maximum number of decimals for the Invoice total amount with VAT (BT-112) is 2.",
"ErrorSource": "ZATCA"
},
{
"ErrorCode": "BR-CO-14",
"ErrorMessage": "Invoice total VAT amount (BT-110) ",
"ErrorSource": "ZATCA"
},
{
"ErrorCode": "BR-DEC-18",
"ErrorMessage": "The allowed maximum number of decimals for the Amount due for payment (BT-115) is 2.",
"ErrorSource": "ZATCA"
}
],
"WarningList": [],
"Message": null
}
```
{% endcode %}
Error from ZATCA - If we are getting 401 from Zatca, so in that case the Invoice status will be FAILED.
```json
{
"QRCode": null,
"RawQRCode": null,
"UUID": "308a9c99-d727-487e-a327-1d8d84123c09",
"PIH": "ihAo9IepEZ4Ek4mOR4Kh9ou/hGKuqcBgekj+IdXovm4=",
"InvoiceHash": "wQ1bduk6PCUiKStxqyrxQHHGs8a9SFVYb3rfaeM7Oxo=",
"ICV": "31574",
"DeviceId": "36175d8a-240d-4282-9da3-cfbc1a7a8fa0",
"SellerVatNumber": "311555804900003",
"BuyerVatNumber": "300008123400003",
"Status": "NOT_GENERATED",
"QrCodeStatus": "NOT_GENERATED",
"InvoiceStatus": "FAILED",
"InvoiceType": "INV",
"InvoiceNumber": "Jitna-02",
"IssueDate": "2025-03-25",
"IssueTime": "12:15:48",
"GeneratedDate": null,
"GeneratedTime": null,
"InvoiceXml": null,
"WarningList": null,
"ErrorList": [
{
"ErrorCode": "401",
"ErrorMessage": "User is not authorized",
"ErrorSource": "ZATCA"
}
],
"Message": null,
"ValidationsSuccess": true,
"UniqueId": "311555804900003_Jitna-02_388_2025",
"UniqueReqIdentifier": null,
"Id": "67ebc64f40a9a738f9cd5491",
"TimeDifference": 0,
"ReportingTime": null,
"Vat": "311555804900003"
}
```
### API Validations
{% hint style="warning" %}
**New validation rules coming soon!**
There are a few changes proposed by ZATCA in the revised E-Invoicing Regulation and related guidelines which are currently under public consultation. Once the same is finalized and notified, the validation rules may change.
{% endhint %}
### API Constraints
1. This API needs to be authenticated with a valid user authentication token. If the auth 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 auth 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 auth token is used, should have an Admin role for the particular VAT used in the request.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.