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
Replace the {{BASE_URL}} with the one mentioned based on whether you are using sandbox or production.
Rate Limit : 1000 API requests per minute
Request Headers
Parameter
Data Type
Field Validations
Description
x-cleartax-auth-token
String
Cannot be empty.
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
EInvoice
Object
NA
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:
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
WarningList
Array
NA
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
SUCCESS
FAILED
FAILED
FAILED
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
{
"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
}
Error from ClearTax - HTTP Status Code - 400
{
"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"
}
],
}
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).
Note: In case a document is validated by ClearTax but failed at ZATCA, then the HTTP Status Code will be 200 and not 400.
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".
{
"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
}
Error from ZATCA - If we are getting 401 from Zatca, so in that case the Invoice status will be FAILED.
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.
API Constraints
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.
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.
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.
Mandatory. .
Mandatory. The Device ID registered with ClearTax. Refer to ?
Mandatory.
Optional. Validation Errors. An array of . In case there are no errors, this will be an empty Array ([]).
Optional. Warnings from ZATCA. An array of . In case there are no warnings, this will be an empty Array ([]).