Generate E-Invoice Async

Generate a valid E-Invoice with JSON payload synchronously and send it to ZATCA for reporting asynchronously.

This API can be used only for Simplified Tax Invoices and related notes (B2C).

Request Method

POST

Request URL

{{BASE_URL}}/v2/einvoices/generate/async

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

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 Validations	Description
DeviceId	String	MaxLength: 36	Mandatory. The Device ID registered with ClearTax.
EInvoice	Object	Not null	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:

{
    "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 generating CSID (at customer side) and reporting CSID (at ClearTax side) is different, is not supported at the moment.

Sample Request

{
  "DeviceId": "2caa0dd5-2f20-44d1-b1c8-6257f3f60634",
  "EInvoice": {
    "ProfileID": "reporting:1.0",
    "ID": {
      "en": "269",
      "ar": null
    },
    "InvoiceTypeCode": {
      "name": "0100000",
      "value": "388"
    },
    "IssueDate": "2021-04-25",
    "IssueTime": "15:30:00",
    "DocumentCurrencyCode": "SAR",
    "TaxCurrencyCode": "SAR",
    "Delivery": [
      {
        "ActualDeliveryDate": "2022-04-25"
      }
    ],
    "AccountingSupplierParty": {
      "Party": {
        "PartyLegalEntity": {
          "RegistrationName": {
            "en": "Al Salam Supplies Co. LTD",
            "ar": null
          }
        },
        "PartyTaxScheme": {
          "CompanyID": "300492946900003",
          "TaxScheme": {
            "ID": "VAT"
          }
        },
        "PartyIdentification": {
          "ID": {
            "schemeID": "SAG",
            "value": "123457890"
          }
        },
        "PostalAddress": {
          "StreetName": {
            "en": "King Abdulaziz Road",
            "ar": null
          },
          "BuildingNumber": {
            "en": "8228",
            "ar": null
          },
          "PlotIdentification": {
            "en": "2121",
            "ar": null
          },
          "CityName": {
            "en": "Riyadh",
            "ar": null
          },
          "PostalZone": 12643,
          "CitySubdivisionName": {
            "en": "Al Amal",
            "ar": null
          },
          "Country": {
            "IdentificationCode": "SA"
          },
          "CountrySubentity": {
            "en": "Riyadh Region",
            "ar": null
          }
        }
      }
    },
    "AccountingCustomerParty": {
      "Party": {
        "PartyLegalEntity": {
          "RegistrationName": {
            "en": "AL KAWTHAR MARKETS",
            "ar": null
          }
        },
        "PartyTaxScheme": {
          "CompanyID": null,
          "TaxScheme": {
            "ID": "VAT"
          }
        },
        "PartyIdentification": {
          "ID": {
            "schemeID": "SAG",
            "value": "123C12345678"
          }
        },
        "PostalAddress": {
          "StreetName": {
            "en": "King Abdullah Road",
            "ar": null
          },
          "BuildingNumber": {
            "en": "3709",
            "ar": null
          },
          "PlotIdentification": {
            "en": "1004",
            "ar": null
          },
          "CityName": {
            "en": "Riyadh",
            "ar": null
          },
          "PostalZone": 11564,
          "CitySubdivisionName": {
            "en": "Al Mursalat",
            "ar": null
          },
          "Country": {
            "IdentificationCode": "SA"
          },
          "CountrySubentity": {
            "en": "Riyadh Region",
            "ar": null
          }
        }
      }
    },
    "InvoiceLine": [
      {
        "ID": "1",
        "Item": {
          "Name": {
            "en": "Item A",
            "ar": null
          },
          "ClassifiedTaxCategory": {
            "ID": "S",
            "Percent": 15.00,
            "TaxScheme": {
              "ID": "VAT"
            }
          }
        },
        "Price": {
          "PriceAmount": {
            "currencyID": "SAR",
            "value": 200.00
          }
        },
        "InvoicedQuantity": {
          "value": 1.0
        },
        "LineExtensionAmount": {
          "currencyID": "SAR",
          "value": 200.00
        },
        "TaxTotal": {
          "TaxAmount": {
            "currencyID": "SAR",
            "value": 30.00
          },
          "RoundingAmount": {
            "currencyID": "SAR",
            "value": 230.00
          }
        }
      },
      {
        "ID": "2",
        "Item": {
          "Name": {
            "en": "Item B",
            "ar": null
          },
          "ClassifiedTaxCategory": {
            "ID": "S",
            "Percent": 15.00,
            "TaxScheme": {
              "ID": "VAT"
            }
          }
        },
        "Price": {
          "PriceAmount": {
            "currencyID": "SAR",
            "value": 350.00
          }
        },
        "InvoicedQuantity": {
          "value": 2.0
        },
        "LineExtensionAmount": {
          "currencyID": "SAR",
          "value": 700.00
        },
        "TaxTotal": {
          "TaxAmount": {
            "currencyID": "SAR",
            "value": 105.00
          },
          "RoundingAmount": {
            "currencyID": "SAR",
            "value": 805.00
          }
        }
      }
    ],
    "TaxTotal": [
      {
        "TaxAmount": {
          "currencyID": "SAR",
          "value": 135.00
        },
        "TaxSubtotal": [
          {
            "TaxableAmount": {
              "currencyID": "SAR",
              "value": 900.00
            },
            "TaxAmount": {
              "currencyID": "SAR",
              "value": 135.00
            },
            "TaxCategory": {
              "ID": "S",
              "Percent": 15.00,
              "TaxScheme": {
                "ID": "VAT"
              }
            }
          }
        ]
      }
    ],
    "LegalMonetaryTotal": {
      "LineExtensionAmount": {
        "currencyID": "SAR",
        "value": 900.00
      },
      "AllowanceTotalAmount": {
        "currencyID": "SAR",
        "value": 0.00
      },
      "TaxExclusiveAmount": {
        "currencyID": "SAR",
        "value": 900.00
      },
      "TaxInclusiveAmount": {
        "currencyID": "SAR",
        "value": 1035.00
      },
      "PayableAmount": {
        "currencyID": "SAR",
        "value": 1035.00
      }
    },
    "PaymentMeans": [
      {
        "PaymentMeansCode": "42"
      }
    ]
  },
  "CustomFields": {
    "country_of_origin": "IN",
    "total_containers": "3"
  }
}

Response Status Codes

HTTP Status Code	Description
202	For successfully acceptance from CT
400	For any cleartax validation error
400	Validation error from 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 used to generate invoices.
Status	String	Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED, IN_PROGRESS	Mandatory. Status of E-Invoice QR Code. This is the same as QrCodeStatus below. Provided only for backward compatibility for Phase I API. IN_PROGRESS, NOT_GENERATED, GENERATION_FAILED
QrCodeStatus	String	Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED	Mandatory. Status of E-Invoice QR Code. GENERATED, NOT_GENERATED, GENERATION_FAILED
InvoiceStatus	String	Enum: PENDING, FAILED.	Mandatory. Status of submission to ZATCA.
QRCode	String		Optional. Rendered QR Code image in base64 encoded PNG format. If validations fail, this will be null.
RawQRCode	String		Optional. QR Code payload in base64 encoded TLV format.
InvoiceXml	String		Optional. It is the XML used for reporting.
UUID	String		Optional. UUID sent to ZATCA ClearTax generates this before sending to ZATCA, if not sent in input.
ICV	String		Optional. Invoice counter value sent to ZATCA ClearTax generates this before sending it to ZATCA.
PIH	String		Optional. Previous hash value, Invoice hash value of previous invoice reported for same deviceId.
InvoiceHash	String		Optional. Current invoice hash. Hash value of current invoice xml by removing tags ext:UBLExtensions, cac:AdditionalDocumentReference:QRCode
InvoiceType	String	Enum: INV, CRN, DBN	Mandatory. Document Type: INV-INVOICE, CRN-CREDIT NOTE, DBN-DEBIT NOTE.
InvoiceNumber	String	Can not be null	Mandatory. Invoice number (ID) as per the input.
IssueDate	String	Can not 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 is generated
GeneratedTime	String	Format: HH:mm:ss (24 hr format)	Mandatory. Invoice generation time. The time when the invoice is generated.
SellerVatNumber	String	Can not be null	Mandatory. Seller VAT identification number.
BuyerVatNumber	String	Can not be null	Optional. Buyer VAT identification number.
ErrorList	Array<Error Detail>	Can be empty	Optional. Validation errors.

Error Details Object

Parameter	Data Type	Field Validations	Description
ErrorCode	String	Cannot be null	A code to identify the error. Error codes are published above.
ErrorMessage	String	Cannot be null	Human readable error message.
ErrorSource	String	CLEARTAX	Source of the error.
Path	String	-	If it is a validation error of a request data, it will point to the request data field. Example below.

Sample Response

Success for Simplified Document - HTTP Status Code - 200

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "PENDING",
    "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
}

Error from ClearTax - HTTP Status Code - 400

{
    "InvoiceType": "INV",
    "InvoiceNumber": "2022",
    "IssueDate": "2021-04-25",
    "IssueTime": "12:24:26",
    "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.

{
    "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
}

API Validations

API validations will remain the same as in Phase I. In addition, the following new validations are added for Phase II.

1. Other Seller ID is Mandatory.

2. Other Buyer ID is Mandatory.

3. Payment type code is Mandatory.

4. The document issue date must be less than or equal to the current date.

5. Buyer name is mandatory for Simplified Tax Invoice and associated credit/debit notes.

6. DEC-20=[BR-DEC-20] - The allowed maximum number of decimals for the VAT category tax amount (BT-117) is 2.

7. BR-DEC-13=[BR-DEC-13] - The allowed maximum number of decimals for the Invoice total VAT amount (BT-110) is 2.

8. BR-DEC-15=[BR-DEC-15] - The allowed maximum number of decimals for the Invoice total VAT amount in accounting currency (BT-111) is 2.

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. If the auth token is valid, but the user does not have the authorization to generate einvoice , then the API will return HTTP Status Code 403.

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. Async API is for simplified tax invoices only as for standard tax invoices ZATCA generates the QR code and signs it realtime. Error message in case standard tax invoices are sent via this API - "Async API call is only supported for Reporting simplified tax invoices. For standard invoices use the Generate e-Invoice API."