# Simplified (B2C) 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. 

## Simplified Invoice Compliance Check

<mark style="color:green;">`POST`</mark> `/api/Simplified-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="124">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">SimplifiedInvoice
SimplifiedaCreditNote
SimplifiedDebitNote
PrePaidSimplifiedInvoice
</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><pre><code>isExport
</code></pre></td><td>string</td><td>Not required in simplified doc</td><td>It is not required or keep false in simplified invoice.</td></tr></tbody></table>

#### &#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><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>

#### Customer

{% hint style="info" %}
Customer details requirement also same as above seller table. But not mandatory for simplified invoices
{% 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>Type</th><th>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": "SimplifiedInvoice", 
         "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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://stackcue.gitbook.io/stackcue-docs/get-started/let-us-integrate-to-zatca/simplified-b2c-compliance-check.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.