Upload E-Invoice API is used for validation & persistence of Invoice Data with CT, additional actions on the Invoice can be done later using documentId. Particularly useful for B2C Invoice Flow, where Customer Details might not be available for E-Invoice Generation or the Invoice is to be consolidated.
Request Method
POST
Request URL
{{HOST}}/einvoice/v1/documents/upload
Rate Limit : 1000 API requests per minute
Request Headers
Parameter
Data Type
Field Validations
Description
x-cleartax-auth-token
String
Cannot be empty
Mandatory. User auth token.
x-clear-tin
String
Cannot be empty
Mandatory. TIN of the entity
x-clear-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 TIN of the entity.
x-request-id
UUID
Should be unique for every request
Optional. Unique request ID.
Used for Debugging Support Issues
Content-Type
String
application/json
application/json
Request Path Params
There are no path paramaters for this API.
Request Query Params
Parameter
Data Type
Field Validations
Description
einvoice-type
ENUM
SALES, PURCHASE, SALES_B2C
Mandatory. API is available only for SALES_B2C
Disabled for other E-Invoice Types
Request Body
Parameter
Data Type
Field Validations
Description
Documents
Array
MinListLength: 1
MaxListLength: 10
Mandatory. List of Documents
Version
String
Mandatory. MY_GENERATE_UBL_2_1_V1
Documents Object
Parameter
Data Type
Field Validations
Description
DocumentData
String
NA
Mandatory. Base64 of the document data shared below
DocumentFormat
ENUM
JSON
Mandatory. Describes the data received is in the JSON Format
UniqueIdentifier
String
NA
Mandatory. Unique identifier formed with concatenation of TIN, Document Number, Document Type, Fiscal Year fields with _
Example: C948329382_INV-101_INV_2024
CustomFields
Object
NA
Map of Custom fields with key-value pair eg : ( {
“Internal Number” : “INV000012”
})
DocumentData object is similar to the Generate E-Invoice Request Body.
AccountingCustomerParty, Delivery Details are optional for SALES B2C Documents.
If present, the Details are validated as per LHDN validations.
{
"ErrorDetails": null,
"Success": "true",
"DocumentResponses": [
{
"DocumentId": null,
"Success": "false",
"UniqueId": "C58746708080_TEST-SALES-004_01_2024",
"ErrorDetails": [
{
"ErrorCode": "ibr-cl-15",
"ErrorMessage": "[ibr-cl-15]-Origin country codes in an invoice (ibt-159) MUST be coded using ISO code list 3166-1",
"ErrorSource": "CLEARTAX",
"Path": "Invoice.InvoiceLine[0].Item[0].OriginCountry[0].IdentificationCode"
}
],
"WarningDetails": null
}
]
}
API Validations
Currently there are no known validations.
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.
If the auth token is valid, but the user does not have the authorization to generate an e-invoice for a document, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular TIN used in the request
