Get Document via UUID

This API allows you to retrieve the document object in JSON format and its corresponding metadata for a given UUID.

Request Method

GET

Request URL

{{HOST}}/einvoice/v1/documents

Rate Limit : 1000 API requests per minute

Request Headers

ParameterData TypeField ValidationsDescription

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.

Request Path Params

There are no path parameters for this API.

Request Query Params

ParameterData TypeField ValidationsDescription

einvoice-type

ENUM

SALES, PURCHASE, SALES_B2C

NA

uuid

String

Mandatory - If document-id is not specified.

UUID of the document, as per LHDN

document-id

String

Mandatory - If uuid is not specified.

Unique document-id generated after generation.

Request Body

There will be no request body for this API.

Sample Request

Request Body

NA

Response Status Codes

HTTP Status CodeDescription

200

For a successful retrieval

400

For any kind of validation issues

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

ParameterData TypeField ValidationsDescription

Success

Boolean

true/false

Identifies whether the request processing was successful or not

DocumentId

String

NA

DocumentId generated by ClearTax uniquely identifies the document.

Status

String

VALID/

INVALID/

SUBMITTED/

NOT_SUBMITTED/

CANCELLED

Mandatory. Status of Document Processing

VALID: E-Invoice is generated for the document and is Valid.

INVALID: E-Invoice has validation errors from LHDN

SUBMITTED: E-Invoice Generation is in Progress

NOT_SUBMITTED: E-Invoice is not submitted for the Document

Uuid

String

NA

Unique document ID in e-Invoice, shared by LHDN for the document

LongId

String

NA

Unique long temporary Id that can be used to query document data anonymously

InternalId

String

NA

Internal ID used in submission for the document to LHDN, link document number

DateTimeValidated

DateTime

NA

The date and time when the document passed all validations and moved to the valid state.

CancelDateTime

DateTime

NA

Refer to the document cancellation that has been initiated by the taxpayer “issuer” of the document on the system, will be in UTC format

RejectRequestDateTime

DateTime

NA

Refer to the document rejection request that has been initiated by the taxpayer “receiver” of the document on the system, will be in UTC format

IssuerTin

String

NA

TIN of issuer

IssuerName

String

NA

Issuer company name

ReceiverId

String

NA

Optional: receiver registration number (can be national ID or foreigner ID).

ReceiverName

String

NA

Optional: receiver name (can be company name or person’s name)

TotalExcludingTax

Amount

NA

Total sales amount of the document in MYR.

TotalDiscount

Amount

NA

Total discount amount of the document in MYR.

TotalNetAmount

Amount

NA

Total net amount of the document in MYR.

TotalPayableAmount

Amount

NA

Total amount of the document in MYR.

Document

Json

NA

Document Received from LHDN in Json Format.

QrCode

String

NA

QrCode generated by Cleartax using unique longId and UUID.

qrCodePreSignedUrl

String

NA

URL for QR Code image with link access expiry of 3 days.

ErrorDetails

Array

NA

Optional. List of error objects.

Sample Response (Success)

HTTP Status Code: 200

Response Body

{
    "Success": "true",
    "DocumentId": "6661aa2bb9b8da72880487ad",
    "Status": "VALID",
    "Uuid": "9C7TX0XB4CBP1KVM5XADJ41J10",
    "LongId": "ZF5CG3EG349E53NB5XADJ41J10Nvg2HZ1719214189",
    "InternalId": "INV-2024-05-22-502",
    "DateTimeValidated": "2024-06-24T07:29:50",
    "CancelDateTime": "null",
    "RejectRequestTime": null,
    "IssuerTin": "C58746708080",
    "IssuerName": "Envisage Telco Sdn Bhd",
    "ReceiverId": "C5896234040",
    "ReceiverName": "Rajesh A/L Kumar",
    "TotalExcludingTax": 0.0,
    "TotalDiscount": 0.0,
    "TotalNetAmount": 16680.0,
    "TotalPayableAmount": 0.0,
    "Document": {"Document in JSON format"},
    "GovtQrCodeUrl": "https://preprod.myinvois.hasil.gov.my/22ZKQD6WWHJ66P3D8ZYZ6Z3J10/share/ERDBTDJ7BX38RSXZ8ZYZ6Z3J10hGBcLC1722255670",
    "QrCode": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAADRUlEQVR4Xu3XW25jOQxFUc5A85+lZqDiOnKjyhcBqn86DNCW4/sQtwLxLdf5N2PXc+bL8cEe44M9xgd7jA/2GP83bFf1ffd991utWhHsdQWzWP81tNap3TP9XdWPaxFMY/bej73hta+0R3MR/ABsRdQI85axfgzGzevq0WtA50dgSJfTsl7ArmtZGtksZttfjnpm1hO44z/E8mTz7fZTlLD137JZbPO6dE5Eoq9e60brJJbX1R7n7xKOHrrevIXlCGZSEdwSeWf7h9z7PMbbqoxaI3Foc9PmAoNYLHmkh3IjQHvzi53fW9sAJvaAvWtqaHNSWQe58kGMlysw7lwrR4u8DmMJwwSiuYUwI0ynsRhWmebv1Jnefaq2taMYSUkUnLAEC4EdnWax7dhU+WzJcxwLbni+5GPY5uU4Wkj2ZUUVl/On60cwHu7YVKoruvQk5+tu81iXPoZlZSa+h1CZ9K7C92PXvrFpi8VBXnIkfYTlt2M3Flfo6EOVNJHznvUjmBxhVH5fzi7aWtPK4TBWkiMFx3czbsllukxjfS8VD04TydLLotQ0BtI8iKwRpAK0l76AMSzSdrYUdhpNylic5jaLXRW4XXxm34sSV5thzObZUiJbYy6Tlg5jMSivV4ycbR+p/XocxFq09dwWtB6Mmo0fhfDPCJnA2DWnzXJd4uB6X1xOYzc3UlZuoqxgePJJ7GiymohdR5ssUKHfsn4GK/VZnWkTb6xqHfE4xudHX5M4vYSNTSRYh7FK76eH2gdNOaTNNOatNBA65L6dV+gxj/F7X1NXUqhz5/dHqfl+zNZTnCWJ7dOp5SWNpjHFRYkpiS0qX9V6uc1i2ycuj7d9eti/zyx2ROFJ9aOH2lz5yZg+PIspzkUHR/ZlgTkre3oeq/z6Eo8s/ErkNN5pjBHzm/VWQnaV4T31FiETmAfGXdovBSoJtKPLPMbE8qbUw5s6kATAKJYpKaLyVY4pJ8ep1uL+j0HsasCkopPfGZsKsmcWU1XMe6dP+z4JnsCcx47KpywLTm/7H0P/AIwScvp2NCZP3pCPYv5yJJAtO2zd3T8j5PuxUgdXYG5vqyqGVvoXo9hfxwd7jA/2GB/sMT7YY3ywx9i/AMvYcY1nE/k/AAAAAElFTkSuQmCC",
“qrCodePreSignedUrl”: “https://clr-tax-http.internal.cleartax.co/S7u8NNhG”,
    "ErrorDetails": null
}

Sample Response (Error)

HTTP Status Code: 200

Response Body

{
    "Success": "false",
    "ErrorDetails": [
        {
            "ErrorCode": "6003",
            "ErrorMessage": "No Documents found for the requested search",
            "ErrorSource": "CLEARTAX"
        }
    ]
}

API Validations

Currently, there are no known validations.

API Constraints

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.

Last updated