Generate E-Invoice (Phase I)
A new version is available!
This API is valid only for Phase I requirements of ZATCA. In case you are implementing for Phase II, use the latest Generate E-Invoice API built for Phase II.
You can generate the E-Invoice by sending a POST request to E-Invoicing KSA API.
Request Headers
x-cleartax-auth-token: {{USER_AUTH_TOKEN}}
Content-Type: application/json
owner_id: {{OWNER_ID}}
vat: {{VAT}}| Parameter | Data Type | Field Validations | Description |
|---|---|---|---|
X-Cleartax-Auth-Token | String | Cannot be empty. | Mandatory. The auth token generated from ClearTax user id and password. |
Content-Type | String | Cannot be empty. | Mandatory. This will always be "application/json". |
vat | String | Cannot be empty. | TIN (VAT Number) for which you are generating the E-Invoice. |
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. |
Request URL
POST: https://api-demo.cleartax.com/middle-east/ksa/einvoicing/v2/einvoices/generateRequest Parameters
| Param Name | Type | Validation | Description |
|---|---|---|---|
EInvoice | Object | Mandatory. E-Invoice object | |
CustomFields | Object | Custom Fields object |
Sample URL
POST: https://api.cleartax.com/v2/einvoices/generateSample Request
{
"EInvoice": {
"UBLVersionID": "2.1",
"ProfileID": "reporting:1.0",
"ID": {
"en": "K01082K5",
"ar": "K01082K5"
},
"InvoiceTypeCode": {
"name": "0101000",
"value": "388"
},
"IssueDate": "2021-08-14",
"IssueTime": "15:44:20",
"Delivery": [
{
"ActualDeliveryDate": "2021-08-14",
"LatestDeliveryDate": "2021-08-14"
}
],
"BillingReference": [
{
"InvoiceDocumentReference": {
"ID": {
"ar": "string",
"en": "156166151"
}
}
}
],
"OrderReference": {
"ID": {
"ar": "string",
"en": "161313031"
}
},
"ContractDocumentReference": [
{
"ID": {
"ar": "string",
"en": "161313031"
}
}
],
"DocumentCurrencyCode": "SAR",
"TaxCurrencyCode": "SAR",
"AccountingSupplierParty": {
"Party": {
"PartyLegalEntity": {
"RegistrationName": {
"en": "Gulf Arabian Equipment Co",
"ar": "شركة الخليج العربية للمعدات"
}
},
"PartyTaxScheme": {
"CompanyID": "310387374800003",
"TaxScheme": {
"ID": "VAT"
}
},
"PartyIdentification": {
"ID": {
"value": "312345678914443",
"schemeID": "CRN"
}
},
"PostalAddress": {
"StreetName": {
"en": "Abdelrahman Road",
"ar": "طريق عبد الرحمن"
},
"AdditionalStreetName": {
"en": "",
"ar": ""
},
"BuildingNumber": {
"en": "2021",
"ar": "2021"
},
"PlotIdentification": {
"en": "2347",
"ar": "2347"
},
"CitySubDivisionName": {
"en": "Abqaiq",
"ar": "بقيق"
},
"CityName": {
"en": "Al-Baḥah",
"ar": "الباءة"
},
"PostalZone": "33502",
"CountrySubentity": {
"en": "Al-Jawf",
"ar": "الجوف"
},
"Country": {
"IdentificationCode": "SA"
}
}
}
},
"AccountingCustomerParty": {
"Party": {
"PartyLegalEntity": {
"RegistrationName": {
"en": "AL Amal Specialized Hospital",
"ar": "مستشفى الامل التخصصى"
}
},
"PartyTaxScheme": {
"CompanyID": "300761193700003",
"TaxScheme": {
"ID": "VAT"
}
},
"PartyIdentification": {
"ID": {
"value": "300761193710003",
"schemeID": "NAT"
}
},
"PostalAddress": {
"StreetName": {
"en": "Abdelrahman Road",
"ar": "طريق عبد الرحمن"
},
"AdditionalStreetName": {
"en": "",
"ar": ""
},
"BuildingNumber": {
"en": "2119",
"ar": "2119"
},
"PlotIdentification": {
"en": "2345",
"ar": "2345"
},
"CitySubDivisionName": {
"en": "Abqaiq",
"ar": "بقيق"
},
"CityName": {
"en": "Khobhar",
"ar": "الخبر"
},
"PostalZone": "31952",
"CountrySubentity": {
"en": "Riyadh",
"ar": "الرياض"
},
"Country": {
"IdentificationCode": "SA"
}
}
}
},
"InvoiceLine": [
{
"ID": "1",
"Item": {
"Name": {
"en": "Cable",
"ar": "كابل"
},
"ClassifiedTaxCategory": {
"ID": "S",
"Percent": "15",
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"PriceAmount": {
"currencyID": "SAR",
"value": "9000"
},
"BaseQuantity": {
"unitCode": "MTR",
"value": "10"
},
"AllowanceCharge":
{
"ChargeIndicator": "false",
"BaseAmount": {
"currencyID": "SAR",
"value": "10000"
},
"Amount": {
"currencyID": "SAR",
"value": "1000"
}
}
},
"InvoicedQuantity": {
"unitCode": "MTR",
"value": "10"
},
"AllowanceCharge": [
{
"ChargeIndicator": "false",
"BaseAmount": {
"currencyID": "SAR",
"value": "9000"
},
"MultiplierFactorNumeric": "10",
"Amount": {
"currencyID": "SAR",
"value": "900"
},
"AllowanceChargeReason": {
"ar": "خصم",
"en": "Discount"
},
"AllowanceChargeReasonCode":null
}
],
"LineExtensionAmount": {
"currencyID": "SAR",
"value": "8100"
},
"TaxTotal": {
"TaxAmount": {
"currencyID": "SAR",
"value": "1215"
},
"RoundingAmount": {
"currencyID": "SAR",
"value": "9315"
}
}
}
],
"AllowanceCharge": [
{
"BaseAmount": {
"currencyID": "SAR",
"value": "10000"
},
"MultiplierFactorNumeric": "5",
"Amount": {
"currencyID": "SAR",
"value": "500"
},
"TaxCategory": {
"ID": "S",
"Percent": "15",
"TaxScheme": {
"ID": "VAT"
}
}
}
],
"TaxTotal": [
{
"TaxAmount": {
"currencyID": "SAR",
"value": "1140"
},
"TaxSubtotal": [
{
"TaxableAmount": {
"currencyID": "SAR",
"value": "7600"
},
"TaxAmount": {
"currencyID": "SAR",
"value": "1140"
},
"TaxCategory": {
"ID": "S",
"Percent": "15",
"TaxScheme": {
"ID": "VAT"
}
}
}
]
}
],
"LegalMonetaryTotal": {
"LineExtensionAmount": {
"currencyID": "SAR",
"value": "8100"
},
"AllowanceTotalAmount": {
"currencyID": "SAR",
"value": "500"
},
"TaxExclusiveAmount": {
"currencyID": "SAR",
"value": "7600"
},
"TaxInclusiveAmount": {
"currencyID": "SAR",
"value": "8740"
},
"PrepaidAmount": {
"currencyID": "SAR",
"value": "0"
},
"PayableAmount": {
"currencyID": "SAR",
"value": "8740"
}
},
"PaymentMeans": [
{
"PaymentMeansCode": "10",
"InstructionNote": {
"en": "10",
"ar": ""
},
"PayeeFinancialAccount": {
"PaymentNote": {
"en": "",
"ar": ""
}
}
}
]
},
"CustomFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}Response Parameters
For Successful request you will receive a response with HTTP Status 200 with the below schema.
| Parameter | Type | Description |
|---|---|---|
QRCode | String | Rendered QR Code image in base64encoded PNG format. |
RawQRCode | String | QR Code payload in base64encoded TLV format. |
SellerVatNumber | String | Seller VAT identification number. |
BuyerVatNumber | String | Buyer VAT identification number. |
Status | String | "Generated" if the request is successful. |
InvoiceType | String | Document Type: INV-INVOICE, CRN-CREDIT NOTE, DBN-DEBIT NOTE. |
InvoiceNumber | String | Invoice number. |
InvoiceDate | String | Format YYYY-MM-DD, Invoice date. |
For Failed request you will receive a response with HTTP Status 400 with the below schema.
| Parameter | Type | Description |
|---|---|---|
ErrorList | Array of Error Detail | Details of all errors |
Error Details
| Parameter | Type | Description |
|---|---|---|
ErrorCode | String | Error Code |
ErrorMessage | String | Error Message |
ErrorSource | String | Error Source |
Path | String | Field name throwing error |
Sample Response
{
"QRCode": "iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQAAAABUY/ToAAACu0lEQVR4Xu2YQW7sMAxDDfQAOVKuPkfKAQq4JinFsZOpP7r7GHLhxBKfuiHsTEv9o15lrvyrTK5kciWTK5lcyeRKJlcyudJ/SZbQl6plr9/atje4trbdj3SpZtLkQHJTD1gP4t8Ry5dwbNVIs0mTE4loBQSdLiWydTX3kkiTapicyQJdSLiGrkmTCzJuvLOm9FEmTf5K9t7GNwxCQ+Q5t5tNmhzJEKIF/HlJl8l3yyeTF72EwwD/GMbBN+5NfjhZKPphJdTuQxp6o/2swx1p0uQDqQqsgvBfAb7FacUZWNQwafKJ5CYyl0mLmrLZA2rS5J3sx5PKrO0VNUzTtkHZqCZlMHkhGbwzfQyZpqkRunxTmTQ5kBW3m548t84acQ0aw2gyaiYzfSgXfkT19O1oRCwLICwcZNLkA6lvcFQ25hALvsaVPjX4F2IxaXIiYahxPDUrhUQyc5zLUlpMmpxJ4TuWcsEjfbktkUj4TJocSW0q7j756eIgnVvAjxxp0uQDyczxniMZX1IRQY3UcJhNmryT7UlDuPJzCi7UXpggZcOkyZk8Dyq4iF/ThxlQ/AWTJm9kugBp0DV9vSHfbtLkOxJ+5Qv+8/DKow012k2avJGVdx/PrcKzjNbKQazlyDjpTJqcSfYCYhlbvKWraedwpNSkyQcScWtdZE5vcOkE47mVOcSbSZPPZLPieJJfNfmTrLmYNPlI8nEwdrDyjacaEklc6oecSZNXsitmUAPORl9MQiZrT1+IwevpYwPpAx4XZZlOMJMmRXJTW0+Zw7WnpJ1H1rSYNDmT9Ctfmb4wnGGEYJFMmnxH0s+Pbs2ga8PaLBwkmTQp3ck4svjrjQbghLbnX3QmTYrkQyQMHIQGIhhb4N1s0uRIhkBm3NLA7Ve+3dJn0iTJP8jkSiZXMrmSyZVMrmRyJZMrfQz5A8JgUny/HLvzAAAAAElFTkSuQmCC",
"RawQRCode": "ARlHdWxmIEFyYWJpYW4gRXF1aXBtZW50IENvAg8zMDA0NTk4MDM4MDAwMDMDEzIwMjEtMDgtMTQgMTU6NDQ6MjAEBDg3NDAFBDExNDA=",
"SellerVatNumber": "300459803800003",
"BuyerVatNumber": "300761193700003",
"Status": "GENERATED",
"InvoiceType": "INV",
"InvoiceNumber": "K01082K5",
"InvoiceDate": "2021-08-14"
}{
"ErrorList": [
{
"ErrorCode": "6002",
"ErrorMessage": "Invalid value for the field EInvoice.TaxTotal. Send the correct the value and try again",
"ErrorSource": "CLEARTAX",
"Path": "EInvoice.TaxTotal"
}
]
}Last updated