Upload E-Invoice

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

https://api-sandbox.my.cleartax.com/einvoice/v1/documents/upload

Request Headers

ParameterData TypeField ValidationsDescription

x-clear-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

ParameterData TypeField ValidationsDescription

einvoice-type

ENUM

SALES, PURCHASE, SALES_B2C

Mandatory. API is available only for SALES_B2C

Disabled for other E-Invoice Types

Request Body

ParameterData TypeField ValidationsDescription

Documents

Array

MinListLength: 1

MaxListLength: 10

Mandatory. List of Documents

Version

String

Mandatory. MY_GENERATE_UBL_2_1_V1

Documents Object

ParameterData TypeField ValidationsDescription

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”

})

Document Data 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.

Sample Request

Request Body

{
    "Documents": [
        {
            "DocumentData": "ewogICAgIkludm9pY2VUeXBlQ29kZSI6IHsKICAgICAgICAiVmFsdWUiOiAiMDEiCiAgICB9LAogICAgIklzc3VlRGF0ZSI6ICIyMDI0LTA2LTAzIiwKICAgICJJc3N1ZVRpbWUiOiAiMTg6MzA6MDAiLAogICAgIkRvY3VtZW50Q3VycmVuY3lDb2RlIjogIk1ZUiIsCiAgICAiSWQiOiAiVEVTVC1TQUxFUy0wMDQiLAogICAgIkFjY291bnRpbmdTdXBwbGllclBhcnR5IjogewogICAgICAgICJQYXJ0eSI6IHsKICAgICAgICAgICAgIkNvbnRhY3QiOiB7CiAgICAgICAgICAgICAgICAiRWxlY3Ryb25pY01haWwiOiAiZ2VuZXJhbEBwbHVzLmNvbS5teSIsCiAgICAgICAgICAgICAgICAiVGVsZXBob25lIjogIjYwMzIyMzAwOTAiCiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJJbmR1c3RyeUNsYXNzaWZpY2F0aW9uQ29kZSI6IHsKICAgICAgICAgICAgICAgICJWYWx1ZSI6ICIwMTExMSIsCiAgICAgICAgICAgICAgICAiTmFtZSI6ICJPdGhlciBzZXJ2aWNlIGFjdGl2aXRpZXMgbi5lLmMuIgogICAgICAgICAgICB9LAogICAgICAgICAgICAiUGFydHlJZGVudGlmaWNhdGlvbiI6IFsKICAgICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAgICAiSWQiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJTY2hlbWVJRCI6ICJUSU4iLAogICAgICAgICAgICAgICAgICAgICAgICAiVmFsdWUiOiAiQzU4NzQ2NzA4MDgwIgogICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgIklkIjogewogICAgICAgICAgICAgICAgICAgICAgICAiU2NoZW1lSUQiOiAiQlJOIiwKICAgICAgICAgICAgICAgICAgICAgICAgIlZhbHVlIjogIjIwMjQwMTAyMTEyOCIKICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9LAogICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICJJZCI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgIlNjaGVtZUlEIjogIlNTVCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICJOQSIKICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9LAogICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICJJZCI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgIlNjaGVtZUlEIjogIlRUWCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICJOQSIKICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIF0sCiAgICAgICAgICAgICJQYXJ0eUxlZ2FsRW50aXR5IjogewogICAgICAgICAgICAgICAgIlJlZ2lzdHJhdGlvbk5hbWUiOiAiWFlaIgogICAgICAgICAgICB9LAogICAgICAgICAgICAiUG9zdGFsQWRkcmVzcyI6IHsKICAgICAgICAgICAgICAgICJBZGRyZXNzTGluZSI6IFsKICAgICAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgICAgICJMaW5lIjogIk1lbmFyYSBLb3Jwb3JhdCIKICAgICAgICAgICAgICAgICAgICB9LAogICAgICAgICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAgICAgICAgIkxpbmUiOiAiUGVyc2FkYSBQTFVTIgogICAgICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICAgICAiTGluZSI6ICJQZXJzaW1wYW5nYW4gQmVydGluZ2thdCBTdWJhbmcgS00xNSIKICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgIkNpdHlOYW1lIjogIkxlYnVocmF5YSBCYXJ1IExlbWJhaCBLbGFuZyIsCiAgICAgICAgICAgICAgICAiQ291bnRyeSI6IHsKICAgICAgICAgICAgICAgICAgICAiSWRlbnRpZmljYXRpb25Db2RlIjogewogICAgICAgICAgICAgICAgICAgICAgICAiQ291bnRyeUNvZGUiOiAiTVlTIgogICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICAiQ291bnRyeVN1YmVudGl0eUNvZGUiOiAiMTAiLAogICAgICAgICAgICAgICAgIlBvc3RhbFpvbmUiOiAiNDczMDEiCiAgICAgICAgICAgIH0KICAgICAgICB9CiAgICB9LAogICAgIkludm9pY2VMaW5lIjogWwogICAgICAgIHsKICAgICAgICAgICAgIklkIjogIjEiLAogICAgICAgICAgICAiSW52b2ljZWRRdWFudGl0eSI6IHsKICAgICAgICAgICAgICAgICJRdWFudGl0eSI6IDEsCiAgICAgICAgICAgICAgICAiVW5pdENvZGUiOiAiS0dTIgogICAgICAgICAgICB9LAogICAgICAgICAgICAiSXRlbSI6IHsKICAgICAgICAgICAgICAgICJDb21tb2RpdHlDbGFzc2lmaWNhdGlvbiI6IFsKICAgICAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgICAgICJJdGVtQ2xhc3NpZmljYXRpb25Db2RlIjogewogICAgICAgICAgICAgICAgICAgICAgICAgICAgIkxpc3RJRCI6ICJDTEFTUyIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiVmFsdWUiOiAiMDExIgogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgXSwKICAgICAgICAgICAgICAgICJEZXNjcmlwdGlvbiI6ICJSZXBhaXIgYW5kIG1haW50ZW5hbmNlIiwKICAgICAgICAgICAgICAgICJPcmlnaW5Db3VudHJ5IjogewogICAgICAgICAgICAgICAgICAgICJJZGVudGlmaWNhdGlvbkNvZGUiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJDb3VudHJ5Q29kZSI6ICJNWVMiCiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAiSXRlbVByaWNlRXh0ZW5zaW9uIjogewogICAgICAgICAgICAgICAgIkFtb3VudCI6IHsKICAgICAgICAgICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICIxMjAwMDAiCiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJBbGxvd2FuY2VDaGFyZ2UiOiBbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgIkNoYXJnZUluZGljYXRvciI6IGZhbHNlLAogICAgICAgICAgICAgICAgICAgICJNdWx0aXBsaWVyRmFjdG9yTnVtZXJpYyI6IDAuMTAsCiAgICAgICAgICAgICAgICAgICAgIkFsbG93YW5jZUNoYXJnZVJlYXNvbiI6ICJTYW1wbGUiLAogICAgICAgICAgICAgICAgICAgICJBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJDdXJyZW5jeUlEIjogIk1ZUiIsCiAgICAgICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICIxMjAwMC4wMCIKICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9LAogICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICJDaGFyZ2VJbmRpY2F0b3IiOiB0cnVlLAogICAgICAgICAgICAgICAgICAgICJNdWx0aXBsaWVyRmFjdG9yTnVtZXJpYyI6IDAsCiAgICAgICAgICAgICAgICAgICAgIkFsbG93YW5jZUNoYXJnZVJlYXNvbiI6ICJTYW1wbGUiLAogICAgICAgICAgICAgICAgICAgICJBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJDdXJyZW5jeUlEIjogIk1ZUiIsCiAgICAgICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICIwLjAwIgogICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgXSwKICAgICAgICAgICAgIlByaWNlIjogewogICAgICAgICAgICAgICAgIlByaWNlQW1vdW50IjogewogICAgICAgICAgICAgICAgICAgICJDdXJyZW5jeUlEIjogIk1ZUiIsCiAgICAgICAgICAgICAgICAgICAgIlZhbHVlIjogIjEwODAwMC4wMCIKICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgfSwKICAgICAgICAgICAgIkxpbmVFeHRlbnNpb25BbW91bnQiOiB7CiAgICAgICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAgICAgIlZhbHVlIjogIjEwODAwMCIKICAgICAgICAgICAgfSwKICAgICAgICAgICAgIlRheFRvdGFsIjogewogICAgICAgICAgICAgICAgIlRheEFtb3VudCI6IHsKICAgICAgICAgICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICI4NjQwLjAwIgogICAgICAgICAgICAgICAgfSwKICAgICAgICAgICAgICAgICJUYXhTdWJ0b3RhbCI6IFsKICAgICAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgICAgICJUYXhBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAgICAgICAgICAgICAgICAgIlZhbHVlIjogIjg2NDAuMDAiCiAgICAgICAgICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICAgICAgICAgICJUYXhhYmxlQW1vdW50IjogewogICAgICAgICAgICAgICAgICAgICAgICAgICAgIkN1cnJlbmN5SUQiOiAiTVlSIiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICIxMDgwMDAuMDAiCiAgICAgICAgICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICAgICAgICAgICJUYXhDYXRlZ29yeSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJJZCI6ICIwMSIKICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgIF0KICAgICAgICAgICAgfQogICAgICAgIH0KICAgIF0sCiAgICAiQWxsb3dhbmNlQ2hhcmdlIjogWwogICAgICAgIHsKICAgICAgICAgICAgIkNoYXJnZUluZGljYXRvciI6IGZhbHNlLAogICAgICAgICAgICAiQWxsb3dhbmNlQ2hhcmdlUmVhc29uIjogIlNhbXBsZSBEZXNjcmlwdGlvbiIsCiAgICAgICAgICAgICJBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAiVmFsdWUiOiA4MDAwLAogICAgICAgICAgICAgICAgIkN1cnJlbmN5SUQiOiAiTVlSIgogICAgICAgICAgICB9CiAgICAgICAgfSwKICAgICAgICB7CiAgICAgICAgICAgICJDaGFyZ2VJbmRpY2F0b3IiOiB0cnVlLAogICAgICAgICAgICAiQWxsb3dhbmNlQ2hhcmdlUmVhc29uIjogIlNhbXBsZSBEZXNjcmlwdGlvbiIsCiAgICAgICAgICAgICJBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAiVmFsdWUiOiAwLAogICAgICAgICAgICAgICAgIkN1cnJlbmN5SUQiOiAiTVlSIgogICAgICAgICAgICB9CiAgICAgICAgfQogICAgXSwKICAgICJUYXhUb3RhbCI6IFsKICAgICAgICB7CiAgICAgICAgICAgICJUYXhBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAgICAgIlZhbHVlIjogIjEwMDAwLjAwIgogICAgICAgICAgICB9LAogICAgICAgICAgICAiVGF4U3VidG90YWwiOiBbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAgICAgIlRheGFibGVBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJDdXJyZW5jeUlEIjogIk1ZUiIsCiAgICAgICAgICAgICAgICAgICAgICAgICJWYWx1ZSI6ICIxMDAwMDAuMDAiCiAgICAgICAgICAgICAgICAgICAgfSwKICAgICAgICAgICAgICAgICAgICAiVGF4QW1vdW50IjogewogICAgICAgICAgICAgICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAgICAgICAgICAgICAiVmFsdWUiOiAiMTAwMDAuMDAiCiAgICAgICAgICAgICAgICAgICAgfSwKICAgICAgICAgICAgICAgICAgICAiVGF4U3VidG90YWwiOiBbCiAgICAgICAgICAgICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJUYXhBbW91bnQiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIkN1cnJlbmN5SUQiOiAiTVlSIiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiVmFsdWUiOiAiMTAwMDAuMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9LAogICAgICAgICAgICAgICAgICAgICAgICAgICAgIlRheENhdGVnb3J5IjogewogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICJJZCI6ICIwMSIKICAgICAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgIF0KICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgXQogICAgICAgIH0KICAgIF0sCiAgICAiTGVnYWxNb25ldGFyeVRvdGFsIjogewogICAgICAgICJMaW5lRXh0ZW5zaW9uQW1vdW50IjogewogICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAiVmFsdWUiOiAiMTA4MDAwLjAwIgogICAgICAgIH0sCiAgICAgICAgIkFsbG93YW5jZVRvdGFsQW1vdW50IjogewogICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAiVmFsdWUiOiAiODAwMC4wMCIKICAgICAgICB9LAogICAgICAgICJDaGFyZ2VUb3RhbEFtb3VudCI6IHsKICAgICAgICAgICAgIkN1cnJlbmN5SUQiOiAiTVlSIiwKICAgICAgICAgICAgIlZhbHVlIjogIjAuMDAiCiAgICAgICAgfSwKICAgICAgICAiVGF4RXhjbHVzaXZlQW1vdW50IjogewogICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAiVmFsdWUiOiAiMTAwMDAwLjAwIgogICAgICAgIH0sCiAgICAgICAgIlRheEluY2x1c2l2ZUFtb3VudCI6IHsKICAgICAgICAgICAgIkN1cnJlbmN5SUQiOiAiTVlSIiwKICAgICAgICAgICAgIlZhbHVlIjogIjExMDAwMC4wMCIKICAgICAgICB9LAogICAgICAgICJQcmVwYWlkQW1vdW50IjogewogICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAiVmFsdWUiOiAiMC4wMCIKICAgICAgICB9LAogICAgICAgICJQYXlhYmxlQW1vdW50IjogewogICAgICAgICAgICAiQ3VycmVuY3lJRCI6ICJNWVIiLAogICAgICAgICAgICAiVmFsdWUiOiAiMTEwMDAwLjAwIgogICAgICAgIH0sCiAgICAgICAgIlBheWFibGVSb3VuZGluZ0Ftb3VudCI6IHsKICAgICAgICAgICAgIlZhbHVlIjogIjAuMDAiCiAgICAgICAgfQogICAgfSwKICAgICJQYXltZW50TWVhbnMiOiB7CiAgICAgICAgIlBheW1lbnRNZWFuc0NvZGUiOiAiNCIKICAgIH0sCiAgICAiUGF5bWVudFRlcm1zIjogewogICAgICAgICJOb3RlIjogIlBheW1lbnQgTWV0aG9kIGlzIGNhc2giCiAgICB9Cn0=",
            "DocumentFormat": "JSON",
            "UniqueIdentifier": "C58746708080_TEST-SALES-001_01_2024",
            "CustomFields": {
                "Internal Number": "INV00001234561687"
            },
            "version": "MY_GENERATE_UBL_2_1_V1"
        }
    ]
}

Sample Request - Upload Document Details - Decoded

Response Status Codes

HTTP Status CodeDescription

200

For successfully submitted document or with validation errors

400

For any kind of Invalid Payload issues

401

If the user is not authenticated for the operation

403

If the user is not authorized for the operation

Response Schema

ParameterData TypeField ValidationsDescription

Success

Boolean

true/false

Mandatory. Indicates the request was successful or not

DocumentResponses

Array

NA

NA

ErrorDetails

Array<ErrorDetail>

Error details

Optional.

Error list from ClearTax

Document Details Object

ParameterData TypeField ValidationsDescription

DocumentId

String

NA

Unique document id generated in database

UniqueId

String

NA

Mandatory. Same uniqueId as shared in the request

Success

Boolean

true/false

Indicates, if the request for this document was successfully processed or not

Status

String

NA

Enum, status of the document.

ErrorDetails

Array<ErrorDetail>

Error details

Optional.

Error list from ClearTax/LHDN

WarningDetails

Array<ErrorDetail>

Warning details

Optional. Warning list from ClearTax

Sample Response (Success)

HTTP Status Code

200

Response Body

{
    "ErrorDetails": null,
    "Success": "true",
    "DocumentResponses": [
        {
            "DocumentId": "66694ab91fe33e3be063dc57",
            "Success": "true",
            "UniqueId": "C58746708080_TEST-SALES-004_01_2024",
            "ErrorDetails": null,
            "WarningDetails": null
        }
    ]
}

Sample Response (Error)

HTTP Status Code: 400

Response Body

{
    "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

  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. 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

Last updated