Submit Documents

Overview

Submit Documents API is the main API of the solution because it is used to submit one or more documents of different types to the system. Documents submitted are grouped into the submission. Then, each document that is part of the submission must be linked to and comply with data structure of the document type (see document type versions supported).

Document submission API supports documents submitted using JSON and XML format. Taxpayer ERP system or integration module is responsible for transforming the data into JSON or XML format as per the document type structure expected by API (see document type versions supported). Note that all documents within the submission and enclosing submission element itself needs to be in the same format. The format used should be provided through Content-type request header value.

When API is called, it performs minimal set of validations through validation rules to check that submission is of correct structure. Then, each document that is part of the submission is checked for the taxpayer issuing the documents. The structure of each document is checked that it matches the appropriate structure of the document type version used.

After synchronous validation succeeds, caller receives back the assigned submission ID and list of IDs of the documents that are accepted for further processing, matching them back to internal document IDs supplied so that callers can map them in taxpayer ERP system. These IDs can later be used to retrieve documents, submission information and learn about full validation results. If required, they can also be used to cancel the document.

Signature

This is REST based API that receives its document submission information in the body of the request.

Signature: POST /api/v1.0/documentsubmissions/

Inputs

This API accepts standard e-Invoice API header parameters for authenticated call except for the one defined below:

Body of the request contains a single documents value that contains one or more Document objects. Document objects of different types and even versions can have different fields supplied.

Single document consists of:

Document can be either:

• Invoice - Invoice is a commercial document issued by Supplier to itemise and record a transaction with Buyer.
• Credit Note - Credit note is the document issued by Suppliers to correct errors, apply discounts, or account for returns in a previously issued e-Invoice with the purpose of reducing the value of the original e-Invoice. This is used in situations where the reduction of the original e-Invoice does not involve return of monies to the Buyer.
• Debit Note - Debit note is the document issued to indicate additional charges on a previously issued e-Invoice.
• Refund Note - Refund note is the document issued by a Supplier to confirm the refund of the Buyer’s payment. This is used in situations where there is a return of monies to the Buyer.
• Self-Billed Invoice - There are certain circumstances where another party (other than the Supplier) will be allowed to issue a self-billed e-Invoice. Kindly refer to Section 8 of the e-Invoice Specific Guideline where self-billed e-Invoice will be allowed.
  Self-Billed Invoice refers to the self-billed e-Invoice that will be issued by the Buyer for the transaction with the Supplier, based on the circumstances as specified in Section 8 of the e-Invoice Specific Guideline.
• Self-Billed Credit Note - Self-Billed Credit Note is issued by Buyers to correct errors, apply discounts, or account for returns in a previously issued Self-Billed e-Invoice with the purpose of reducing the value of the original Self-Billed e-Invoice. This is used in situations where the reduction of the original Self-Billed e-Invoice does not involve return of monies to the Buyer
• Self-Billed Debit Note - Self-Billed Debit Note is the document issued by Buyers to indicate additional charges on a previously issued Self-Billed e-Invoice.
• Self-Billed Refund Note - Self-Billed Refund Note is the document issued by Buyers to confirm the refund payment from the Supplier. This is used in situations where there is a return of monies from the Supplier to the Buyer.

Outputs

Successful Response

On a successful submission, API returns unique submission ID and unique IDs for all documents accepted. These IDs assigned are mapped to the internal IDs that are inside the documents so that caller ERP system can map them back in the ERP as well.

Given that the process of validation is not complete when result is returned, API returns HTTP status code 202.

Accepted Documents

Accepted document response consists of:

Rejected Documents

Rejected document response consists of:

Error Response

Error situations are reported back by this API through the standard error response.

Additional specialised error messages can be returned as a result of validation of documents:

Additional considerations

The e-Invoice file size rules are as follows:

1. 5 MB maximum submission size;
2. 100 maximum e-Invoices per submission; and
3. 300 KB maximum per e-Invoice.

No restriction on the number of lines in an e-Invoice will be imposed, as long as the rules above are met.

Minification of XML/JSON Documents

In order to optimize document size and prevent potential validation errors, we recommend implementing minification techniques for XML and JSON documents submitted via the Submit Document API. This entails the compression of whitespace and unnecessary characters within the documents, effectively reducing their overall size without altering their content or structure.

Minification serves two primary purposes:

• ⁠Size Optimization: By eliminating unnecessary whitespace, line breaks, and indentation, the size of XML and JSON documents can be significantly reduced. This is particularly beneficial when dealing with large datasets or documents, helping to minimize bandwidth usage and improve overall system performance.

• Validation Error Prevention: Minification can help mitigate the risk of encountering validation errors, such as the 1,000 lines limitation. By reducing the overall line count of the documents, the likelihood of hitting such limits is diminished, ensuring smoother processing and transmission of data.

Implementing minification as part of the document submission process not only enhances the efficiency of data transfer but also contributes to a more robust and scalable system architecture. We encourage developers to incorporate minification techniques into their workflows when utilizing the Submit Document API, thereby optimizing performance and mitigating potential validation issues.

Mapping Internal IDs to Assigned Ones

To support mapping of internal documents managed in taxpayer ERP system to documents issued or received through MyInvois System, taxpayers can supply their internal invoice identifiers (used in ERP solution) and also internal product identifiers for the goods sold or services rendered when submitting e-Invoice to LHDNM.

When MyInvois System returns back assigned unique IDs for document submission (containing one or more documents), each individual document accepted by the solution contains assigned e-Invoice ID, long unique ID used for the creation of validation link and internal document ID (that was supplied by the submitter).

Throttling

Given large amounts of submissions coming from multiple taxpayers, it is recommended that taxpayers submit invoices in batches, it is important that ERP systems are not calling the API too frequently. Therefore, solution leverages throttling techniques configured by administrators. See standard headers description to see headers that are returned in successful responses and standard error response information for throttling error information.

Notes