Format - ISO.DATE
E.g - 2024-07-20
Mandatory.
Document Start date
Format - ISO.DATE
E.g - 2024-07-22
Mandatory.
Document End Date
The difference between start date & end date should not be more than 3 days
SALES, SALES\_B2C,
PURCHASE,
SALES\_CONSOLIDATED,
PURCHASE\_CONSOLIDATED
| Mandatory. | | page-number | Integer |
NA
Optional. Default: 0
Specifies the current page number for which data is to be retrieved. The value 0 represents the first page.
| | page-size | Integer | Minimum: 1, Maximum: 1000 |Optional. Default: 100
Defines the maximum number of documents to be returned in a single API call. The value must be between 1 and 1000.
| ### Request Body There will be no request body for this API. ### Sample Request Request Body ```json 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 | | Documents | Array |NA
VALID/
INVALID/
SUBMITTED/
NOT\_GENERATED/
CANCELLED/
FAILED/
CONSOLIDATED
|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\_GENERATED: E-Invoice is not submitted for the Document
CANCELLED : E-Invoice is cancelled
FAILED : E-Invoice Generation failed.
CONSOLIDATED: E-Invoice is consolidated.
| | 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 | |ConsolidatedDocumentId
|String
|NA
|This will come only in case the status is “CONSOLIDATED”. It will represent the ClearTax generated DocumentId of the consolidated Document.
| | ConsolidatedDocumentStatus | String | NA | This will come only in case the status is “CONSOLIDATED”. It will represent the status of the consolidated Document. | | ErrorDetails | Array | NA | Optional. List of error objects. | ### Sample Response (Success) HTTP Status Code: 200 Response Body - 1 ```json { "Success": "true", "Documents": [ { "DocumentId": "66befcb7c465be7e9d3b9012", "DocumentNumber": "2024-07-17-60", "Status": "VALID", "UUID": "GGWX0HS8NFHJ8MFJTX441D5J10", "LongId": "QQGV37423WR2NF4AVX441D5J10KsaNUM1723793019", "InternalId": "2024-07-17-60", "DateTimeValidated": "2024-08-16T15:23:40", "CancelDateTime": null, "RejectRequestDateTime": null, "ConsolidatedDocumentId": "", "ConsolidatedDocumentStatus": "", "ErrorDetails": [] } ], "ErrorDetails": null, "PageNumber": 0, "PageSize": 1 } ``` Response Body - 2 ```json { "Success": "true", "Documents": [ { "DocumentId": "66befdb283e43b65c86dc09b", "DocumentNumber": "B2C+INV0000355", "Status": "CONSOLIDATED", "UUID": "545DM5QYDZ32Z1YC3JYY9D7J10", "LongId": "9Y420DYS8XSG80S73JYY9D7J10cZh0Xp1725949770", "InternalId": "CINV_SALES_B2C_2409_0000002", "DateTimeValidated": "2024-09-10T14:29:30", "CancelDateTime": null, "RejectRequestDateTime": null, "ConsolidatedDocumentId": "66dfe749a0c21f09d11aacfe", "ConsolidatedDocumentStatus": "VALID", "ErrorDetails": [] } ], "ErrorDetails": null, "PageNumber": 0, "PageSize": 1 } ``` ### Sample Response (Error) HTTP Status Code: 200 Response Body ```json { "ErrorDetails": [ { "ErrorCode": "400", "ErrorMessage": "Invalid Request Parameter passed.", "ErrorSource": "CLEARTAX", "Path": 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. 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. 3. If the auth token is valid, but the user does not have the authorization to get list of documents, 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. 4. Rate Limit: The below rate limits are in line with those applied by LHDN. **Production - 500 API calls per minute with a burst capacity of 25 API calls** **Sandbox - 500 API calls per minute with a burst capacity of 25 API calls**