# Generate e-Invoice (Synchronous)

### Request Method

POST

### Request URL

```
{{BASE_URL}}/api/EInvoice/Generate
```

{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](/e-invoicing-ksa-api.md) based on whether you are using sandbox or production.
{% endhint %}

### **Request Authorization**

<table><thead><tr><th width="137">Key</th><th width="136">Data Type</th><th width="206">Validations and Example</th><th>Description</th></tr></thead><tbody><tr><td>Bearer token</td><td>String</td><td>Cannot be empty.</td><td>Mandatory.</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="243.33333333333334">Parameter</th><th width="106">Data Type</th><th width="188">Validations and Example</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>String</td><td>INV-00002</td><td>Mandatory. invoice number</td></tr><tr><td>DeviceID</td><td>string</td><td>0059BA36-50EF-4183-A127-4D867738EF74</td><td>Mandatory. GUID appears at the time of onboarding</td></tr><tr><td><a href="#invoicetype-object">InvoiceType</a></td><td>object</td><td></td><td>Mandatory</td></tr><tr><td>VATNumber</td><td>string</td><td>3xxxxxxxxxxxxx3</td><td>Mandatory</td></tr><tr><td>VAT_Percent</td><td>decimal</td><td>15</td><td>Mandatory</td></tr><tr><td>DeliveryDate</td><td>string</td><td>"2024-11-30"</td><td>conditional. required only for B2B</td></tr><tr><td>BillingReference</td><td>string</td><td>INV-00001</td><td>conditional. IF InvoiceTypeCode is 381 AND 383 Then Requried </td></tr><tr><td><a href="#payment-means-object">PaymentMeans</a></td><td>object</td><td></td><td>conditional. IF InvoiceTypeCode is 381 AND 383 Then Requried </td></tr><tr><td>IssueDate</td><td>string</td><td>"2024-11-29"</td><td>Mandatory</td></tr><tr><td>IssueTime</td><td>string</td><td>"19:04:50"</td><td>Mandatory</td></tr><tr><td><a href="#buyer-object">BUYER</a></td><td>object</td><td></td><td>conditional. required only for B2B</td></tr><tr><td><a href="#invoice-line-object">InvoiceLine</a></td><td>object</td><td></td><td>Mandatory</td></tr><tr><td>AllowanceCharge</td><td>decimal</td><td>0.00</td><td>Mandatory</td></tr></tbody></table>

#### Invoice Type Object

<table><thead><tr><th width="281.33333333333337">Parameter</th><th width="105">Data Type</th><th>Validations and Example</th><th>Description</th></tr></thead><tbody><tr><td>InvoiceTypeCode</td><td>string</td><td>388, 381, 383</td><td>Mandatory. 388 for invoice, 381 for credit note, 383 for debit note</td></tr><tr><td>InvoiceTypeName</td><td>String</td><td>0100000, 0200000</td><td>Mandatory. 0100000 for B2B, 0200000 for B2C.</td></tr></tbody></table>

#### **Payment Means Object**

<table><thead><tr><th>Parameter</th><th>Data Type</th><th width="187">Validations and Example</th><th>Description</th></tr></thead><tbody><tr><td>paymentMeansCode</td><td>String</td><td>10</td><td><p>Mandatory. The means, expressed as code, for how a payment is expected to be or has been settled.</p><p>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.</p><p>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) .</p><p>In the simplified tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02) this value is optional.</p></td></tr><tr><td>paymentNote</td><td>String</td><td>free text</td><td>Mandatory.</td></tr><tr><td>instructionNote</td><td>string</td><td>free text</td><td>Mandatory</td></tr></tbody></table>

#### **BUYER Object**

| Parameter                | Data Type | Example           | Description                                                                          |
| ------------------------ | --------- | ----------------- | ------------------------------------------------------------------------------------ |
| BUYERNAME                | String    | Saudi Arabian Co. | Mandatory                                                                            |
| BUYERTYPE                | String    | B2B, B2C          | Mandatory                                                                            |
| BUYER\_VAT               | String    | 3xxxxxxxxxxxx3    | Conditional. Required when PartyIdentification & PartyIdentificationValue is missing |
| TAX\_SCHEME              | String    | VAT               | Mandatory                                                                            |
| PARTYIDENTIFICATION      | String    | CRN               | Conditional. Required when Buyer\_VAT is missing                                     |
| BUILDINGNUMBER           | String    | 1234              | Mandatory. must be 4 digits                                                          |
| CITYSUBDIVISIONNAME      | String    | Jeddah            | Mandatory                                                                            |
| CITY                     | String    | Jeddah            | Mandatory                                                                            |
| POSTALZONE               | String    | 12345             | Mandatory. must be 5 digits                                                          |
| COUNTRYSUBENTITY         | String    | saudi arabia      | mandatory                                                                            |
| COUNTRYCODE              | String    | SA                | mandatory                                                                            |
| PARTYIDENTIFICATIONVALUE | String    | 1234567890        | Conditional. Required when Buyer\_VAT is missing                                     |

### Invoice Line **Object**

| Parameter              | Data Type | Example          | Description                                       |
| ---------------------- | --------- | ---------------- | ------------------------------------------------- |
| Name                   | string    | Item 1           | Mandatory                                         |
| Price                  | decimal   | 100.00           | Mandatory                                         |
| InvoicedQuantity       | int       | 2                | Mandatory                                         |
| ItemTaxCategory        | string    | S,Z,E,O          | Mandatory                                         |
| UnitOfMeasure          | string    | each             | Mandatory                                         |
| TaxExemptionReasonCode | string    | VATEX-SA-32      | conditional. required if ItemTaxCategory is Z,E,O |
| TaxExemptionReason     | string    | exports of goods | conditional. required if ItemTaxCategory is Z,E,O |

### Sample Request

```json
{
    "ID": "INV-00001",
    "InvoiceType": {
        "InvoiceTypeCode": "388",
        "InvoiceTypeName": "0100000"
    },
    "VATNumber": "3xxxxxxxxxxxxx3",
    "DeviceId": "28f33520-2fcb-6ace-94e2-6e61dbcc1932",
    "VAT_Percent": 15,
    "DELIVERYDATE": "2024-11-30",
    "BILLINGREFERENCE": "510324",
    "PAYMENTMEANS": {
        "PAYMENTMEANSCODE": "10",
        "PAYMENTNOTE": "",
        "INSTRUCTIONNOTE": ""
    },
    "IssueDate": "2024-11-29",
    "IssueTime": "19:04:50",
    "BUYER": {
        "BUYERNAME": "SAUDI ARABIAN COMPANY",
        "BUYERTYPE": "B2B",
        "BUYER_VAT": "3xxxxxxxxxxxxx3",
        "TAX_SCHEME": "VAT",
        "PARTYIDENTIFICATION": "CRN",
        "PARTYIDENTIFICATIONVALUE": "1234567890",
        "STREETNAME": "شارع الجادة الشرقية",
        "BUILDINGNUMBER": "4297",
        "CITYSUBDIVISIONNAME": "حي الظهران الغربي",
        "CITY": "الظهران",
        "POSTALZONE": "34465",
        "COUNTRYSUBENTITY": "المنطقة الشرقية",
        "COUNTRYCODE": "SA"
    },
    "InvoiceLine": [
        {
            "Name": "ST04 - Fresh Air Duct",
            "Price": 32.00,
            "InvoicedQuantity": 4,
            "ItemTaxCategory": "S",
            "UnitOfMeasure": "EA",
            "TaxExemptionReasonCode": "",
            "TaxExemptionReason": ""
        },
        {
            "Name": "test for zero rated",
            "Price": 100.00,
            "InvoicedQuantity": 5,
            "ItemTaxCategory": "Z",
            "UnitOfMeasure": "EA",
            "TaxExemptionReasonCode": "VATEX-SA-32",
            "TaxExemptionReason": "Export of goods"
        },
        {
            "Name": "ST05 - Fresh Air Duct",
            "Price": 62.00,
            "InvoicedQuantity": 2,
            "ItemTaxCategory": "E",
            "UnitOfMeasure": "EA",
            "TaxExemptionReasonCode": "VATEX-SA-29",
            "TaxExemptionReason": "Financial services mentioned in Article 29 of the VAT Regulations"
        },
        {
            "Name": "ST06 - Fresh Air Duct",
            "Price": 63.33,
            "InvoicedQuantity": 4,
            "ItemTaxCategory": "O",
            "UnitOfMeasure": "EA",
            "TaxExemptionReasonCode": "VATEX-SA-OOS",
            "TaxExemptionReason": "Reason is free text, to be provided by the taxpayer on case to case basis."
        }
    ],
    "AllowanceCharge": 0.00
}
```

### Response Status Codes

| HTTP Status Code | Description                                                                  |
| ---------------- | ---------------------------------------------------------------------------- |
| 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

| Parameter | Datatype | Description        |
| --------- | -------- | ------------------ |
| status    | int      | status code        |
| response  | object   |                    |
| message   | string   | success or failure |

### Response object

| Parameter       | Data Type | Description                                                                                                                                                                                                                                       |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DeviceId        | String    | Mandatory                                                                                                                                                                                                                                         |
| Status          | String    | Mandatory. Status of E-Invoice QR Code Generation and acceptance by ZATCA. Explained below.                                                                                                                                                       |
| QrCodeStatus    | String    | <p>Mandatory. Status of E-Invoice QR Code.</p><p></p><p>GENERATED, NOT\_GENERATED, GENERATION\_FAILED</p>                                                                                                                                         |
| InvoiceStatus   | String    | <p>Mandatory. Status of submission to ZATCA.</p><p>NOT\_SUBMITTED, FAILED NOT\_REPORTED, REPORTED, CLEARED, NOT\_CLEARED ACCEPTED\_WITH\_WARNING,</p><p>PENDING</p>                                                                               |
| QRCode          | String    | <p>Optional. Rendered QR Code image in base64encoded PNG format.</p><p>If clearance fails, this will be null.</p>                                                                                                                                 |
| RawQRCode       | String    | <p>Optional. QR Code payload in base64encoded TLV format.</p><p>For reporting, this will be generated by ClearTax, if not received in the input.</p><p>For clearance, this will be generated by ZATCA. If clearance fails, this will be null.</p> |
| InvoiceXml      | String    | <p>Optional. In case of Standard invoices, XML returned by ZATCA.</p><p>In case of Simplified invoices, XML used for reporting.</p>                                                                                                               |
| UUID            | String    | <p>Optional. UUID sent to ZATCA</p><p>Evs Engine generates this before sending to ZATCA, if not sent in input.</p>                                                                                                                                |
| 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    | <p>Optional. Invoice hash value,</p><p>Hash value of current invoice xml by removing tags ext:UBLExtensions, cac:AdditionalDocumentReference:QRCode</p>                                                                                           |
| InvoiceType     | String    | <p>Mandatory. Document Type. <br>INV - Invoice, <br>CRN - Credit Note,<br>DBN - Debit Note.</p>                                                                                                                                                   |
| 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](broken://pages/F1C21JYW5nzbGO0ILOrR). In case there are no errors, this will be an empty Array (\[]).                                                                            |
| WarningList     | Array     | Optional. Warnings from ZATCA. An array of [Error Details Objects](broken://pages/F1C21JYW5nzbGO0ILOrR). In case there are no warnings, this will be an empty Array (\[]).                                                                        |
| Message         | String    | Optional. Message received from ZATCA.                                                                                                                                                                                                            |

**Error List object**

| Parameter    | Data Type | Description                                                           |
| ------------ | --------- | --------------------------------------------------------------------- |
| ErrorCode    | String    | <p>100401-Authentication Failed,<br>100403 = Authorization Failed</p> |
| ErrorMessage | String    | Mandatory. Human readable error message.                              |
| ErrorSource  | String    | EVS\_Engine                                                           |

**Warning List object**

| Parameter    | Data Type | Description                                                           |
| ------------ | --------- | --------------------------------------------------------------------- |
| ErrorCode    | String    | <p>100401-Authentication Failed,<br>100403 = Authorization Failed</p> |
| ErrorMessage | String    | Mandatory. Human readable error message.                              |
| ErrorSource  | String    | EVS\_Engine                                                           |

### Sample Response

Success - HTTP Status Code - 200

```json5
{
    "status": 200,
    "response": {
        "deviceId": "28f33520-2fcb-4ace-93e2-6e61dbcc5939",
        "status": "GENERATED",
        "qrCodeStatus": "GENERATED",
        "invoiceStatus": "REPORTED",
        "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhE..",
        "rawQRCode": "ARNFdmluY2libGUgU2..",
        "invoiceXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBl",
        "uuid": "f713c0dd-87bf-4935-88c9-2284137e074c",
        "icv": "35",
        "pih": "rp2AXhdXjl9T79S3cUSnJFLKrp6AcNcY0y0T4=",
        "invoiceHash": "WKvutQo3ExeBNLGVfgFvOxZVrGIlXibqBc6LW=",
        "invoiceType": "INV",
        "invoiceNumber": "INV-00001",
        "issueDate": "2024-11-29",
        "issueTime": "19:04:50",
        "generatedDate": "1/9/2025",
        "generatedTime": "10:29:36",
        "sellerVatNumber": "3xxxxxxxxxxxxx3",
        "buyerVatNumber": "3xxxxxxxxxxxxx3",
        "errorList": [],
        "warningList": [],
        "message": null
    },
    "message": "Success"
}
```

Error - HTTP Status Code - 400

```json
{
    "status": 400,
    "response": {
        "deviceId": "28f33520-2fcb-4ace-93e2-6e61dbcc5939",
        "status": "NOT_GENERATED",
        "qrCodeStatus": "NOT_GENERATED",
        "invoiceStatus": "NOT_CLEARED",
        "qrCode": null,
        "rawQRCode": null,
        "invoiceXml": null,
        "uuid": "d2d20562-9ccb-44d1-803d-52eed2c03e7e",
        "icv": null,
        "pih": "NhhgziDqKvmfawWAY9kaf0vCvR1gUvygDQMIEt=",
        "invoiceHash": "bLabqwQgB1itO0P7ttA+w7JEU6Su6P0kRmz18=",
        "invoiceType": "INV",
        "invoiceNumber": "INV-00034",
        "issueDate": "1/9/2025",
        "issueTime": "10:47:18",
        "generatedDate": null,
        "generatedTime": null,
        "sellerVatNumber": "3xxxxxxxxxxxxx3",
        "buyerVatNumber": "3xxxxxxxxxxxxx3",
        "errorList": [
            {
                "errorCode": "certificate-permissions",
                "errorMessage": "Production CSID does not cover Standard documents",
                "errorSource": "CERTIFICATE_ERRORS"
            }
        ],
        "warningList": [
            {
                "errorCode": "BR-KSA-15",
                "errorMessage": "The tax invoice ((invoice type code (BT-30) = 388) & (invoice transaction code (KSA-2) has “01” as first 2 digits)) must contain the supply date (KSA-5).",
                "errorSource": "KSA"
            }
        ],
        "message": null
    },
    "message": "Failure"
}
```

Error - HTTP Status Code - 401

```json
{
    "status": 401,
    "respose": "Authentication Failed",
    "message": "EVS_Portal"
}
```

Error - HTTP Status Code - 403

```json
{
    "status": 409,
    "response": "Invoice Number already Exist",
    "message": "Status with REPORTED"
}
```

### API Validations

1. The token you generated from the token API it should place in authorisation token as a bearer token


---

# 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://zatcaportalapidocs.evinciblesolutions.com/reference/api-reference-version-ii/generate-e-invoice-synchronous.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.