Search Documents

This API allows taxpayer's systems to search the documents sent or received which are available on the MyInvois System using various filters.

Get Document Details Full e-Invoice API list

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, user should omit the continuationToken parameter initially, and should provide values for the filter parameters submissionDateFrom and submissionDateTo or the filter parameters issueDateFrom and issueDateTo. User can use various combination of the provided optional filters to receive precise results.

Results will return in a paginated approach based on the pageSize provided, to navigate to the next page(s) of results in the result set, user needs to send the value of the continuationToken.

Note: Provided input filters parameters values should not change when requesting next page(s) of results in the result set using the the continuationToken filter.

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}&continuationToken={continuationToken}&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
uuid String Optional: Unique ID of the document to retrieve. F9D425P6DS7D8IU
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
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
continuationToken string Optional: Token provided to navigate to the next page. Must be omitted or use an empty string when requesting the first page. Y4RWK9617T0TJNRBF4CSVGQG10
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
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
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
direction Text Optional: direction of the document. Possible values: (Sent, Received). When not provided sent and received documents are retrieved. Sent
status Text Optional: status of the document. Possible values: (Valid, Invalid, Cancelled, Submitted) Valid
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
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
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
issuerTin Text Optional: Document issuer identifier. Only can be used when ‘Direction’ filter is set to Received. C2584563200

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
submissionUUID 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. 2015-02-13T13:15:10Z
dateTimeReceived DateTime The date and time when the document was submitted. 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 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