Overview
The Search Documents API has various enhanced filters for precise queries and provides access to large result set in a paginated way.
Search documents allows users to query the system and return list of documents that have been received or issued.
To invoke this API, users must provide values for either the submissionDateFrom
and submissionDateTo
filter parameters or the issueDateFrom
and issueDateTo
filter parameters. Users can combine these optional filters in various ways to obtain precise results.
Results will be returned in a paginated format based on the specified pageSize
, allowing users to navigate through multiple pages of results.
Note: The values of the input filter parameters should remain consistent when requesting subsequent pages of results.
Days difference between submissionDateFrom
and submissionDateTo
filter parameters, and issueDateFrom
and issueDateTo
filter parameters should not exceed a configured number of days set by e-Invoice system administrators (Current configuration is 30 days).
Results list is ordered based on registration date of the submission descending (newest documents submitted into the e-Invoice system appear first).
Signature
This is REST based that accepts the below URL filter parameters to search for documents.
Signature:
GET /api/v1.0/documents/search?&uuid={uuid}&submissionDateFrom={submissionDateFrom}&submissionDateTo={submissionDateTo}&pageSize={pageSize}&issueDateFrom={issueDateFrom}&issueDateTo={issueDateTo}&direction={direction}&status={status}&documentType={documentType}&receiverId={receiverId}&receiverIdType={receiverIdType}&issuerTin={issuerTin}
Inputs
This API accepts standard e-Invoice API header parameters for authenticated call.
URL parameters accepted:
URL parameter | Type | Description | Value example | Requirement |
---|---|---|---|---|
uuid | String | Optional: Unique ID of the document to retrieve. | F9D425P6DS7D8IU | Optional |
submissionDateFrom | DateTime | Optional: The start date and time when the document was submitted to the e-Invoice API, Time to be supplied in UTC timezone. Mandatory when ‘submissionDateTo’ is provided or issueDate filters are not used | 2022-11-25T01:59:10Z | Optional |
submissionDateTo | DateTime | Optional: The end date and time when the document was submitted to the e-Invoice API, Time to be supplied in UTC timezone. Mandatory when ‘submissionDateFrom’ is provided or issueDate filters are not used | 2022-12-22T23:59:59Z | Optional |
pageSize | Number | Optional: number of the documents to retrieve per page. Page size cannot exceed system configured maximum page size for this API. Default is 100 | 100 | Optional |
issueDateFrom | DateTime | Optional: The start date and time when the document was issued. Mandatory when ‘issueDateTo’ is provided or submissionDate filters are not used | 2021-02-25T23:55:10Z | Optional |
issueDateTo | DateTime | Optional: The end date and time when the document was issued. Mandatory when ‘issueDateFrom’ is provided or submissionDate filters are not used | 2021-03-10T01:59:10Z | Optional |
direction | Text | Optional: direction of the document. Possible values: (Sent , Received ). When not provided sent and received documents are retrieved. |
Sent | Optional |
status | Text | Optional: status of the document. Possible values: (Valid , Invalid , Cancelled , Submitted ) |
Valid | Optional |
documentType | Text | Optional: Unique name of the document type. Possible values: 01 [Invoice], 02 [Credit Note], 03 [Debit Note], 04 [Refund Note], 11 [Self-billed Invoice], 12 [Self-billed Credit Note], 13 [Self-billed Debit Note], 14 [Self-billed Refund Note] |
01 | Optional |
receiverId | Text | Optional: Document recipient identifier. Only can be used when ‘Direction’ filter is set to Sent. Possible values: (Business registration number, Passport Number, National ID) | 201901234567 | Optional |
receiverIdType | Text | Optional: Document recipient identifier type. Only can be used when ‘Direction’ filter is set to Sent. Possible values: (BRN, PASSPORT, NRIC, ARMY) This is mandatory in case the receiverId is provided | PASSPORT | Optional |
issuerTin | Text | Optional: Document issuer identifier. Only can be used when ‘Direction’ filter is set to Received. | C2584563200 | Optional |
Outputs
Successful Response
This API returns HTTP status code 200
.
The resulting structure is part of a single object containing result
structure.
Output parameter | Type | Description | Value example |
---|---|---|---|
uuid | String | Unique document ID in e-Invoice | 42S512YACQBRSRHYKBXBTGQG22 |
submissionUID | String | Unique ID of the submission that document was part of | XYE60M8ENDWA7V9TKBXBTGQG10 |
longId | String | Unique long temporary Id that can be used to query document data anonymously | YQH73576FY9VR57B… |
internalId | String | Internal ID used in submission for the document | PZ-234-A |
typeName | String | Unique name of the document type that can be used in submission of the documents. Possible values: 01 [Invoice], 02 [Credit Note], 03 [Debit Note], 04 [Refund Note], 11 [Self-billed Invoice], 12 [Self-billed Credit Note], 13 [Self-billed Debit Note], 14 [Self-billed Refund Note] |
01 |
typeVersionName | String | Name of the document type version within the document type that can be used in document submission to identify document type version being submitted | 1.0 |
issuerTin | String | TIN of issuer | C2584563200 |
issuerName | String | Issuer company name | AMS Setia Jaya Sdn. Bhd. |
receiverId | String | Optional: receiver registration number (can be national ID or foreigner ID). | 087377381 |
receiverIdType | Text | Optional: Document recipient identifier type. Only can be used when ‘Direction’ filter is set to Sent. Possible values: (BRN, PASSPORT, NRIC, ARMY,) This is mandatory in case the receiverId is provided | PASSPORT |
receiverName | String | Optional: receiver name (can be company name or person’s name) | AMS Setia Jaya Sdn. Bhd. |
dateTimeIssued | DateTime | The date and time when the document was issued in the UTC timeformat | 2015-02-13T13:15:10Z |
dateTimeReceived | DateTime | The date and time when the document was submitted in the UTC timeformat | 2015-02-13T14:20:10Z |
totalSales | Decimal | Total sales amount of the document in MYR. | 10.10 |
totalDiscount | Decimal | Total discount amount of the document in MYR. | 50.00 |
netAmount | Decimal | Total net amount of the document in MYR. | 100.70 |
total | Decimal | Total amount of the document in MYR. | 124.09 |
totalOriginalSales | Decimal | Total sales amount of the document in Original currency. | 10.10 |
totalOriginalDiscount | Decimal | Total discount amount of the document in Original currency. | 50.00 |
netOriginalAmount | Decimal | Total net amount of the document in Original currency. | 100.70 |
totalOriginal | Decimal | Total amount of the document in Original currency. | 124.09 |
status | String | Status of the document - Submitted , Valid , Invalid , Cancelled |
Valid |
cancelDateTime | Date | Refer to the document cancellation that has been initiated by the taxpayer “issuer” of the document on the system, will be in UTC format | 2021-02-25T01:59:10Z |
rejectRequestDateTime | Date | 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 | 2021-02-25T01:59:10Z |
documentStatusReason | String | Mandatory: Reason of the cancellation or rejection of the document. | Examples of reasons: Wrong buyer details or Wrong invoice details or any other reasons as appropriate |
createdByUserId | String | User created the document. Can be ERP ID or User Email | 1XXXXXXXX00:9e21b10c-41c4-9323-c590-95abcb6e4e4d general.ams@supplier.com |
Throttling and Rate limiting
To allow consistent performance for all taxpayers using e-Invoice API and prevent overuse of resources, this API has throttling limits set per taxpayer (current configuration is 1 Request every 2 Seconds). The throttling limit is subject to change by e-Invoice system administrators.
See the standard error response for more details when your calls to the API are throttled.
Error Response
Error situations are reported back by this API through the standard error response.
Additional considerations
Days difference between submissionDateFrom
and submissionDateTo
filter parameters, and issueDateFrom
and issueDateTo
filter parameters are currently configured to 30 days. Days difference value can be changed by e-Invoice system administrators.
There are no maximum number of documents that can be returned by this endpoint. You can use the various optional filters to get the desired documents results.
Receiver of the documents can retrieve documents that are in statuses Valid
or Cancelled
. If document exists, and is issued to given receiver, but status is Submitted
or Invalid
, document will not be part of the response. Issuer of the documents can retrieve documents in any status. The document validation or public URL can be created using below -
{envbaseurl}/uuid-of-document/share/longid
where {envbaseurl} need to be replaced with MyInvois portal Base URL