form-dataGet the PDF/A3 version of an E-Invoice with the XML attached by sending the non-PDF/A3 version and the invoice identifiers of the invoice data already sent to Clear earlier.
Request Method
POST
Request URL
{{BASE_URL}}/v2/einvoices/embeddedpdf
Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.
Rate Limit : 150 API requests per minute
Request Headers
Parameter
Data Type
Field Validations
Description
x-cleartax-auth-token
String
Cannot be empty
vat
String
Cannot be empty
Mandatory. VAT or Group VAT of the entity.
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
Parameter
Data Type
Field Validations
Description
invoiceNumber
String
-
Mandatory. Document Number.
invoiceType
String
Enum: INV, CRN, DBN, RECEIPT
Mandatory. Document Type.
issueDate
String
YYYY-MM-DD
Mandatory. Document Date.
vat
String
-
Mandatory. TaxPayer/VAT Number.
pdfTypeResponse
String
Enum: PDF_BASE64, PDF_FILE
Optional. If the field is not passed or left blank then by default PDF_FILE
All query parameters should be URL encoded.
Request Body
Parameter
Data Type
Field Validations
Description
file
form-data
Content type: application/pdf
Optional. Human readable PDF file with all the fields as per ZATCA compliance requirements including the QR Code.
base64EncodedPdfFile
form-data
Application/json
Optional. Base64 encoded content of the PDF file in double quotes.
If the user is not authenticated for the operation
403
If the user is not authorized for the operation
404
If the data is not present
429
Too many requests
5XX
Unhandled exception
Response Schema
The response will be a PDF/A3 file with embedded XML or a base64 encoded PDF/A-3 for a successful scenario depending on the input given in request query params. In case of an error, the error response will be an array of error details objects.
If the PDF is not present in the request or if the PDF in the request is invalid.
{
"ErrorList": [
{
"ErrorCode": "300114",
"ErrorMessage": "Please supply a valid PDF file. Supplied file content type is : null , and file name is: ",
"ErrorSource": "CLEARTAX"
}
]
}
HTTP Status Code - 404
If there is no document in Clear for the given document details in the request.
{
"ErrorList": [
{
"ErrorCode": "300102",
"ErrorMessage": "You don't have any data present for the selected Document Details",
"ErrorSource": "CLEARTAX"
}
]
}
API Validations
The file in the request should be a valid PDF file or base64 encoded PDF file.
The invoiceNumber, invoiceType, issueDate and vat should be valid and the invoice data for this document must be present in Clear.
User has to pass either the PDF file or base64 encoded value of the PDF file in the request body and without at least one of them the API would not work.
API Constraints
This API needs to be authenticated with a valid user authentication token. If the authentication 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.
If the authentication token is valid, but the user does not have the authorization to download the invoice with the given search parameters, then the API will return an error 403.
If data is not present in the Clear then the API will return HTTP Status Code 404.
