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.
Note! when you are logged in as intermediary, permissions that are granted by the taxpayer will be applied on your profile and this will control the functionalities that you'll be able to executed on behalf of the taxpayer you are representing.
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:
| Header parameter | Type | Description | Value example |
|---|---|---|---|
| Content type | String | Defines the type of the document submission format used. Can use XML or JSON. | application/json |
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.
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| documents | Document[] | List of document objects submitted. List should have at least one document. The document should follow the UBL 2.1 schema based on the document type version. | Array of Documents |
Single document consists of:
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| format | String | XML, JSON | XML |
| document | String | The base64 of the document JSON or XML | |
| documentHash | String | The hash value of the document being submitted. Hashing can be performed using algorithms like SHA256 as mentioned here. | |
| codeNumber | String | Document reference number used by Supplier for internal tracking purpose | INV12345, CN23456, DN34567 |
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.
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| submissionUID | String | Unique ID of the submission. 26 Latin alphanumeric symbols. | |
| acceptedDocuments | acceptedDocuments[] | List of documents that are initially accepted (passed sync validations) together with their invoice code numbers and newly assigned IDs. | |
| rejectedDocuments | rejectedDocuments[] | List of documents that are not accepted together with their invoice code numbers and error information. |
Accepted Documents
Accepted document response consists of:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique document ID assigned by e-Invoice. 26 Latin alphanumeric symbols. | |
| invoiceCodeNumber | String | Document reference number used by Supplier for internal tracking purpose | INV12345, CN23456, DN34567 |
Rejected Documents
Rejected document response consists of:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| invoiceCodeNumber | String | Document reference number used by Supplier for internal tracking purpose | INV12345, CN23456, DN34567 |
| error | Error | Error information detailing why the document was not accepted in this submission. |
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:
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | BadStructure | Returned when there is a structural error with the submission message. Either is not having the Documents included in a single Document tag or there are other elements that are not allowed. |
| 400 | MaximumSizeExceeded | Returned when the size of the submission exceeds allowed limit. Details including supported size in the Error object in the body of the return message. It is expected that calling system creates smaller submissions and submit them one by one. |
| 403 | IncorrectSubmitter | Returned when submitter of the documents is trying to submit them on behalf of the other taxpayer. Also returned when intermediary is submitting documents on behalf of taxpayer, but they do not have such a permission. Details in the Error object in the body of the return message. |
| 422 | DuplicateSubmission | Returned when an identical submission is detected based on the previous submissions sent by the same taxpayer within the past 10 minutes. Issuer can try submitting the same payload again based on the returned value in the response header Retry-After in seconds. Detection works on hashing the request payload and compare it with previous submissions. |
Additional considerations
The e-Invoice file size rules are as follows:
- 5 MB maximum submission size;
- 100 maximum e-Invoices per submission; and
- 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.
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 IRBM.
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.