# Get Invoice

Get the e-Invoice details for any invoice present in ClearTax database using unique identifiers or concatenation of unique identifiers.

### **Request Method**

GET

### **Request URL**

```
{{BASE_URL}}/v2/einvoices/data
```

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

{% hint style="danger" %}
Rate Limit : 1000 API requests per minute
{% endhint %}

### **Request Headers**

<table><thead><tr><th width="171">Parameters</th><th width="132">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>x-cleartax-auth-token</td><td>String</td><td>Cannot be empty</td><td>Mandatory. User auth token.</td></tr><tr><td>vat</td><td>String</td><td>Cannot be empty</td><td>Mandatory. User auth token.</td></tr><tr><td>branch</td><td>String</td><td>Should be a valid branch from the user account.</td><td>Optional. Branch name (store name) added in the user account which maps to a VAT or Group VAT of the entity.</td></tr></tbody></table>

### **Request Path Params**

There are no path parameters for this API.

### **Request Query Params**

<table><thead><tr><th width="175">Parameters</th><th width="135">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>uniqueId</td><td>String</td><td>Should be present if 4 parameters are absent.</td><td>Conditional.Concat of seller vat + invoice id + invoice type code + issue date. All these entities are separated by underscore.<br></td></tr><tr><td>invoiceNumber</td><td>String</td><td>NA</td><td>Conditional. Document Number (Invoice Reference Number).</td></tr><tr><td>invoiceType</td><td>String</td><td>Enum: INV, CRN, DBN, RECEIPT</td><td>Conditional. INV - Invoice, CRN - Credit Note, DBN - Debit Note, RECEIPT - Receipt</td></tr><tr><td>issueDate</td><td>String</td><td>yyyy-mm-dd</td><td>Conditional. Document Date</td></tr><tr><td>vat</td><td>String</td><td>NA</td><td>Conditional. VAT Number.</td></tr></tbody></table>

### **Request Body**

**Sample Request**

```
https://api-sandbox.cleartax.com/middle-east/ksa/einvoicing/v2/einvoices/data?invoiceNumber=A0108211%2F01&invoiceType=INV&vat=300459805100003&issueDate=2021-11-12
```

### **Response Status Codes**

| HTTP Status Code | Description                                         |
| ---------------- | --------------------------------------------------- |
| 200              | For successful retrieval.                           |
| 401              | If the user is not authenticated for the operation. |
| 403              | If the user is not authorized for the operation.    |
| 429              | Too many requests                                   |
| 5XX              | Unhandled exception.                                |

### **Response Schema**

<table><thead><tr><th width="176">Parameter</th><th width="141">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>DeviceId</td><td>String</td><td>MaxLength: 36</td><td>Optional. Device ID used to generate invoices.</td></tr><tr><td>Status</td><td>String</td><td>Enum:GENERATED,NOT_GENERATED,GENERATION_FAILED,<br>IN_PROGRESS</td><td><p>Mandatory. Status of E-Invoice QR Code. This is the same as QrCodeStatus below. Provided only for backward compatibility for Phase I API.</p><p>IN_PROGRESS, NOT_GENERATED, GENERATION_FAILED</p></td></tr><tr><td>QrCodeStatus</td><td>String</td><td>Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED</td><td><p>Mandatory. Status of E-Invoice QR Code.</p><p>GENERATED, NOT_GENERATED, GENERATION_FAILED</p></td></tr><tr><td>InvoiceStatus</td><td>String</td><td>Enum: NOT_SUBMITTED,              FAILED, NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED, ACCEPTED_WITH_WARNING, PENDING, DISCARDED</td><td><p>Mandatory. Status of submission to ZATCA.</p><p>NOT_SUBMITTED</p></td></tr><tr><td>QRCode</td><td>String</td><td></td><td><p>Optional. Rendered QR Code image in base64 encoded PNG format.</p><p>If clearance fails, this will be null.</p></td></tr><tr><td>RawQRCode</td><td>String</td><td></td><td><p>Optional. QR Code payload in base64 encoded TLV format.</p><p>For reporting, this will be generated by ClearTax. Except when complete XML is generated by ERP and sent in the input.</p><p>For clearance, this will be generated by ZATCA. If clearance fails, this will be null.</p></td></tr><tr><td>InvoiceXml</td><td>String</td><td></td><td><p>Optional. In the case of Standard invoices, the XML is returned by ZATCA.</p><p>In the case of Simplified invoices, it is the XML used for reporting.</p></td></tr><tr><td>UUID</td><td>String</td><td></td><td><p>Optional. UUID sent to ZATCA</p><p>ClearTax generates this before sending to ZATCA, if not sent in input.</p></td></tr><tr><td>ICV</td><td>String</td><td></td><td>Optional. Invoice counter value sent to ZATCA<br>ClearTax generates this before sending it to ZATCA.<br></td></tr><tr><td>PIH</td><td>String</td><td></td><td>Optional. Previous hash value, Invoice hash value of previous invoice reported/cleared for same deviceId.</td></tr><tr><td>InvoiceHash</td><td>String</td><td></td><td><p>Optional. Current invoice hash.</p><p>Hash value of current invoice xml by removing tags <a href="ext:UBLExtensions">ext:UBLExtensions</a>, <a href="cac:AdditionalDocumentReference:QRCode">cac:AdditionalDocumentReference:QRCode</a></p></td></tr><tr><td>InvoiceType</td><td>String</td><td>Enum: INV, CRN, DBN</td><td><p>Mandatory.</p><p>Document Type: INV-INVOICE, CRN-CREDIT NOTE, DBN-DEBIT NOTE.</p></td></tr><tr><td>InvoiceNumber</td><td>String</td><td>Cannot be null</td><td>Mandatory. Invoice number (ID) as per the input.</td></tr><tr><td>IssueDate</td><td>String</td><td>Cannot be null</td><td>Mandatory. Issue Date as per the input.<br></td></tr><tr><td>IssueTime</td><td>String</td><td>Format: HH:mm:ss (24 hr format)</td><td>Mandatory. Invoice issue time. The time when the invoice was issued.</td></tr><tr><td>GeneratedDate</td><td>String</td><td>Cannot be null</td><td>Mandatory. Date on which the invoice is generated.</td></tr><tr><td>GeneratedTime</td><td>String</td><td>Format: HH:mm:ss (24 hr format)</td><td>Mandatory. Invoice generation time. The time when the invoice is generated.</td></tr><tr><td>SellerVatNumber</td><td>String</td><td>Cannot be null</td><td>Mandatory. Seller VAT identification number.</td></tr><tr><td>BuyerVatNumber</td><td>String</td><td>Cannot be null</td><td>Optional. Buyer VAT identification number.</td></tr><tr><td>ErrorList</td><td>Array&#x3C;Error Detail></td><td>Error details from zatca</td><td>Optional.Error list from zatca (6.8.1)</td></tr><tr><td>Message</td><td>String</td><td>NA</td><td>Optional.Message received from zatca<br></td></tr></tbody></table>

#### **Error Details Object**

<table><thead><tr><th width="167">Parameters</th><th width="151">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>ErrorCode</td><td>String</td><td>Cannot be null</td><td>A code to identify the error. Error codes are published above.</td></tr><tr><td>ErrorMessage</td><td>String</td><td>Cannot be null</td><td>Human readable error message.</td></tr><tr><td>ErrorSource</td><td>String</td><td>ZATCA, CLEARTAX</td><td>Source of the error.</td></tr><tr><td>Path</td><td>String</td><td>-</td><td>If it is a validation error of a request data, it will point to the request data field. Example below.</td></tr></tbody></table>

### **Sample Response**

Success for Simplified Document - HTTP Status Code - 200

```json
{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "REPORTED",
    "QRCode": "MjAsSIy1….",
    "RawQRCode": "ARlBb….",
    "InvoiceXml": "ASsdfkf...",
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "13:26:45",
    "GeneratedDate": "2022-10-23",
    "GeneratedTime": "12:26:45",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [],
    "WarningList":[],
    "Message": null
}
```

Success for Standard Document - HTTP Status Code - 200

```json
{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "CLEARED",
    "QRCode": "iBU5ul8ZaHcbmWYy3zL.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXB.......",
    "InvoiceXml": "PD94PC....",
    "UUID": "ed7d6a63-e650-425d-b1eb-f54187a0ccca",
    "ICV": "62",
    "PIH": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceHash": "u+zU7f/JDKpjoKrNUMF5Z3Kho3cqb1VUoNSCIphyZu8=",
    "InvoiceType": "INV",
    "InvoiceNumber": "130",
    "IssueDate": "2021-04-25",
    "IssueTime": "13:26:45",
    "GeneratedDate": "2022-10-23",
    "GeneratedTime": "12:26:45",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList":[],
    "WarningList": [],
    "Message": null
}
```

Success with Warning - HTTP Status Code - 200

```json
{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "ACCEPTED_WITH_WARNING",
    "QRCode": "i+GdAUnzMJS.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
    "InvoiceXml": "ASsdfkf...",
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "13:26:45",
    "GeneratedDate": "2022-10-23",
    "GeneratedTime": "12:26:45",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [],
    "WarningList": [
        {
            "ErrorCode": "BR-KSA-09",
            "ErrorMessage": "Seller address must contain additional number (KSA-23), street name (BT-35), building number (KSA-17), postal code (BT-38), city (BT-37), Neighborhood (KSA-3), country code (BT-40). \n  For more information please access this link: https://www.address.gov.sa/en/address-format/overview",
            "ErrorSource": "ZATCA"
        }
    ],
   "Message": null
}
```

Error from ClearTax - HTTP Status Code - 400

```json
{
    "InvoiceType": "INV",
    "InvoiceNumber": "2022",
    "IssueDate": "2021-04-25",
    "IssueTime": "14:34:45",
    "SellerVatNumber": "300492946900003",
    "Status": "GENERATION_FAILED",
    "QrCodeStatus": "GENERATION_FAILED",
    "InvoiceStatus": "FAILED",
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "If Supplier Group Vat number is provided, scheme id must be HQ",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.AccountingSupplierParty.Party.PartyIdentification.ID.schemeID"
        },
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Payment means code in an invoice must contain one of the values (10, 30, 42, 48, 1). In the simplified tax invoice and associated credit notes and debit notes this value is optional.",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.PaymentMeans.PaymentMeansCode"
        }
    ],
}
```

Error from ZATCA - HTTP Status Code - 200 (Sample Simplified invoice where QR code is generated by ClearTax and then sent to ZATCA for reporting which is not approved by ZATCA).

{% hint style="info" %}
Note: In case a document is validated by ClearTax but failed at ZATCA, then the HTTP Status Code will be 200 and not 400.
{% endhint %}

```json
{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "NOT_REPORTED",
    "QRCode": "i+GdAUnzMJS.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
    "InvoiceXml": null,
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "13:43:34",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [
        {
            "ErrorCode": "Invalid-Invoice-Hash",
            "ErrorMessage": "The provided invoice hash is invalid",
            "ErrorSource": "ZATCA"
        }
    ],
    "WarningList": [],
    "Message": null
}
```

Error from ZATCA - Sample Standard invoice with multiple errors which is not approved by Zatca and hence the InvoiceStatus will be "NOT\_CLEARED" and QrCodeStatus will be "NOT\_GENERATED".

```json
{
    "DeviceId": "09569f97-dd87-4b50-b226-a644b0cb0ab8",
    "Status": "NOT_GENERATED",
    "QrCodeStatus": "NOT_GENERATED",
    "InvoiceStatus": "NOT_CLEARED",
    "QRCode": null,
    "RawQRCode": null,
    "InvoiceXml": null,
    "UUID": "e6791446-844d-4fd1-b4d3-1ae2d111abf8",
    "ICV": "36",
    "PIH": "a+ae0fY+MBboXiFPkZicCIF8ceL2sEnU/fBeQpWEPP4=",
    "InvoiceHash": "+EYiXktJtVeAEqitiJBxNGlO9Hm29/r8l21Z8LGTbCQ=",
    "InvoiceType": "INV",
    "InvoiceNumber": "S-INV-0004",
    "IssueDate": "2022-06-23",
    "IssueTime": "13:43:34",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": "300526201800003",
    "ErrorList": [
        {
            "ErrorCode": "BR-CO-15",
            "ErrorMessage": "Invoice total amount with VAT (BT-112) ",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-20",
            "ErrorMessage": "The allowed maximum number of decimals for the VAT category tax amount (BT-117) is 2.",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-13",
            "ErrorMessage": "The allowed maximum number of decimals for the Invoice total VAT amount (BT-110) is 2.-BR-DEC-15",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-14",
            "ErrorMessage": "The allowed maximum number of decimals for the Invoice total amount with VAT (BT-112) is 2.",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-CO-14",
            "ErrorMessage": "Invoice total VAT amount (BT-110) ",
            "ErrorSource": "ZATCA"
        },
        {
            "ErrorCode": "BR-DEC-18",
            "ErrorMessage": "The allowed maximum number of decimals for the Amount due for payment (BT-115) is 2.",
            "ErrorSource": "ZATCA"
        }
    ],
    "WarningList": [],
    "Message": null
}
```

### **API Validations**

1. The uniqueIdentifier passed in request params should be valid and must be present in ClearTax datastore.
2. 4 fields passed should belong to the user.

### **API Constraints**

1. 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.
2. Each customer is allowed to send a limited number of requests per minute to prevent server overload. If the limit is exceeded, the server will respond with a 429 Too Many Requests status code.
3. Taxpayers can request details of only one invoice per request.
4. The API will only return details of those invoices present in the ClearTax data store.