# 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

<mark style="color:green;">`POST`</mark> `/api/standard-compliance`

**Headers**

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

**Body**

#### &#x20;stackcue

<table><thead><tr><th width="320">Name</th><th width="102">Type</th><th width="107">Validation</th><th>Description</th></tr></thead><tbody><tr><td><pre><code>documentType
</code></pre></td><td>String</td><td>Required</td><td><p>For standard Invoice, it can have below values</p><pre class="language-postman_json"><code class="lang-postman_json">StandardInvoice
StandardCreditNote
StandardDebitNote
PrePaidStandardInvoice
</code></pre></td></tr><tr><td><pre><code>stackcueComplianceIdentifier
</code></pre></td><td>String</td><td>Required</td><td>Compliance identifier from successful Compliance CSID  API request </td></tr><tr><td><p></p><pre class="language-postman_json"><code class="lang-postman_json">isExport
</code></pre></td><td>boolean</td><td>optional</td><td><p>if goods are for export then  add it as true<br>     <code>"isExport": true</code></p><p>if not included considered as non export.</p></td></tr></tbody></table>

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

#### &#x20;Invoice

<table><thead><tr><th width="276">Name</th><th width="138">Type</th><th>Validation</th><th>Description</th></tr></thead><tbody><tr><td><pre><code>id
</code></pre></td><td>Integer</td><td>Required</td><td>Item line number</td></tr><tr><td><pre><code>issueDate
</code></pre></td><td>String<br>(YYY-MM-DD)</td><td>Required</td><td><p>Example : </p><pre class="language-postman_json"><code class="lang-postman_json">2022-09-07
</code></pre></td></tr><tr><td><pre><code><strong>issueTime
</strong></code></pre></td><td>String<br>(hh:mm:ss)</td><td>Required</td><td><p>Example:</p><pre class="language-postman_json"><code class="lang-postman_json">2:21:28
</code></pre></td></tr><tr><td></td><td></td><td></td><td></td></tr><tr><td><pre><code>invoiceCounterValue
</code></pre></td><td>Integer</td><td>Required</td><td>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.</td></tr><tr><td><pre><code>actualDeliveryDate
</code></pre></td><td>String<br>(YYY-MM-DD)</td><td>Required</td><td><p></p><p>Example : </p><pre class="language-postman_json"><code class="lang-postman_json">2022-09-07
</code></pre></td></tr><tr><td><pre><code>paymentMeansCode
</code></pre></td><td>Integer</td><td>Required</td><td><p>Below values are used based on invoice payment</p><p><br><code>10 In cash</code> </p><p><code>30 Credit</code> </p><p><code>42 Payment to bank account</code> </p><p><code>48 Bank card</code> </p><p><code>1 Instrument not defined (Free text)</code></p></td></tr><tr><td><pre><code>PIHvalue
</code></pre></td><td>String</td><td>Required</td><td><p>Previouse invoice Hash value (PIH) delivered through API response. It should be used in next invoice for the same Production CSID.<br>For very first invoice PIH values is as below<br></p><pre class="language-postman_json"><code class="lang-postman_json">NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==
</code></pre></td></tr><tr><td><pre><code>referanceInvoiceID
</code></pre></td><td>String</td><td>Required only for credit note and debit note</td><td>The referance invoice ID to the original invoice against which credit note and debit note to be issued.</td></tr><tr><td><pre><code>reasonForCreditOrDebitNote
</code></pre></td><td>String</td><td>Required only for credit note and debit note</td><td>The reason for credit note and debit note</td></tr></tbody></table>

#### &#x20;Seller&#x20;

<table><thead><tr><th width="277">Name</th><th width="88">Type</th><th width="111">Validation</th><th></th></tr></thead><tbody><tr><td><pre><code>partyIdentificationId
</code></pre></td><td>String</td><td>Required</td><td>Any id number (Type given below)</td></tr><tr><td><pre><code>partyIdentificationIdType
</code></pre></td><td>String</td><td>Required</td><td><p><code>CRN : Commercial Reg No</code></p><p><code>MOM : MOMRAH License</code><br><code>MLS : MHRSD License</code><br><code>SAG : SAGIA License</code><br><code>OTH : Others</code><br><code>700 : 700 number</code></p></td></tr><tr><td><pre><code>streetName
</code></pre></td><td>String</td><td>Required</td><td>Seller street name</td></tr><tr><td><pre><code>buildingNumber
</code></pre></td><td>String</td><td>Required</td><td>Seller Building Number</td></tr><tr><td><pre><code>citySubdivisionName
</code></pre></td><td>String</td><td>Required</td><td>Sub division city name</td></tr><tr><td><pre><code>cityName
</code></pre></td><td>String</td><td>Required</td><td>City Name</td></tr><tr><td><pre><code>postalZone
</code></pre></td><td>String</td><td>Required</td><td>Postal Code Number</td></tr><tr><td><p></p><pre class="language-postman_json"><code class="lang-postman_json">country
</code></pre></td><td>String</td><td>Required</td><td>Country codes in an invoice MUST be coded using <a href="../../additional-informations/iso-code-list-3166-1-for-countries">ISO code list 3166-1</a></td></tr><tr><td><pre><code>companyID
</code></pre></td><td>String</td><td>Required</td><td>VAT Registration number</td></tr><tr><td><pre><code>registrationName
</code></pre></td><td>String</td><td>Required</td><td>Company Name</td></tr></tbody></table>

**Seller**

{% hint style="info" %}
Customer details requirement also same as above seller table.&#x20;
{% endhint %}

#### Document Charge

<table><thead><tr><th width="320">Name</th><th>Type</th><th>Validation</th><th>Description</th></tr></thead><tbody><tr><td><pre><code>chargeReason
</code></pre></td><td>String</td><td>Required if document level charge exist</td><td>Reason for charge- Document level</td></tr><tr><td><pre><code>chargeAmount
</code></pre></td><td>Number</td><td>Required if document level charge exist</td><td>Charge Amount - Document level</td></tr><tr><td><pre><code>taxCategoryID
</code></pre></td><td>String</td><td>Required if document level charge exist</td><td>Category ID<br>eg: S</td></tr><tr><td><pre><code>taxPercentage
</code></pre></td><td>Number</td><td>Required if document level charge exist</td><td>tax percentage<br>eg: 15</td></tr></tbody></table>

**Document Allowance**

<table><thead><tr><th width="320">Name</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody><tr><td><pre><code>allowanceReason
</code></pre></td><td>String</td><td>Required if document level allowance exist</td><td>Reason for allowance- Document level</td></tr><tr><td><pre><code>allowanceAmount
</code></pre></td><td>Number</td><td>Required if document level allowance exist</td><td>Allowance Amount - Document level</td></tr><tr><td><pre><code>taxCategoryID
</code></pre></td><td>String</td><td>Required if document level allowance exist</td><td>Category ID<br>eg: S</td></tr><tr><td><pre><code>taxPercentage
</code></pre></td><td>Number</td><td>Required if document level allowance exist</td><td>tax percentage<br>eg: 15</td></tr></tbody></table>

#### Prepaid Document

<table><thead><tr><th width="320">Name</th><th>Type</th><th>Validation</th><th>Description</th></tr></thead><tbody><tr><td><pre><code>prePaymentDocumentId
</code></pre></td><td>String</td><td>Required if Invoice amount already paid with another invoice</td><td>Document ID for the prepaid invoice</td></tr><tr><td><pre><code>prePaymentDocumentIssueDate
</code></pre></td><td>String</td><td>Required if Invoice amount already paid with another invoice</td><td>Document issue date for the prepaid invoice</td></tr><tr><td><pre><code>prePaymentDocumentIssueTime
</code></pre></td><td>String</td><td>Required if Invoice amount already paid with another invoice</td><td>Document issue time for the prepaid invoice</td></tr><tr><td><pre><code>prePaymentCategoryAmount
</code></pre></td><td>String</td><td>Required if Invoice amount already paid with another invoice</td><td>The prepaid amount by category wise</td></tr></tbody></table>

#### Line Items

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

#### Examples

{% tabs %}
{% tab title="Sample Request" %}

```json
{
    "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
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Success Response

{% tabs %}
{% tab title="Success" %}

```json
{
    "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": ""
    }
}
```

{% endtab %}
{% endtabs %}

#### Error Response

{% tabs %}
{% tab title="Error" %}

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

{% endtab %}
{% endtabs %}