Submit Documents

Taxpayer can submit one or more signed documents to eInvoicing solution using this API.

Get Document Type Version Cancel Document

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 e-Invoicing 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.

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 e-Invoicing. 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.
403 IncorrectSubmitter Returned when submitted 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 including supported size in the Error object in the body of the return message.
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.
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 e-Invoicing solution, when submitting documents to e-Invoicing taxpayers can supply their internal invoice identifiers (used in ERP solution) and also internal product identifiers for the goods or services sold.

When e-Invoicing solution returns back assigned unique IDs for document submission (containing one or more documents) each individual document accepted by the solution contains assigned e-Invoicing 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.