Standard (B2B) Compliance Check

ZATCA allows to check invoices before actually submit to them. this checking allows to identify if any issues (UBL XML standard) to the generted invoice.

Standard Invoice Compliance Check

POST /api/standard-compliance

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

stackcue

Name	Type	Validation	Description
documentType	String	Required	For standard Invoice, it can have below values StandardInvoice StandardCreditNote StandardDebitNote PrePaidStandardInvoice
stackcueComplianceIdentifier	String	Required	Compliance identifier from successful Compliance CSID API request
isExport	boolean	optional	if goods are for export then add it as true "isExport": true if not included considered as non export.

Note : isExport is applicable only in Standard (B2B) transactions

Invoice

Name	Type	Validation	Description
id	Integer	Required	Item line number
issueDate	String (YYY-MM-DD)	Required	Example : 2022-09-07
issueTime	String (hh:mm:ss)	Required	Example: 2:21:28
invoiceCounterValue	Integer	Required	Counter value of documents. it starts from 1. and increments for every new documents. it can reset and start from 1 for every new Production CSID.
actualDeliveryDate	String (YYY-MM-DD)	Required	Example : 2022-09-07
paymentMeansCode	Integer	Required	Below values are used based on invoice payment 10 In cash 30 Credit 42 Payment to bank account 48 Bank card 1 Instrument not defined (Free text)
PIHvalue	String	Required	Previouse invoice Hash value (PIH) delivered through API response. It should be used in next invoice for the same Production CSID. For very first invoice PIH values is as below NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==
referanceInvoiceID	String	Required only for credit note and debit note	The referance invoice ID to the original invoice against which credit note and debit note to be issued.
reasonForCreditOrDebitNote	String	Required only for credit note and debit note	The reason for credit note and debit note

Seller

Name	Type	Validation
partyIdentificationId	String	Required	Any id number (Type given below)
partyIdentificationIdType	String	Required	CRN : Commercial Reg No MOM : MOMRAH License MLS : MHRSD License SAG : SAGIA License OTH : Others 700 : 700 number
streetName	String	Required	Seller street name
buildingNumber	String	Required	Seller Building Number
citySubdivisionName	String	Required	Sub division city name
cityName	String	Required	City Name
postalZone	String	Required	Postal Code Number
country	String	Required	Country codes in an invoice MUST be coded using ISO code list 3166-1
companyID	String	Required	VAT Registration number
registrationName	String	Required	Company Name

Seller

Customer details requirement also same as above seller table.

Document Charge

Name	Type	Validation	Description
chargeReason	String	Required if document level charge exist	Reason for charge- Document level
chargeAmount	Number	Required if document level charge exist	Charge Amount - Document level
taxCategoryID	String	Required if document level charge exist	Category ID eg: S
taxPercentage	Number	Required if document level charge exist	tax percentage eg: 15

Document Allowance

Name	Type		Description
allowanceReason	String	Required if document level allowance exist	Reason for allowance- Document level
allowanceAmount	Number	Required if document level allowance exist	Allowance Amount - Document level
taxCategoryID	String	Required if document level allowance exist	Category ID eg: S
taxPercentage	Number	Required if document level allowance exist	tax percentage eg: 15

Prepaid Document

Name	Type	Validation	Description
prePaymentDocumentId	String	Required if Invoice amount already paid with another invoice	Document ID for the prepaid invoice
prePaymentDocumentIssueDate	String	Required if Invoice amount already paid with another invoice	Document issue date for the prepaid invoice
prePaymentDocumentIssueTime	String	Required if Invoice amount already paid with another invoice	Document issue time for the prepaid invoice
prePaymentCategoryAmount	String	Required if Invoice amount already paid with another invoice	The prepaid amount by category wise

Line Items

Name	Type	Validation	Description
lineID	Integer	Required	Invoice item line number
invoicedQuantity	Number	Required	Invoiced qty
baseQuantity	Number	Required	Base qty is standard qty of the item.
currency	String	Required	It must be coded with ISO -4217 alpha 3 standard. For Saudi riayls use SAR. For other currencies refer : https://www.six-group.com/en/products-services/financial-information/data-standards.html
name	String	Required	Name of item
categoriesCode	String	Required	Tax category code (S/E/Z/O) For standard tax item use S
vatPercentage	Number	Required	VAT percentage for category S is 15. for E,Z and O it is 0
grossAmount	Number	Required	The standard price of item without any allowance/charge
priceAllowanceReason	String	Required if price allowance exists	Reason if price allowance exists
priceAllowanceAmount	Number	Required if price allowance exists	Price allowance amount if exists
lineAllowanceMethod	String	Required. but will process only when lineAllowanceAmount > 0	Use only percentage or direct
itemlineAllowance_UNE_Reason	String	Required. but will process only when lineAllowanceAmount > 0	Use reason mentioned in https://unece.org/fileadmin/DAM/trade/untdid/d16b/tred/tred5189.htm
lineAllowanceAmount	Number	Required if line allowance exists. otherwise keep 0	Allowance amount to the invoice line
lineAllowancePercentage	Number	Required. but will process only when lineAllowanceAmount > 0	Line allowance percentage
baseAmountForLineAllowance	Number	Required. but will process only when lineAllowanceAmount > 0	The base amount used to calculate allowance
lineChargeMethod	String	Required if lineChargeAmount > 0	se only percentage or direct
itemlineCharge_UNE_Reason	String	Required. but will process only when lineChargeAmount > 0	Use reason mentioned in https://unece.org/fileadmin/DAM/trade/untdid/d16b/tred/tred7161.htm
lineChargeAmount	Number	Required. but will process only when lineChargeAmount > 0	Charge amount to the line
lineChargePercentage	Number	Required. but will process only when lineChargeAmount > 0	Percentage of line charge
baseAmountForLineCharge	Number	Required. but will process only when lineChargeAmount > 0	Base amount used to calculate charge

Examples

Sample Request

{
    "Stackcue": {
        "documentType": "StandardInvoice", 
        "stackcueComplianceIdentifier": "7ba9b14a-a060-4e49-bc58-24af68b47a40",
        "isExport": false
    },
    "Invoice": {
        "id": "SME00061",
        "issueDate": "2022-09-07",
        "issueTime": "12:21:28",
        "invoiceCounterValue": 101,
        "actualDeliveryDate": "2022-09-07",
        "paymentMeansCode": 10,
        "PIHvalue": "NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==",
        "referanceInvoiceID": "SMI00023",
        "reasonForCreditOrDebitNote": "Item Returned"
    },
    "Seller": {
        "partyIdentificationId": "454634645645654",
        "partyIdentificationIdType": "CRN",
        "streetName": "Riyadh",
        "buildingNumber": "2322",
        "plotIdentification": "2223",
        "citySubdivisionName": "Riyad",
        "cityName": "Riyadh",
        "postalZone": "23333",
        "companyID": "399999999900003",
        "registrationName": "Jeeem IT"
    },
    "Customer": {
        "partyIdentificationId": "2345",
        "partyIdentificationIdType": "NAT",
        "streetName": "Riyadh",
        "buildingNumber": "1111",
        "plotIdentification": "2223",
        "citySubdivisionName": "Riyadh",
        "cityName": "Dammam",
        "postalZone": "12222",
        "country": "SA",
        "companyID": "399999999400003",
        "registrationName": "Acme Widgets LTD 2"
    },
    "DocumentAllowances": [
        {
            "allowanceReason": "Free Text for allowance",
            "allowanceAmount": 1,
            "taxCategoryID": "S",
            "taxPercentage": 15
        }
    ],
    "DocumentCharges": [
        {
            "chargeReason": "Advertising",
            "chargeAmount": 10,
            "taxCategoryID": "S",
            "taxPercentage": 15
        }
    ],
    "prePaidDocuments": [
        {
            "prePaymentDocumentId": "123",
            "prePaymentDocumentIssueDate": "2021-07-31",
            "prePaymentDocumentIssueTime": "12:28:17",
            "prePaymentCategoryAmount": {
                "S": 2,
                "E": 0,
                "Z": 0,
                "O": 0
            }
        },
        {
            "prePaymentDocumentId": "124",
            "prePaymentDocumentIssueDate": "2021-07-31",
            "prePaymentDocumentIssueTime": "12:28:17",
            "prePaymentCategoryAmount": {
                "S": 1,
                "E": 0,
                "Z": 0,
                "O": 0
            }
        }
    ],
    "Lineitems": [
        {
            "lineID": 1,
            "invoicedQuantity": 1,
            "invoicedQuantityUnit": "Pce",
            "baseQuantity": 1000,
            "currency": "SAR",
            "name": "Juice",
            "categoriesCode": "S",
            "vatPercentage": 15,
            "grossAmount": 10,
            "priceAllowanceReason": "FREETEXT",
            "priceAllowanceAmount": 1,
            "lineAllowanceMethod": "percentage",
            "itemlineAllowance_UNE_Reason": "Discount",
            "lineAllowanceAmount": 1,
            "lineAllowancePercentage": 10,
            "baseAmountForLineAllowance": 11,
            "lineChargeMethod": "percentage",
            "itemlineCharge_UNE_Reason": "Advertising",
            "lineChargeAmount": 1,
            "lineChargePercentage": 10,
            "baseAmountForLineCharge": 11
        }
    ]
}

Success Response

Success

{
    "zatcaResponse": {
        "validationResults": {
            "infoMessages": [
                {
                    "type": "INFO",
                    "code": "XSD_ZATCA_VALID",
                    "category": "XSD validation",
                    "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                    "status": "PASS"
                }
            ],
            "warningMessages": [],
            "errorMessages": [],
            "status": "PASS"
        },
        "reportingStatus": null,
        "clearanceStatus": "CLEARED",
        "qrSellertStatus": null,
        "qrBuyertStatus": null
    },
    "stackcueHelper": {
        "overallStatus": 1,
        "ublStatus": 1,
        "zatcaSubmissionStatus": 1,
        "isZatcaServerUp": true,
        "countRedirections": 1,
        "totalTaxableAmount": "9.01",
        "totalTaxAmount": "1.35",
        "hash": "LGIekRDtFYwRBlX75pgpZsRrKrwW66Ms+i6fotpqrX4=",
        "xmlFileName": "399999999900003_20220907T122128_2022-09-07-SME00061",
        "phase2QR": "",
        "simplifiedDocXML": ""
    }
}

Error Response

Error

{
    "zatcaResponse": {
        "validationResults": {
            "infoMessages": [
                {
                    "type": "INFO",
                    "code": "XSD_ZATCA_VALID",
                    "category": "XSD validation",
                    "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                    "status": "PASS"
                }
            ],
            "warningMessages": [],
            "errorMessages": [
                {
                    "type": "ERROR",
                    "code": "BR-CL-03",
                    "category": "EN_16931",
                    "message": "currencyID MUST be coded using ISO code list 4217 alpha-3",
                    "status": "ERROR"
                },
                {
                    "type": "ERROR",
                    "code": "BR-KSA-CL-02",
                    "category": "KSA",
                    "message": "All currencyID attributes (BT-5) must have the same value as the invoice currency code (BT-5), except for the invoice total VAT amount in accounting currency (BT-111).",
                    "status": "ERROR"
                }
            ],
            "status": "ERROR"
        },
        "reportingStatus": null,
        "clearanceStatus": "NOT_CLEARED",
        "qrSellertStatus": null,
        "qrBuyertStatus": null
    },
    "stackcueHelper": {
        "overallStatus": 0,
        "ublStatus": 1,
        "zatcaSubmissionStatus": 0,
        "isZatcaServerUp": true,
        "countRedirections": "",
        "totalTaxableAmount": "9.11",
        "totalTaxAmount": "1.37",
        "hash": "CvzM3l+F6T6mXFaOlNiu8V3ynuM8C6ohRn2TsESsIY4=",
        "xmlFileName": "399999999900003_20220907T122128_2022-09-07-SME00061",
        "phase2QR": "",
        "simplifiedDocXML": null
    }
}