Overview
Document Submission API is the main API of the solution because it is used to submit one or more documents of different types to the solution. Documents submitted are grouped into the submission, each of the documents part of the submission must be linked to and complying with data structure of the document type version active at the moment of issuance of the document (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 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 equation to check that submission is of correct structure, that each document within it is issued by the taxpayer issuing the documents and that structure of each of the documents match the appropriate structure of the document type version used.
After synchronous validation succeeds (at least partially), 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 or decline rejection.
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
API 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 eInvoicing 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. | Array of Documents |
Document can be either:
- Invoice - used by taxpayer to invoice seller about goods delivered or goods to be delivered.
- Credit Note - used by taxpayer to update amounts of previously issued invoice(s). Amounts supplied in credit note cannot exceed total amounts of the referenced invoices. No new invoice lines can be added.
- Debit Note - used by taxpayer to update the amounts of previously issued invoice in case price has increased, for example and buyer ows seller more.
- Export Invoice - used by taxpayer to invoice a foreign seller about goods delivered or goods to be delivered.
- Export Credit Note - used by taxpayer to update amounts of previously issued export invoice(s). Amounts supplied in export credit note cannot exceed total amounts of the referenced export invoices. No new export invoice lines can be added.
- Export Debit Note - used by taxpayer to update the amounts of previously issued export invoice in case price has increased, for example a foreign buyer ows seller more.
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 |
|---|---|---|---|
| submissionUUID | String | Unique ID of the submission. 26 Latin alphanumeric symbols. | TZRKK8MFZCPSTW9XCYWBMKME10 |
| acceptedDocuments | Document Accepted[] | List of documents that are accepted together with their internal IDs and newly assigned IDs. | See structure |
| rejectedDocuments | Document Rejected[] | List of documents that are not accepted together with their internal IDs and error information. | See structure |
Document Accepted
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique document ID assigned by eInvoicing. 26 Latin alphanumeric symbols. | TZRKK8MFZCPSTW9XCYWBMKME11 |
| longId | String | Unique long temporary Id that can be used to query document data anonymously. 42 Latin alphanumeric symbols. | TZRKK8MFZ CPSTW9XC YWBMKME10A BC123160 2681697 |
| internalId | String | Internal ID used in submission for the document | PZ-234-A |
Document Rejected
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| internalId | String | Internal ID used in submission for the document | P-234 |
| error | Error | Error information detailing why the document was not accepted in this submission | See structure |
Error
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| code | String | Error code that client must be able to handle. | BadArgument |
| message | String | Human readable error message. If available, message is returned in user’s preferred language. | Previous passwords may not be reused |
| target | String | Optional: the target/subject of the error, e.g., parameter that caused the error. | password |
| details | Error[] | Optional: list of multiple errors detected that caused overall API call to fail. Used to return all errors in one go so that they all can be corrected by the caller before calling again. | <JSON list of Error structures> |
Error Response
Error situations are reported back by this API through the standard error response.
Additional specialized 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. |
| 403 | Forbidden | Returned when submitter of the documents is trying to submit them while submitter profile has ‘B2B Deny ERP Submission’ tag assigned to it by ETA Admin. Details 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
Mapping Internal IDs to ETA Assigned Ones
To support mapping of internal documents managed in Taxpayer ERP solution to documents issued or received through eInvoicing solution, when submitting documents to eInvoicing taxpayers can supply their internal invoice identifiers (used in ERP solution) and also internal product identifiers for the goods or services sold.
When eInvoicing solution returns back assigned unique IDs for document submission (containing one or more documents) each individual document accepted by the solution contains assigned eInvoicing ID, long unique ID used for inclusion in the document printouts 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.