Generate e-invoice async ( B2C )
Abc
Request Method
POST
Request URL
{{BASE_URL}}/api/v1/einvoices/generate/asyncRequest Headers
x-evs-auth-token
String
Cannot be empty.
Mandatory. User auth token.
vat
String
Cannot be empty.
Mandatory. VAT or Group VAT of the entity.
Request Body
EInvoice
Object
Mandatory. EInvoice Object.
Prodsecret
String
Mandatory. Prodsecret
ProdbinarySecurityToken
String
Mandatory.ProdbinarySecurityToken
binarySecurityToken
String
Mandatory. binarySecurityToken
PrivateKey
String
Mandatory. PrivateKey
Vat
String
Mandatory. Vat
prevhash
String
NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==
Mandatory. prevhash
EInvoice Object
UBLVersionID
String
Optional. Default value: "2.1"
ProfileID
String
1.0
Mandatory. Business process type. Identifies a user-defined profile of the customization of UBL being used. Default value: "reporting:1.0"
ID
String
2021/02/12/1230
Mandatory. Invoice number. A unique identification of the Invoice.
ICV
Number
46531
Mandatory. Invoice counter value sent to ZATCA
InvoiceTypeCode
Object
388
Mandatory. Invoice Type Code Object
IssueDate
String
2021-02-25
Mandatory. Invoice issue date (gregorian calendar). The date when the Invoice was issued as per Article 53 of the VAT Implementing Regulation. The document issue date must be less or equal to the current date.
IssueTime
String
16:55:24
Mandatory. Invoice issue time. The time when the invoice was issued.
Delivery
Array
"Conditional. Required in case of Credit Debit Notes. Array of Delivery Objects. Default: []"
BillingReference
Array
Conditional. Required only in case the invoice type is Debit Note or Credit Note. Not required if the invoice type is Tax Invoice. Array of Billing Reference Objects.
OrderReference
Object
Optional. Order Reference Object. Default: null
ContractDocumentReference
Array
Optional. Array of Contract Document Reference Objects. Default: null
DocumentCurrencyCode
String
SAR
Mandatory. Invoice currency code. The currency in which all Invoice amounts are given, except for the Total VAT amount in accounting currency. Default: "SAR".
TaxCurrencyCode
String
SAR
Mandatory. Tax currency code. The currency used for VAT accounting and reporting purposes as accepted or required in the country of the Seller. Shall be used in combination with the Total VAT amount in accounting currency (BT-111). Default: "SAR".
AccountingSupplierParty
Object
Mandatory. Accounting Supplier Party Object
AccountingCustomerParty
Object
Mandatory. Accounting Customer Party Object
InvoiceLine
Array
Mandatory. Array of Invoice Line Item Objects
AllowanceCharge
Array
Conditional. Required in case of invoice level discount. Allowance Charge Object
TaxTotal
Array
Mandatory. Array of Tax Total Objects
LegalMonetaryTotal
Object
Mandatory. Legal Monetary Total Object
PaymentMeans
Array
Optional
Note
String
Optional. Invoice note. A textual note that gives unstructured information that is relevant to the Invoice as a whole. Default: null
InvoiceTypeCode Object
name
String
010100
Mandatory. A code of the invoice subtype and invoices transactions. The invoice transaction code must exist and respect the following structure: NNPNESB where - NN (positions 1 and 2) = invoice subtype: - 01 for tax invoice - 02 for simplified tax invoice. P (position 3) = 3rd Party invoice transaction, 0 for false, 1 for true N (position 4) = Nominal invoice transaction, 0 for false, 1 for true E (position 5) = Exports invoice transaction, 0 for false, 1 for true S (position 6) = Summary invoice transaction, 0 for false, 1 for true B (position 7) = Self billed invoice. Self-billing is not allowed (KSA-2, position 7 cannot be ""1"") for export invoices (KSA-2, position 5 = 1).
For simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02), only the following are accepted: third party (KSA-2, position 3 = 1), nominal supply (KSA-2, position 4 = 1) and summary transactions (KSA-2,, position 6 = 1) XC
value
String
Mandatory. A code specifying the functional type of the Invoice. The invoice type code must be equal to one of value from the subset of UN/CEFACT code list 1001, D.16B agreed for KSA electronic invoices. Allowed: 388 - Tax Invoice, 383 - Debit Note, 381 - Credit Note
Delivery Array
Delivery[0].ActualDeliveryDate
String
Conditional. Supply date (gregorian calendar). 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).
The date when the supply is performed. For credit and debit notes, it acts as the original supply date.
If the invoice contains a supply end date (KSA-2424), then the invoice must contain a supply date (KSA-5).
Delivery[0].LatestDeliveryDate
String
Optional. Supply end date. Calendar field "End Date" for Continuous Supplies.
If the invoice contains a supply end date (KSA-2424), then this date must be greater than the supply date (KSA-5).
Default: null
Billing Reference Object
InvoiceDocumentReference
Object
Conditional. Required only in case the invoice type is Debit Note or Credit Note. Not required if the invoice type is Tax Invoice. Invoice Document Reference Object
InvoiceDocumentReference.ID
string
Conditional. Required only in case the invoice type is Debit Note or Credit Note. Not required if the invoice type is Tax Invoice. The sequential number (Invoice number BT-1) of the original invoice(s) that the credit/debit note is related to.
Order Reference Object
ID
String
Optional. An identifier of a referenced purchase order, issued by the Buyer. Default: null
Contract Document Reference Object
ID
String
Optional. The identification of a contract. Default: null
Accounting Supplier Party Object
Party
Object
Mandatory. Supplier Party Object.
Party.PartyLegalEntity
object
Mandatory. Seller Party Legal Entity Object
Party.PartyLegalEntity.RegistrationName
String
SELLER SA
Mandatory. Seller name
Party.PartyTaxScheme
Object
Conditional. The invoice must contain the seller VAT registration number (BT-31) and/or seller group VAT registration number (KSA-18). Seller VAT Object.
Party.PartyTaxScheme.CompanyID
String
3xxxxxxxxx00003
Mandatory. Seller VAT identifier - taxpayer entity Also known as Seller VAT identification number.
Party.PartyTaxScheme.TaxScheme
Object
Mandatory. Seller Party Tax Scheme object
Party.PartyTaxScheme.TaxScheme.ID
String
Mandatory. Tax Scheme ID should be "VAT".
Party.PartyIdentification
Object
Mandatory. Supplier Party Identification Object.
Party.PartyIdentification.ID
Object
Mandatory. Supplier Party Identification ID Object.
Party.PartyIdentification.ID.value
String
456789123
Mandatory in Phase 2 - ONLY one of the Other seller ID from the below list:
Commercial registration number with "CRN" as schemeID
Momra license with "MOM" as schemeID
MLSD license with "MLS" as schemeID
Sagia license with "SAG" as schemeID
Other OD with "OTH" as schemeID
Party.PartyIdentification.ID.schemeID
String
Mandatory in Phase 2 - Other seller ID is one of the list:
"CRN" - Commercial registration number,
"MOM" - Momra license,
"MLS" - MLSD license,
"SAG" - Sagia license,
"OTH" - Other ID
Party.PostalAddress
Object
Mandatory. Seller Postal Address object. Seller address must contain additional number, street name, building number, postal code, city, Neighborhood, country code. For more information please access this link: https://www.address.gov.sa/en/a ddress-format/overview
Party.PostalAddress.StreetName
String
Main street 1
Mandatory. Seller address line 1 - the main address line in an address.
Party.PostalAddress.AdditionalStreetName
String
Optional. Seller address line 2 - an additional address line in an address that can be used to give further details supplementing the main line. Default: null
Party.PostalAddress.BuildingNumber
String
Mandatory. Seller address building number. The seller address building number must contain 4 digits..
Party.PostalAddress.PlotIdentification
String
Optional. Seller address additional number. Seller Address Additional number must be 4 digits.
Party.PostalAddress.CityName
String
Riyadh
Mandatory. The common name of the city, town or village, where the Seller's address is located.
Party.PostalAddress.CitySubdivisionName
String
District A
Mandatory. The name of the subdivision of the Seller city, town, or village in which its address is located, such as the name of its district or borough.
Party.PostalAddress.PostalZone
String
72415
Mandatory. Seller post code. Seller postal code (BT-38) must be 5 digits.
Party.PostalAddress.CountrySubentity
String
Optional. Seller country subdivision
Party.Country
object
Mandatory. Country
Party.Country.IdentificationCode
String
SA
Mandatory. Seller country code. Country codes in an invoice MUST be coded using ISO code list 3166-1. The seller address country code (BT-40) must be “SA”.
Accounting Customer Party Object
Party
Object
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note.
Buyer Party Object.
For simplified documents, in case of private education and private healthcare to citizens, the Buyer name and Additional buyer ID is required only in Phase II. For standard documents, buyer details are mandatory in Phase I itself.
Party.PartyLegalEntity
Object
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit ntoe or a debit note.
Buyer Party Legal Entity Object
Party.PartyLegalEntity.RegistrationName
String
Mandatory for Standard Invoices, Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note.
The full name of the Buyer.
Party.PartyTaxScheme
Object
Conditional. Required if invoice type is standard and not export. Buyer Party Tax Schema object.
Party.PartyTaxScheme.CompanyID
String
Conditional. Required if invoice type is standard. The Buyer's VAT identifier (also known as Buyer VAT identification number).
If it exists in the invoice, and If it is not an export invoice (KSA-2, position 5 is false), the buyer VAT registration number (BT-48) must contain 15 digits. The first digit and the last digit is “3”.
If it is an export invoice (KSA-2, position 5 is true), the buyer VAT registration number (BT-48) and the buyer group VAT registration number (KSA-20) must not exist in the invoice.
Party.PartyTaxScheme.TaxScheme
object
Conditional. Required if invoice type is standard and not export. Optional for Simplified. Buyer Party Tax Schema ID object.
Party.PartyTaxScheme.TaxScheme.ID
String
Mandatory. Tax Scheme ID should be "VAT".
Party.PartyIdentification
Object
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note. Buyer Party Identification Object.
Party.PartyIdentification.ID
Object
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note. Buyer Party Identification ID Object.
Party.PartyIdentification.ID.value
String
Mandatory. Other Buyer ID must be one of the following list:
National ID with "NAT" as schemeID
Tax Identification Number "TIN" as schemeID
Iqama Number with "IQA" as schemeID
Passport ID with "PAS" as schemeID
Commercial registration number with "CRN" as schemeID
Momra license with "MOM" as schemeID
MLSD license with "MLS" as schemeID
Sagia license with "SAG" as schemeID
GCC ID with "GCC" as schemeID
Other ID with "OTH" as schemeID
If the tax exemption reason code (BT-121) is equal to VATEX-SA- EDU or VATEX-SA-HEA, then the other buyer ID (BT-46) is mandatory and must be national ID (BT-46-1 = NAT)
Party.PartyIdentification.ID.SchemeID
String
Mandatory in Phase 2 - Other Buyer ID must be one of the following list:
"NAT" - National ID
"TIN" - Tax Identification Number
"IQA" - Iqama Number
"PAS" - Passport ID
"CRN" - Commercial registration number
"MOM" - Momra license
"MLS" - MLSD license
"SAG" - Sagia license
"GCC" - GCC ID
"OTH" - Other ID
Party.PostalAddress
object
"Conditional. An Invoice shall contain the Buyer postal address (BG-8). Not applicable for simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02).
Buyer address must contain a street (BT-50), city (BT-52), postal code (BT-53), country code (BT- 55). This rule does not apply on the simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02)."
Party.PostalAddress.StreetName
String
Buyer address line 1 - the main address line in an address. Mandatory for Standard Invoices, Conditional for Simplified Invoices.
Party.PostalAddress.AdditionalStreetName
String
Optional. Buyer address line 2 - an additional address line in an address that can be used to give further details supplementing the main line.
Party.PostalAddress.BuildingNumber
String
Buyer address building number.
Mandatory for Standard Invoices, Conditional for Simplified Invoices.
Party.PostalAddress.PlotIdentification
String
Buyer address additional number. Optional for both Standard Invoices and Simplified Invoices.
Party.PostalAddress.CityName
String
The common name of the city, town or village, where the Buyer's address is located. Mandatory for Standard Invoices, Conditional for Simplified Invoices.
Party.PostalAddress.CitySubdivisionName
String
The name of the subdivision of the Buyer city, town, or village in which its address is located, such as the name of its district or borough. Mandatory for Standard Invoices and Simplified Invoices.
Party.PostalAddress.PostalZone
String
Buyer postal code. Mandatory for Standard Invoices, Conditional for Simplified Invoices.
Party.PostalAddress.CountrySubentity
String
Buyer country subdivision. Optional for both Standard Invoices and Simplified Invoices.
Party.PostalAddress.Country
Object
Buyer country object. Mandatory for Standard Invoices, Conditional for Simplified Invoices.
Party.PostalAddress.Country.IdentificationCode
String
Mandatory. Buyer country code. Country codes in an invoice MUST be coded using ISO code list 3166-1. If the buyer country code (BT-55) exists in the invoice, and If it is not an export invoice (KSA-2, position 5 is false), then the country code (BT-55) must be “SA”. For more information please access this link: https://www.address.gov.sa/en/address-format/overview Mandatory for Standard Invoices, Optional for Simplified Invoices.
Invoice Line Object
ID
String
1
"Mandatory. Each Invoice line (BG-25) shall have an Invoice line identifier (BT-126).
A unique identifier for the individual line within the Invoice.
An Invoice shall have at least one Invoice line (BG-25)"
Item
Object
Mandatory. Each Invoice line (BG-25) shall contain the Item name (BT-153).
Item.Name
String
Item name
"Mandatory. Each Invoice line (BG-25) shall contain the Item name (BT-153).
The description of goods or services as per Article 53 of the VAT Implementing Regulation."
Item.BuyersItemIdentification
Object
Optional
Item.BuyersItemIdentification.ID
String
Optional. An identifier, assigned by the Buyer, for the item.
Item.SellersItemIdentification
Object
Optional
Item.SellersItemIdentification.ID
String
Optional. An identifier, assigned by the Seller, for the item.
Item.StandardItemIdentification
Object
Optional
Item.StandardItemIdentification.ID
String
"Optional. An item identifier based on a registered scheme.
This should include the product code type and the actual code. This list includes UPC (11 digit, 12 digit, 13 digit EAN), GTIN (14 digit), Customs HS Code and multiple other codes"
Item.ClassifiedTaxCategory
Object
Mandatory
Item.ClassifiedTaxCategory.ID
String
S
"Mandatory. Each Invoice line (BG-25) shall be categorized with an Invoiced item VAT category code (BT-151). The VAT category code for the invoiced item. An Invoice that contains a VAT breakdown group (BG-23) with a VAT category code (BT-118) ""Not subject to VAT"" shall not contain an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is not ""Not subject to VAT"". Invoice tax categories MUST be coded using UNCL5305 code list VAT category code must contain one of the values (S, Z, E, O).
Item.ClassifiedTaxCategory.Percent
String
20
"Mandatory. The VAT rate, represented as percentage that applies to the invoiced item as per Article 53 of the VAT Implementing Regulation
In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is ""Zero rated"" the Invoiced item VAT rate (BT-152) shall be 0 (zero). In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is ""Exempt from VAT"", the Invoiced item VAT rate (BT-152) shall be 0 (zero). An Invoice line (BG-2525) where the VAT category code (BT-151151) is ""Not subject to VAT"" shall not contain an Invoiced item VAT rate (BT-152152).
The VAT rates (BT-96119, BT-152) must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.
All the document amounts and quantities must be positive."
Item.ClassifiedTaxCategory.TaxScheme
Object
Mandatory. Tax scheme object.
Item.ClassifiedTaxCategory.TaxScheme.ID
String
VAT
Mandatory element. Use “VAT”
Price
Object
Mandatory. Each Invoice line shall contain the Item net price
Price.AllowanceCharge
Object
Conditional
Price.AllowanceCharge.ChargeIndicator
String
"Conditional.
An indicator that this AllowanceCharge describes a discount. The value of this tag indicating discount (Allowance) must be ""false"". This is in the context of the line item price level (not the line item level).
Charge on price level (BG-29) is NOT allowed. Only value 'false' allowed."
Price.AllowanceCharge.BaseAmount
Object
Conditional
Price.AllowanceCharge.BaseAmount.value
Number
"Conditional.
The unit price, exclusive of VAT, before subtracting Item price discount.
All the document amounts and quantities must be positive."
Price.AllowanceCharge.BaseAmount.currencyID
String
Conditional. Required if parent context exists. Currency for item gross prices. This is in the context of the line item price level (not the line item level).
Price.AllowanceCharge.Amount
Object
Conditional
Price.AllowanceCharge.Amount.value
Number
"Conditional.
The total discount subtracted from the Item gross price to calculate the Item net price. Only applies if the discount is provided per unit and if it is not included in the Item gross price. This is in the context of the line item price level (not the line item level).
All the document amounts and quantities must be positive."
Price.AllowanceCharge.Amount.currencyID
String
Conditional. Required if parent context exists. Currency for item price discount
Price.PriceAmount
Object
Mandatory. Each Invoice line shall contain the Item net price
Price.PriceAmount.value
Number
50.24
"Mandatory. The price of an item, exclusive of VAT, after subtracting item price discount.
If the gross price and the discount exist (in price level allowance charge), the Item net price has to be equal with the Item gross price minus the Item price discount.
Item net price must have a maximum two decimals.
All the document amounts and quantities must be positive."
Price.PrimeAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for item net price
Price.BaseQuantity
Object
Optional. Invoice line price base quantity.
Price.BaseQuantity.value
Number
"Optional. The number of item units to which the price applies.
All the document amounts and quantities must be positive."
Price.BaseQuantity.unitCode
String
Optional. Item price base quantity unit code.
InvoicedQuantity
Object
Mandatory. The quantity of items object
InvoicedQuantity.value
Number
"Mandatory. Each Invoice line shall have an Invoiced quantity.
The quantity of items (goods or services) that is charged in the Invoice line.
All the document amounts and quantities must be positive."
InvoicedQuantity.unitCode
String
Optional. The unit of measure that applies to the invoiced quantity.
AllowanceCharge[]
Array
"Conditional. Required only if there is invoice line item level allowance.
One or more Invoice level allowance charge objects."
AllowanceCharge[].ChargeIndicator
String
Conditional. Required in case of Standard Tax Invoice if parent context exists. Optional in the case of other standard and simplified documents.
An indicator that this AllowanceCharge describes a discount. The value of this tag indicating discount (Allowance) must be "false".
Allowance Indicator value MUST equal to 'false'
AllowanceCharge[].BaseAmount
Object
Conditional. Allowance base amount (BT-93, BT-137) must be provided when allowance percentage (BT-94, BT- 138) is provided.
AllowanceCharge[].BaseAmount.value
Number
Conditional. Allowance base amount (BT-93, BT-137) must be provided when allowance percentage (BT-94, BT- 138) is provided.
The base amount that may be used, in conjunction with the Invoice line allowance percentage, to calculate the Invoice line allowance amount.
The allowed maximum number of decimals for the Invoice line allowance base amount (BT- 137) is 2.
All the document amounts and quantities must be positive.
AllowanceCharge[].BaseAmount.currencyID
String
Conditional. Required if parent context exists.
AllowanceCharge[].MultiplierFactorNumeric
Number
Conditional. Required in case of Standard Tax Invoice if parent context exists. Optional in case of other standard and simplified documents.
The percentage that may be used, in conjunction with the Invoice line allowance base amount, to calculate the Invoice line allowance amount.
The allowance percentage values (BT-94, BT-138) must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.
Allowance percentage (BT-94, BT-138) must be provided when the allowance base amount (BT-93, BT-137) is provided.
AllowanceCharge[].Amount
Object
Mandatory. Each Invoice line allowance (BG-27) shall have an Invoice line allowance amount (BT- 136).
AllowanceCharge[].Amount.value
Number
Mandatory. Each Invoice line allowance (BG-27) shall have an Invoice line allowance amount (BT- 136). The amount of an allowance, without VAT.
Allowance amount (BT- 92, BT-136) must equal base amount (BT-93, BT- 137) * percentage (BT-94, BT-138) / 100 if base amount and percentage exists. The allowed maximum number of decimals for the Invoice line allowance amount (BT-136) is 2. All the document amounts and quantities must be positive.
AllowanceCharge[].Amount.currencyID
String
Conditional. Required if parent context exists.
AllowanceCharge[].AllowanceChargeReason
String
Conditional. Each Invoice line allowance (BG-27) shall have an Invoice line allowance reason (BT139) or an Invoice line allowance reason code (BT-140). This is not applicable for Invoice line charge.
AllowanceCharge[].AllowanceChargeReasoncode
String
Conditional. Each Invoice line allowance (BG-27) shall have an Invoice line allowance reason (BT139) or an Invoice line allowance reason code (BT-140). This is not applicable for Invoice line charge.
LineExtensionAmount
Object
Mandatory. Invoice line extension amount object.
LineExtensionAmount.value
Number
2000
Mandatory. Each Invoice line shall have an Invoice line net amount
The total amount of the Invoice line, including allowances (discounts). It is the item net price multiplied with the quantity. The amount is “net” without VAT. Invoice line net amount must equal (Invoiced quantity * (Item net price / item price base quantity))- Sum of invoice line allowance amount The allowed maximum number of decimals for the Invoice line net amount is 2. All the document amounts and quantities must be positive.
LineExtensionAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for invoice line net amount
TaxTotal
Object
Conditional. Required only in case of standard documents. Not required for simplified documents.
TaxTotal.TaxAmount
Object
Conditional. VAT amount as per Article 53
TaxTotal.TaxAmount.value
Number
Conditional. The line VAT amount (KSA-11) is mandatory for tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).
VAT amount as per Article 53
VAT amount at line level (KSA-11) must have a maximum two decimals.
The line VAT amount (KSA-11) must be Invoice line net amount (BT-131) x (Line VAT rate (BT- 152)/100).
All the document amounts and quantities must be positive.
TaxTotal.TaxAmount.currencyID
String
Conditional. Required if parent context exists. Currency for VAT line amount
TaxTotal.RoundingAmount
Object
Conditional. Line amount inclusive VAT
TaxTotal.RoundingAmount.value
Number
20.04
Conditional. The line amount with VAT (KSA- 12) is mandatory for tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).
Line amount inclusive VAT.
Amount with VAT at line level (KSA-12) must have a maximum two decimals.
The line amount with VAT (KSA- 12) must be Invoice line net amount (BT-131) + Line VAT amount (KSA-11).
All the document amounts and quantities must be positive
TaxTotal.RoundingAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for line amount inclusive VAT
Allowance Charge Object
ChargeIndicator
String
"Mandatory. An indicator that this AllowanceCharge describes a discount. The value of this tag indicating discount (Allowance) must be ""false""."
BaseAmount
Object
"Conditional. Allowance base amount (BT-93, BT-137) must be provided when allowance percentage (BT-94, BT- 138) is provided. Allowance Charge Base Amount object."
BaseAmount.value
Number
"Conditional. Required if parent context exists.
The base amount that may be used, in conjunction with the Invoice line allowance percentage, to calculate the Invoice line allowance amount.
The allowed maximum number of decimals for the Document level allowance base amount (BT-93) is 2.
All the document amounts and quantities must be positive. "
BaseAmount.currencyID
String
Conditional. Required if parent context exists. Currency for invoice line allowance base amount
MultiplierFactorNumeric
Number
"Conditional. Allowance percentage (BT-94, BT-138) must be provided when the allowance base amount (BT-93, BT-137) is provided.
The allowance percentage values (BT-94, BT-138) must be from 0.00 to 100.00, with maximum six decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.
The percentage that may be used, in conjunction with the document level allowance base amount, to calculate the document level allowance amount."
Amount
Object
Mandatory. Allowance Charge Amount object.
Amount.value
Number
"Mandatory. Each Document level allowance (BG-20) shall have a Document level allowance amount (BT-92).
The allowed maximum number of decimals for the Document level allowance amount (BT-92) is 2.
Allowance amount (BT- 92, BT-136) must equal base amount (BT-93, BT- 137) * percentage (BT-94, BT-138) / 100 if base amount and percentage exists.
All the document amounts and quantities must be positive.
The amount of an allowance, without VAT."
Amount.currencyID
String
Mandatory. Currency for line allowance amount
TaxCategory
Object
Mandatory. Allowance Charge Tax Category Object
TaxCategory.ID
String
"Mandatory. Each Document level allowance (BG-20) shall have a Document level allowance VAT category code (BT-95).
An Invoice that contains a VAT breakdown group (BG-23) with a VAT category code (BT-118) ""Not subject to VAT"" shall not contain Document level allowances (BG-20) where Document level allowance VAT category code (BT-95) is not ""Not subject to VAT"".
VAT category code must contain one of the values (S, Z, E, O).
A coded identification of what VAT category applies to the document level allowance."
TaxCategory.Percent
Number
"Mandatory. The VAT rate, represented as percentage that applies to the document level allowance.
In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ""Standard rated"" the Document level allowance VAT rate (BT-96) shall be greater than zero. In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ""Zero rated"" the Document level allowance VAT rate (BT-96) shall be 0 (zero). In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ""Exempt from VAT"", the Document level allowance VAT rate (BT-96) shall be 0 (zero). A Document level allowance (BG-2020) where VAT category code (BT-9595) is ""Not subject to VAT"" shall not contain a Document level allowance VAT rate (BT-96).
The VAT rates (BT-96119, BT-152) must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed."
TaxCategory.TaxScheme
Object
Mandatory. Allowance Charge Tax Category Tax Scheme object.
TaxCategory.TaxScheme.ID
String
Mandatory. Use “VAT”
TaxSubtotal[].TaxCategory.TaxScheme
Object
Mandatory
TaxSubtotal[].TaxCategory.TaxScheme.ID
String
Mandatory element. Use “VAT”
Tax Total Object
TaxAmount
Object
Mandatory.
TaxAmount.value
Number
800.00
"Mandatory. The total VAT amount for the Invoice.
The Invoice total VAT amount is the sum of all VAT category tax amounts.
The VAT total amount expressed in the accounting currency accepted or required in the country of the Seller. To be used when the VAT accounting currency (BT-6) differs from the Invoice currency code (BT-5). The VAT amount in accounting currency is not used in the calculation of the Invoice totals.
The allowed maximum number of decimals for the Invoice total VAT amount is 2. The allowed maximum number of decimals for the Invoice total VAT amount in accounting currency is 2"
TaxAmount.currencyID
String
SAR
"Conditional. Required if parent context exists. Currency for total VAT amount Currency for invoice total VAT amount in accounting currency"
TaxSubtotal[]
Array
Mandatory. One or more Tax Subtotal objects.
TaxSubtotal[].TaxableAmount
Object
Mandatory. Each VAT breakdown shall have a VAT category taxable amount.
TaxSubtotal[].TaxableAmount.value
Number
200
"Mandatory. Each VAT breakdown shall have a VAT category taxable amount.
Sum of all taxable amounts subject to a specific VAT category code and VAT category rate (if the VAT category rate is applicable).
The sum of Invoice line net amount minus allowances on document level which are subject to a specific VAT category code and VAT category rate (if the VAT category rate is applicable).
In a VAT breakdown where the VAT category code is ""Not subject to VAT"" the VAT category taxable amount shall equal the sum of Invoice line net amounts minus the sum of Document level allowance amounts where the VAT category codes are ""Not subject to VAT"".
The allowed maximum number of decimals for the VAT category taxable amount is 2."
TaxSubtotal[].TaxableAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for VAT category taxable amount
TaxSubtotal[].TaxAmount
Object
Mandatory. Each VAT breakdown shall have a VAT category tax amount.
TaxSubtotal[].TaxAmount.value
Number
40
"Mandatory. Each VAT breakdown shall have a VAT category tax amount.
Calculated by multiplying the VAT category taxable amount with the VAT category rate for the relevant VAT category.
VAT category tax amount = VAT category taxable amount x (VAT category rate / 100), rounded to two decimals.
The VAT category tax amount in a VAT breakdown where VAT category code is ""Standard rated"" shall equal the VAT category taxable amount multiplied by the VAT category rate. The VAT category tax amount in a VAT breakdown where VAT category code is ""Zero rated"" shall equal 0 (zero). The VAT category tax amount In a VAT breakdown where the VAT category code equals ""Exempt from VAT"" shall equal 0 (zero). The VAT category tax amount in a VAT breakdown where the VAT category code is ""Not subject to VAT"" shall be 0 (zero).
The allowed maximum number of decimals for the VAT category tax amount is 2."
TaxSubtotal[].TaxAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for category tax amount
TaxSubtotal[].TaxCategory
Object
Mandatory.
TaxSubtotal[].TaxCategory.ID
String
"Mandatory. Each VAT breakdown shall be defined through a VAT category code.
Coded identification of a VAT category.
An Invoice that contains an Invoice line, a Document level allowance where the VAT category code is ""Zero rated"" shall contain in the VAT breakdown exactly one VAT category code equal with ""Zero rated"". An Invoice that contains an Invoice line, a Document level allowance where the VAT category code is ""Exempt from VAT"" shall contain exactly one VAT breakdown with the VAT category code equal to ""Exempt from VAT"". A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code , meaning ""Not subject to VAT"" or a VAT exemption reason text "" Not subject to VAT"" (or the equivalent standard text in another language)."
TaxSubtotal[].TaxCategory.Percent
String
"Conditional. Each VAT breakdown shall have a VAT category rate, except if the Invoice is not subject to VAT.
The VAT rate, represented as percentage that applies for the relevant VAT category.
The VAT rates must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed."
TaxSubtotal[].TaxCategory.TaxExemptionReasonCode
String
"Conditional. Required if tax category is Z/E/O.
A coded statement of the reason for why the amount is exempted from VAT.
A VAT breakdown with VAT Category code ""Standard rate"" shall not have a VAT exemption reason Code. A VAT breakdown with VAT Category code ""Exempt from VAT"" shall have a VAT exemption reason code or a VAT exemption reason text. A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code , meaning ""Not subject to VAT"" or a VAT exemption reason text "" Not subject to VAT"" (or the equivalent standard text in another language). A VAT breakdown with VAT Category code ""Zero rated"" shall have a VAT exception reason code and VAT exception reason text.
VAT exemption reason code must exists in the invoice, the codes Z, E must have Tax exemption (or exceptions) reason code and text - specific to Saudi Arabia"
TaxSubtotal[].TaxCategory.TaxExemptionReason
Dual String Object
-
Conditional. Required if tax category is Z/E/O. A textual statement of the reason why the amount is exempted from VAT or why no VAT is being charged A VAT breakdown with VAT Category code ""Standard rate"" shall not have a VAT exemption reason text. A VAT breakdown with VAT Category code ""Exempt from VAT"" shall have a VAT exemption reason code or a VAT exemption reason text. A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code, meaning ""Not subject to VAT"" or a VAT exemption reason text ""Not subject to VAT"" (or the equivalent standard text in another language). A VAT breakdown with VAT Category code ""Zero rated"" shall have a VAT exception reason code and VAT exception reason text
TaxSubtotal[].TaxCategory.TaxScheme
Object
Mandatory.
TaxSubtotal[].TaxCategory.TaxScheme.ID
String
VAT
Mandatory element. Use “VAT”
Legal Monetary Total Object
LineExtensionAmount
Object
Mandatory
LineExtensionAmount.value
Number
4200.00
Mandatory. Sum of all Invoice line net amounts in the Invoice without VAT
Sum of Invoice line net amount = Σ Invoice line net amount
The allowed maximum number of decimals for the Sum of Invoice line net amount is 2.
All the document amounts and quantities must be positive.
LineExtensionAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for invoicetotal amount
AllowanceTotalAmount
Object
Conditional. Required if the allowance is provided.
AllowanceTotalAmount.value
Number
Conditional. Required if the allowance is provided. Sum of all allowances on document level in the Invoice.
Note: Allowances on line level are included in the Invoice line net amount which is summed up into the Sum of Invoice line net amount.
Sum of allowances on document level = Σ Document level allowance amount
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive.
AllowanceTotalAmount.currencyID
String
Conditional. Required if parent context exists. Currency for invoice total amount without VAT
TaxExclusiveAmount
Object
Mandatory. An Invoice shall have the Invoice total amount without VAT.
TaxExclusiveAmount.value
Number
4000.00
"Mandatory. An Invoice shall have the Invoice total amount without VAT.
The total amount of the Invoice without VAT.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
TaxExclusiveAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for invoice total amount without VAT
TaxInclusiveAmount
Object
Mandatory. An Invoice shall have the Invoice total amount with VAT.
TaxExclusiveAmount.value
Number
4800.00
"Mandatory. An Invoice shall have the Invoice total amount without VAT.
The total amount of the Invoice without VAT.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
TaxExclusiveAmount.currencyID
String
SAR
Conditional. Required if parent context exists. Currency for invoice total amount without VAT
TaxInclusiveAmount
Object
Mandatory. An Invoice shall have the Invoice total amount with VAT.
TaxInclusiveAmount.value
Number
"Mandatory. An Invoice shall have the Invoice total amount with VAT.
The total amount of the Invoice with VAT. The Invoice total amount with VAT is the Invoice total amount without VAT plus the Invoice total VAT amount.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
TaxInclusiveAmount.currencyID
String
Conditional. Required if parent context exists. Currency for invoice total amount with VAT
PrepaidAmount
Object
Conditional. Required only if there is advance paid.
PrepaidAmount.value
Number
"Conditional. Required only if there is advance paid.
The sum of amounts which have been paid in advance including VAT. This amount is subtracted from the invoice total amount with VAT to calculate the amount due for payment.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
PrepaidAmount.currencyID
String
Conditional. Required if parent context exists. Currency for paid amount
PayableAmount
Object
Mandatory. An Invoice shall have the Amount due for payment.
PayableAmount.value
Number
4701.52
Mandatory. An Invoice shall have the Amount due for payment.
The outstanding amount that is requested to be paid.
This amount is the Invoice total amount with VAT minus the paid amount that has been paid in advance. The amount is zero in case of a fully paid Invoice.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive.
PayableAmount.currecyID
String
SAR
Conditional. Required if parent context exists. Currency for payable amount
Payment Means Object
PaymentMeansCode
String
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.
InstructionNote
String
Conditional. Required in case of Debit and credit note (invoice type code (BT-3) is equal to 383 or 381). Reasons for issuance of credit / debit note as per Article 40 (paragraph 1) of KSA VAT regulations, a Credit and Debit Note is issued for these 4 instances: Cancellation or suspension of the supplies after its occurrence either wholly or partially In case of essential change or amendment in the supply, which leads to the change of the VAT due; Amendment of the supply value which is pre-agreed upon between the supplier and consumer; In case of goods or services refund.
PayeeFinancialAccount
Object
Optional. Payee Financial Account Payment Note object. Default: null
PayeeFinancialAccount.PaymentNote
String
Optional. The payment terms, if mode of payment is credit. Free text. Default: null
Sample Request
{
"Prodsecret": "Zvy0b8d1sYY4z1Bj44gDg+m2CdbxzpRmtWwfvA52Yhc=",
"ProdbinarySecurityToken": "TUlJRS9EQ0NCS09nQXdJQkFnSVRNZ0FBQ...",
"binarySecurityToken": "TUlJQ0pUQ0NBY3VnQXdJQkFnSUdBWWhYaU...",
"PrivateKey": "MHcCAQEEILGQbaC8H8ZGxWNLkMncgWaBdrQEEIFU...",
"Vat": "311133710900003",
"prevhash": "E+RjEZtQWPKJcEEaJH2q4XbzYViI0HATpdqvS0NHrNc=",
"EInvoice": {
"UBLVersionID": "2.1",
"ProfileID": "reporting:1.0",
"ID": "16543",
"ICV": "156166151",
"InvoiceTypeCode": {
"name": "0200000",
"value": "388"
},
"IssueDate": "2023-05-16",
"IssueTime": "15:44:20",
"DocumentCurrencyCode": "SAR",
"TaxCurrencyCode": "SAR",
"AccountingSupplierParty": {
"Party": {
"PartyLegalEntity": {
"RegistrationName": "Evincible Solutions"
},
"PartyTaxScheme": {
"CompanyID": "311133710900003",
"TaxScheme": {
"ID": "VAT"
}
},
"PartyIdentification": {
"ID": {
"value": "311133710900003",
"schemeID": "CRN"
}
},
"PostalAddress": {
"StreetName": "Zagzoog Business Center",
"AdditionalStreetName": "King Abdullah branch rd",
"BuildingNumber": "1234",
"PlotIdentification": "2122",
"CitySubDivisionName": "Al Amal",
"CityName": "Jeddah",
"PostalZone": "65354",
"CountrySubentity": "KSA",
"Country": {
"IdentificationCode": "SA"
}
}
}
},
"AccountingCustomerParty": {
"Party": {
"PartyIdentification": {
"ID": {
"value": "700",
"schemeID": "700"
}
}
}
},
"InvoiceLine": [
{
"ID": "1",
"Item": {
"Name": "Dynamic Gp",
"ClassifiedTaxCategory": {
"ID": "S",
"Percent": 15,
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"PriceAmount": {
"currencyID": "SAR",
"value": 2.00
},
"AllowanceCharge": {
"ChargeIndicator": "true",
"AllowanceChargeReason": "discount",
"Amount": {
"currencyID": "SAR",
"value": 0.00
}
}
},
"InvoicedQuantity": {
"unitCode": "PCE",
"value": 2.00
},
"AllowanceCharge": [
{
"ChargeIndicator": "false",
"MultiplierFactorNumeric": "10",
"Amount": {
"currencyID": "SAR",
"value": 0.00
},
"AllowanceChargeReason": "AllowanceChargeReason",
"AllowanceChargeReasonCode": null
}
],
"LineExtensionAmount": {
"currencyID": "SAR",
"value": 4.00
},
"TaxTotal": {
"TaxAmount": {
"currencyID": "SAR",
"value": 0.60
},
"RoundingAmount": {
"currencyID": "SAR",
"value": 4.60
}
}
},
{
"ID": "2",
"Item": {
"Name": "Dynamic Gp2",
"ClassifiedTaxCategory": {
"ID": "S",
"Percent": 15,
"TaxScheme": {
"ID": "VAT"
}
}
},
"Price": {
"PriceAmount": {
"currencyID": "SAR",
"value": 2.00
},
"AllowanceCharge": {
"ChargeIndicator": "true",
"AllowanceChargeReason": "discount",
"Amount": {
"currencyID": "SAR",
"value": 0.00
}
}
},
"InvoicedQuantity": {
"unitCode": "PCE",
"value": 2.00
},
"AllowanceCharge": [
{
"ChargeIndicator": "false",
"MultiplierFactorNumeric": "10",
"Amount": {
"currencyID": "SAR",
"value": 0.00
},
"AllowanceChargeReason": "AllowanceChargeReason",
"AllowanceChargeReasonCode": null
}
],
"LineExtensionAmount": {
"currencyID": "SAR",
"value": 4.00
},
"TaxTotal": {
"TaxAmount": {
"currencyID": "SAR",
"value": 0.60
},
"RoundingAmount": {
"currencyID": "SAR",
"value": 4.60
}
}
}
],
"TaxTotal": [
{
"TaxAmount": {
"currencyID": "SAR",
"value": 1.20
}
},
{
"TaxAmount": {
"currencyID": "SAR",
"value": 1.20
},
"TaxSubtotal": [
{
"TaxableAmount": {
"currencyID": "SAR",
"value": 8.00
},
"TaxAmount": {
"currencyID": "SAR",
"value": 1.20
},
"TaxCategory": {
"ID": "S",
"Percent": 15.00,
"TaxScheme": {
"ID": "VAT"
}
}
}
]
}
],
"LegalMonetaryTotal": {
"LineExtensionAmount": {
"currencyID": "SAR",
"value": 8.00
},
"AllowanceTotalAmount": {
"currencyID": "SAR",
"value": 0.00
},
"TaxExclusiveAmount": {
"currencyID": "SAR",
"value": 8.00
},
"TaxInclusiveAmount": {
"currencyID": "SAR",
"value": 9.2
},
"PrepaidAmount": {
"currencyID": "SAR",
"value": 0.00
},
"PayableAmount": {
"currencyID": "SAR",
"value": 9.2
}
}
}
}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
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 Evs Engine, 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
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
ErrorCode
String
100401-Authentication Failed, 100403 = Authorization Failed
ErrorMessage
String
Mandatory. Human readable error message.
ErrorSource
String
EVS_Engine
Path
String
Help to finding Error
Warning List
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": "GENERATED",
"QrCodeStatus": "GENERATED",
"InvoiceStatus": "PENDING",
"QRCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAM....",
"RawQRCode": "ARNFdmluY2libGUgU29sdXRpb25zAg8zMTExMzM3MTA5MDAwMDMDF....",
"InvoiceXml": "DQo8SW52b2ljZSB4bWxucz0idXJuOm9hc2lzOm5hbWVz....",
"UUID": "e28f72a9-f297-4c3b-8437-f4e0d08902d2",
"ICV": "156166151",
"PIH": "5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9",
"InvoiceHash": "fbY1PZf7XAxFoOxH9UWWsXXjyr9FD2oiwhyu2nK0cPA=",
"InvoiceType": "INV",
"InvoiceNumber": "16541",
"IssueDate": "2023-05-16",
"IssueTime": "15:44:20",
"GeneratedDate": "5/23/2023",
"GeneratedTime": "01:06:32",
"SellerVatNumber": "311133710900003",
"BuyerVatNumber": null,
"WarningList": [],
"ErrorList": [],
"Message": null
}Error - HTTP Status Code - 400
{
"Status": "GENERATION_FAILED",
"QrCodeStatus": "GENERATION_FAILED",
"InvoiceStatus": "FAILED",
"InvoiceType": "INV",
"InvoiceNumber": "16541",
"IssueDate": "2023-05-27",
"IssueTime": "15:44:20",
"SellerVatNumber": "311133710900003",
"ErrorList": [
{
"ErrorCode": "00400",
"ErrorMessage": "Seller ID is null",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.AccountingSupplierParty.Party.PartyIdentification.ID.value"
},
{
"ErrorCode": "00400",
"ErrorMessage": "Buyer ID is null",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.AccountingCustomerParty.Party.PartyIdentification.ID.value"
},
{
"ErrorCode": "00400",
"ErrorMessage": "Payment means code in an invoice must contain one of the values (10, 30, 42, 48, 1).",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.PaymentMeans.PaymentMeansCode"
},
{
"ErrorCode": "00400",
"ErrorMessage": "The document issue date must be less than or equal to the current date",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.IssueDate"
},
{
"ErrorCode": "00400",
"ErrorMessage": "Buyer name is mandatory for Simplified Tax Invoice and associated credit/debit notes.",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.AccountingCustomerParty.Party.PartyLegalEntity.RegistrationName"
},
{
"ErrorCode": "00400",
"ErrorMessage": "The allowed maximum number of decimals for the VAT category tax amount is 2",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.TaxTotal.TaxSubtotal.TaxAmount"
},
{
"ErrorCode": "00400",
"ErrorMessage": "The allowed maximum number of decimals for the Invoice total VAT amount is 2.",
"ErrorSource": "EVS_Engine",
"Path": "EInvoice.TaxTotal.TaxAmount.value"
}
]
}Error - HTTP Status Code - 401
{
"ErrorCode": "100401",
"ErrorMessage": "Authentication Failed",
"ErrorSource": "EVS_Engine"
}Error - HTTP Status Code - 403
{
"ErrorCode": "100403",
"ErrorMessage": "Authorization Failed",
"ErrorSource": "EVS_Engine"
}Error - HTTP Status Code - 500
{
"ErrorCode": "",
"ErrorMessage": "Invalid country code name, please provide a valid country code name",
"ErrorSource": "Engine Error"
}API Validations
Other Seller ID is Mandatory.
Other Buyer ID is Mandatory.
Payment type code is Mandatory.
The document issue date must be less than or equal to the current date.
Buyer name is mandatory for Simplified Tax Invoice and associated credit/debit notes.
DEC-20=[BR-DEC-20] - The allowed maximum number of decimals for the VAT category tax amount (BT-117) is 2.
BR-DEC-13=[BR-DEC-13] - The allowed maximum number of decimals for the Invoice total VAT amount (BT-110) is 2.
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
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 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.
Last updated