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/dataRate Limit : 1000 API requests per minute
Request Headers
x-cleartax-auth-token
String
Cannot be empty
Mandatory. User auth token.
vat
String
Cannot be empty
Mandatory. User auth token.
branch
String
Should be a valid branch from the user account.
Optional. Branch name (store name) added in the user account which maps to a VAT or Group VAT of the entity.
Request Path Params
There are no path parameters for this API.
Request Query Params
uniqueId
String
Should be present if 4 parameters are absent.
Conditional.Concat of seller vat + invoice id + invoice type code + issue date. All these entities are separated by underscore.
invoiceNumber
String
NA
Conditional. Document Number (Invoice Reference Number).
invoiceType
String
Enum: INV, CRN, DBN, RECEIPT
Conditional. INV - Invoice, CRN - Credit Note, DBN - Debit Note, RECEIPT - Receipt
issueDate
String
yyyy-mm-dd
Conditional. Document Date
vat
String
NA
Conditional. VAT Number.
Request Body
Sample Request
Response Status Codes
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
DeviceId
String
MaxLength: 36
Optional. Device ID used to generate invoices.
Status
String
Enum:GENERATED,NOT_GENERATED,GENERATION_FAILED, IN_PROGRESS
Mandatory. Status of E-Invoice QR Code. This is the same as QrCodeStatus below. Provided only for backward compatibility for Phase I API.
IN_PROGRESS, NOT_GENERATED, GENERATION_FAILED
QrCodeStatus
String
Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED
Mandatory. Status of E-Invoice QR Code.
GENERATED, NOT_GENERATED, GENERATION_FAILED
InvoiceStatus
String
Enum: NOT_SUBMITTED, FAILED, NOT_REPORTED, REPORTED, CLEARED, NOT_CLEARED, ACCEPTED_WITH_WARNING, PENDING, DISCARDED
Mandatory. Status of submission to ZATCA.
NOT_SUBMITTED
QRCode
String
Optional. Rendered QR Code image in base64 encoded PNG format.
If clearance fails, this will be null.
RawQRCode
String
Optional. QR Code payload in base64 encoded TLV format.
For reporting, this will be generated by ClearTax. Except when complete XML is generated by ERP and sent in the input.
For clearance, this will be generated by ZATCA. If clearance fails, this will be null.
InvoiceXml
String
Optional. In the case of Standard invoices, the XML is returned by ZATCA.
In the case of Simplified invoices, it is the XML used for reporting.
UUID
String
Optional. UUID sent to ZATCA
ClearTax generates this before sending to ZATCA, if not sent in input.
ICV
String
Optional. Invoice counter value sent to ZATCA ClearTax generates this before sending it to ZATCA.
PIH
String
Optional. Previous hash value, Invoice hash value of previous invoice reported/cleared for same deviceId.
InvoiceHash
String
Optional. Current invoice hash.
Hash value of current invoice xml by removing tags ext:UBLExtensions, cac:AdditionalDocumentReference:QRCode
InvoiceType
String
Enum: INV, CRN, DBN
Mandatory.
Document Type: INV-INVOICE, CRN-CREDIT NOTE, DBN-DEBIT NOTE.
InvoiceNumber
String
Cannot be null
Mandatory. Invoice number (ID) as per the input.
IssueDate
String
Cannot be null
Mandatory. Issue Date as per the input.
IssueTime
String
Format: HH:mm:ss (24 hr format)
Mandatory. Invoice issue time. The time when the invoice was issued.
GeneratedDate
String
Cannot be null
Mandatory. Date on which the invoice is generated.
GeneratedTime
String
Format: HH:mm:ss (24 hr format)
Mandatory. Invoice generation time. The time when the invoice is generated.
SellerVatNumber
String
Cannot be null
Mandatory. Seller VAT identification number.
BuyerVatNumber
String
Cannot be null
Optional. Buyer VAT identification number.
ErrorList
Array<Error Detail>
Error details from zatca
Optional.Error list from zatca (6.8.1)
Message
String
NA
Optional.Message received from zatca
Error Details Object
ErrorCode
String
Cannot be null
A code to identify the error. Error codes are published above.
ErrorMessage
String
Cannot be null
Human readable error message.
ErrorSource
String
ZATCA, CLEARTAX
Source of the error.
Path
String
-
If it is a validation error of a request data, it will point to the request data field. Example below.
Sample Response
Success for Simplified Document - HTTP Status Code - 200
Success for Standard Document - HTTP Status Code - 200
Success with Warning - HTTP Status Code - 200
Error from ClearTax - HTTP Status Code - 400
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).
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".
API Validations
The uniqueIdentifier passed in request params should be valid and must be present in ClearTax datastore.
4 fields passed should belong to the user.
API Constraints
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.
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.
Taxpayers can request details of only one invoice per request.
The API will only return details of those invoices present in the ClearTax data store.
Last updated
Was this helpful?