Generate B2C e-Invoice (Asynchronous).
This API is used to generate a new Invoice.
Request Method
POST
Request URL
{{BASE_URL}}/Api/EInvoice/InvoiceReportingRequest Authorization
Bearer token
String
Cannot be empty.
Mandatory.
Request Body
ID
String
INV-00002
Mandatory. invoice number
DeviceID
string
0059BA36-50EF-4183-A127-4D867738EF74
Mandatory. GUID appears at the time of onboarding
VATNumber
string
3xxxxxxxxxxxxx3
Mandatory
VAT_Percent
decimal
15
Mandatory
DeliveryDate
string
"2024-11-30"
conditional. required only for B2B
BillingReference
string
INV-00001
conditional. IF InvoiceTypeCode is 381 AND 383 Then Requried
IssueDate
string
"2024-11-29"
Mandatory
IssueTime
string
"19:04:50"
Mandatory
AllowanceCharge
decimal
0.00
Mandatory
Invoice Type Object
InvoiceTypeCode
string
388, 381, 383
Mandatory. 388 for invoice, 381 for credit note, 383 for debit note
InvoiceTypeName
String
0200000
Mandatory.
Payment Means Object
paymentMeansCode
String
10
Mandatory. The means, expressed as code, for how a payment is expected to be or has been settled.
A Payment instruction (BG-16) shall specify the Payment means type code (BT-81). Payment means in an invoice MUST be coded using UNCL4461 code list.
Payment means code (BT-81) in an invoice must contain one of the values: 10 - In cash, 30 - Credit, 42 - Payment to bank account , 48 - Bank card , 1 - Instrument not defined (Free text) .
In the simplified tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02) this value is optional.
paymentNote
String
free text
Mandatory.
instructionNote
string
free text
Mandatory
BUYER Object
BUYERNAME
String
Saudi Arabian Co.
Mandatory
BUYERTYPE
String
B2C
Mandatory
BUYER_VAT
String
3xxxxxxxxxxxxx3
Mandatory
TAX_SCHEME
String
VAT
Mandatory
PARTYIDENTIFICATION
String
CRN
Mandatory
BUILDINGNUMBER
String
1234
Mandatory. must be 4 digits
CITYSUBDIVISIONNAME
String
Jeddah
Mandatory
CITY
String
Jeddah
Mandatory
POSTALZONE
String
12345
Mandatory. must be 5 digits
COUNTRYSUBENTITY
String
saudi arabia
Mandatory
COUNTRYCODE
String
SA
Mandatory
Invoice Line Object
Name
string
Item 1
Mandatory
Price
decimal
100.00
Mandatory
InvoicedQuantity
int
2
Mandatory
ItemTaxCategory
string
S,Z,E,O
Mandatory
UnitOfMeasure
string
each
Mandatory
TaxExemptionReasonCode
string
VATEX-SA-32
conditional. required if ItemTaxCategory is Z,E,O
TaxExemptionReason
string
export of goods
conditional. required if ItemTaxCategory is Z,E,O
Sample Request
{
"ID": "INV-00001",
"InvoiceType": {
"InvoiceTypeCode": "388",
"InvoiceTypeName": "0200000"
},
"VATNumber": "3xxxxxxxxxxxxx3",
"DeviceId": "28f33520-2fcb-6ace-94e2-6e61dbcc1932",
"VAT_Percent": 15,
"DELIVERYDATE": "2024-11-30",
"BILLINGREFERENCE": "510324",
"PAYMENTMEANS": {
"PAYMENTMEANSCODE": "10",
"PAYMENTNOTE": "",
"INSTRUCTIONNOTE": ""
},
"IssueDate": "2024-11-29",
"IssueTime": "19:04:50",
"BUYER": {
"BUYERNAME": "SAUDI ARABIAN COMPANY",
"BUYERTYPE": "B2C",
"BUYER_VAT": "3xxxxxxxxxxxxx3",
"TAX_SCHEME": "VAT",
"PARTYIDENTIFICATION": "CRN",
"STREETNAME": "شارع الجادة الشرقية",
"BUILDINGNUMBER": "4297",
"CITYSUBDIVISIONNAME": "حي الظهران الغربي",
"CITY": "الظهران",
"POSTALZONE": "34465",
"COUNTRYSUBENTITY": "المنطقة الشرقية",
"COUNTRYCODE": "SA"
},
"InvoiceLine": [
{
"Name": "ST04 - Fresh Air Duct",
"Price": 32.00,
"InvoicedQuantity": 4,
"ItemTaxCategory": "S",
"UnitOfMeasure": "EA",
"TaxExemptionReasonCode": "",
"TaxExemptionReason": ""
},
{
"Name": "test for zero rated",
"Price": 100.00,
"InvoicedQuantity": 5,
"ItemTaxCategory": "Z",
"UnitOfMeasure": "EA",
"TaxExemptionReasonCode": "VATEX-SA-32",
"TaxExemptionReason": "Export of goods"
},
{
"Name": "ST05 - Fresh Air Duct",
"Price": 62.00,
"InvoicedQuantity": 2,
"ItemTaxCategory": "E",
"UnitOfMeasure": "EA",
"TaxExemptionReasonCode": "VATEX-SA-29",
"TaxExemptionReason": "Financial services mentioned in Article 29 of the VAT Regulations"
},
{
"Name": "ST06 - Fresh Air Duct",
"Price": 63.33,
"InvoicedQuantity": 4,
"ItemTaxCategory": "O",
"UnitOfMeasure": "EA",
"TaxExemptionReasonCode": "VATEX-SA-OOS",
"TaxExemptionReason": "Reason is free text, to be provided by the taxpayer on case to case basis."
}
],
"AllowanceCharge": 0.00
}Response Status Codes
200
For a successful Clearance Invoice
400
For any kind of validation issues.
401
If the user is not authenticated for the operation.
403
If the user is not authorized for the operation.
500
HTTP Internal Server Error. Returned when the service faces internal errors.
Response Schema
status
int
status code
response
object
message
string
Response object
DeviceId
String
Mandatory
Status
String
Mandatory. Status of E-Invoice QR Code Generation and acceptance by ZATCA. Explained below.
QrCodeStatus
String
Mandatory. Status of E-Invoice QR Code.
GENERATED, NOT_GENERATED, GENERATION_FAILED
InvoiceStatus
String
Mandatory. Status of submission to ZATCA.
NOT_SUBMITTED, FAILED NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED ACCEPTED_WITH_WARNING,
PENDING
QRCode
String
Optional. Rendered QR Code image in base64encoded PNG format.
If clearance fails, this will be null.
RawQRCode
String
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
Optional. In case of Standard invoices, XML returned by ZATCA.
In case of Simplified invoices, XML used for reporting.
UUID
String
Optional. UUID sent to ZATCA
Evs Engine generates this before sending to ZATCA, if not sent in input.
ICV
String
Optional. Invoice counter value sent to ZATCA
PIH
String
Optional. Previous hash value, Invoice hash value of previous invoice reported/cleared for same deviceId
InvoiceHash
String
Optional. Invoice hash value,
Hash value of current invoice xml by removing tags ext:UBLExtensions, cac:AdditionalDocumentReference:QRCode
InvoiceType
String
Mandatory. Document Type. INV - Invoice, CRN - Credit Note, DBN - Debit Note.
InvoiceNumber
String
Mandatory. Invoice number (ID) as per the input.
IssueDate
String
Mandatory. Issue Date as per the input.
IssueTime
String
Mandatory. Invoice issue time. The time when the invoice was issued.
GeneratedDate
String
Mandatory. Date on which the invoice was generated.
GeneratedTime
String
Mandatory. Invoice generation time. The time when the invoice was generated.
SellerVatNumber
String
Mandatory. Seller VAT identification number.
BuyerVatNumber
String
Optional. Buyer VAT identification number.
ErrorList
Array
Optional. Validation Errors. An array of Error Details Objects. In case there are no errors, this will be an empty Array ([]).
WarningList
Array
Optional. Warnings from ZATCA. An array of Error Details Objects. In case there are no warnings, this will be an empty Array ([]).
Message
String
Optional. Message received from ZATCA.
Error List object
ErrorCode
String
100401-Authentication Failed, 100403 = Authorization Failed
ErrorMessage
String
Mandatory. Human readable error message.
ErrorSource
String
EVS_Engine
Warning List object
ErrorCode
String
100401-Authentication Failed, 100403 = Authorization Failed
ErrorMessage
String
Mandatory. Human readable error message.
ErrorSource
String
EVS_Engine
Sample Response
Success - HTTP Status Code - 200
{
"status": 200,
"response": {
"deviceId": "28f33520-2fcb-4ace-93e2-6e61dbcc5939",
"status": "PENDING",
"qrCodeStatus": "GENERATED",
"invoiceStatus": "PENDING",
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhE..",
"rawQRCode": "ARNFdmluY2libGUgU2..",
"invoiceXml": null,
"uuid": "f713c0dd-87bf-4935-88c9-2284137e074c",
"icv": "35",
"pih": "rp2AXhdXjl9T79S3cUSnJFLKrp6AcNcY0y0T4=",
"invoiceHash": "WKvutQo3ExeBNLGVfgFvOxZVrGIlXibqBc6LW=",
"invoiceType": "INV",
"invoiceNumber": "INV-00001",
"issueDate": "2024-11-29",
"issueTime": "19:04:50",
"generatedDate": "1/9/2025",
"generatedTime": "10:29:36",
"sellerVatNumber": "3xxxxxxxxxxxxx3",
"buyerVatNumber": "3xxxxxxxxxxxxx3",
"errorList": null,
"warningList": null,
"message": null
},
"message": "Success"
}Error - HTTP Status Code - 400
{
"status": 400,
"response": {
"deviceId": "28f33520-2fcb-4ace-93e2-6e61dbcc5939",
"status": "NOT_GENERATED",
"qrCodeStatus": "NOT_GENERATED",
"invoiceStatus": "NOT_REPORTED",
"qrCode": null,
"rawQRCode": null,
"invoiceXml": null,
"uuid": "d2d20562-9ccb-44d1-803d-52eed2c03e7e",
"icv": null,
"pih": "NhhgziDqKvmfawWAY9kaf0vCvR1gUvygDQMIEt=",
"invoiceHash": "bLabqwQgB1itO0P7ttA+w7JEU6Su6P0kRmz18=",
"invoiceType": "INV",
"invoiceNumber": "INV-00001",
"issueDate": "1/9/2025",
"issueTime": "10:47:18",
"generatedDate": null,
"generatedTime": null,
"sellerVatNumber": "3xxxxxxxxxxxxx3",
"buyerVatNumber": "3xxxxxxxxxxxxx3",
"errorList": [
{
"errorCode": "certificate-permissions",
"errorMessage": "Production CSID does not cover Standard documents",
"errorSource": "CERTIFICATE_ERRORS"
}
],
"warningList": [
{
"errorCode": "BR-KSA-15",
"errorMessage": "The tax invoice ((invoice type code (BT-30) = 388) & (invoice transaction code (KSA-2) has “01” as first 2 digits)) must contain the supply date (KSA-5).",
"errorSource": "KSA"
}
],
"message": null
},
"message": "Failure"
}Error - HTTP Status Code - 401
{
"status": 401,
"respose": "Authentication Failed",
"message": "EVS_Portal"
}Error - HTTP Status Code - 403
{
"status": 409,
"response": "Invoice Number already Exist",
"message": "Status with REPORTED"
}API Validations
The token you generated from the token API it should place in authorisation token as a bearer token
Last updated