Optional: default is both OFFLINE and ONLINE
Conditional.
Concat of seller vat + invoice id + invoice type code + issue year. All these entities are separated by underscore.
Either unique id or invoice details are required to fetch the details.
| | invoiceNumber | String | NA | Conditional. Document Number (Invoice Reference Number). | | invoiceType | String | Enum: INV, CRN, DBN | Conditional. INV - Invoice, CRN - Credit Note, DBN - Debit Note | | issueDate | String | yyyy-mm-dd | Conditional. Document Date | | vat | String | NA | Conditional. VAT Number. | ### Sample Request Request Body (Without MethodOfGeneration) ```json { "Invoices": [ { "invoiceNumber": "RR-INV-0001", "invoiceType": "INV", "issueDate": "2022-08-13", "vat": "12345678901234" }, { "uniqueId": "12345678901234_RR-INV-0002_388_2022" }, { "uniqueId": "12345678901234_RR-INV-0013_388_2022" } ] } ``` Request Body (With MethodOfGeneration) Method of generation is an optional field but giving this will help in querying and fetching the details of the invoices faster. ```json { "Invoices": [ { "invoiceNumber": "RR-INV-0001", "invoiceType": "INV", "issueDate": "2022-08-13", "vat": "12345678901234" }, { "uniqueId": "12345678901234_RR-INV-0002_388_2022" }, { "uniqueId": "12345678901234_RR-INV-0013_388_2022" } ], "methodOfGeneration": "ONLINE" } ``` ### 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 | Parameter | Data Type | Field Validations | Description | | -------------- | --------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | invoiceNumber | String | Cannot be null |Mandatory.
Invoice number (ID) as per the input.
| | einvoiceStatus | Object |PENDING / REPORTED / NOT\_REPORTED / ACCEPTED\_WITH\_WARNING /
CLEARED /
NOT\_CLEARED
|For clearance: CLEARED, NOT\_CLEARED, ACCEPTED\_WITH\_WARNING
For reported: REPORTED, NOT\_REPORTED, ACCEPTED\_WITH\_WARNING
| | errorCode | String | Can be empty in case of no error | This field is not empty in case of any error at the time of reporting/clearance. Gives the error code for the error. Error source maybe ClearTax/ZATCA. | | errorMessage | String | Can be empty in case of no error | Human readable error message in case of any error at the time of reporting/clearance. Error source maybe ClearTax/ZATCA. | ### Sample Response (Success) Success - HTTP Status Code - 200 ```json [ { "invoiceNumber": "INVKSA2218811366", "einvoiceStatus": "CLEARED", "errorCode": "", "errorMessage": "" } ] ``` ```json [ { { "invoiceNumber": "13", "einvoiceStatus": "NOT_REPORTED" "errorCode": "BR-KSA-17, BR-CO-15", "errorMessage": "Debit and credit note (invoice type code (BT-3) is equal to 383 or 381) must contain the reason (KSA-10) for this invoice type issuing., Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).", } } ] ``` ### Sample Response (Error) ```json [ { "invoiceNumber": "RR-INV-0001", "einvoiceStatus": "FAILED", "errorCode": "300102", "errorMessage": "You don't have any data present for the selected Document Details" } ] ``` ### API Validations 1. The uniqueIdentifier passed in request params should be valid and must be present in ClearTax datastore. 2. Four invoice info fields passed to identify the invoice or the UniqueId 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. The API will accept only 500 invoices in a single request and the API will allow 10 threads running parallel. Hence, data for 5000 invoices can be requested in parallel. 4. The API works for only those invoices present in the CT data store. 5. Plan this API call 1 hour after sending the invoice to ClearTax. If the invoice is still in pending status then plan the subsequent calls 2, 4, 8, 16 and 30 hours. The invoice will have a terminal status as ‘Failed’ max by 30 hours if ZATCA is continuously non-responsive. 6. If the auth token is valid, but the user does not have the authorization to fetch invoice details, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an “Admin” role for the particular VAT used in the request.