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

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.

Request Path Params

There are no path parameters for this API.

Request Query Params

Parameter	Data Type	Field Validations	Description
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 Code	Description
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

Parameter	Data Type	Field Validations	Description
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

Rate Limit: The below rate limits are in line with those applied by LHDN.

Production - 60 API calls per minute with a burst capacity of 6 API calls

Sandbox - 6 API calls per minute with a burst capacity of 2 API calls