Submit Receipt Documents

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

Authenticate POS Get Receipt Details

Overview

Receipt Submission API is the main API of the solution because it is used to submit one or more receipts of different types to the solution. Receipts submitted are grouped into the submission, each of the receipt part of the submission must be linked to and complying with data structure of the receipt type version active at the moment of issuance of the receipt (see receipt type versions supported).

Receipt submission API supports receipts submitted in JSON format. Taxpayer POS system or integration module is responsible for transforming the data into JSON format as per the receipt type structure expected by API (see receipt type versions supported). Note that all receipts 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 (“application/json”).

When API is called it performs minimal set of validations through validation equation to check that submission is of correct structure, that each receipt within it is issued by the taxpayer issuing the receipts and that structure of each of the receipts match the appropriate structure of the receipt type version used.

After synchronous validation succeeds (at least partially), caller receives back the assigned submission ID that are accepted for further processing.

Note! POS should be activated before submission on any other channel.

Signature

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

Signature: POST /api/v1/receiptsubmissions

Inputs

This API accepts standard eReceipt API header parameters for authenticated call except for the one defined below:

Header parameter Type Description Value example
Content type String (70) Defines the type of the document submission format used. Can use JSON only. application/json

Body of the request contains a single receipts 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
receipts Document[] List of document objects submitted. List should have at least one document. Array of Documents
signatures Signature[] Structure containing one or two digital signatures. At least signature of the Issuer must be present. Signature of the Service provider is optional. See structure.

Document can be either:

  • Receipt - Receipt is the document issued by the taxpayer for the good or service purchased by customer.
  • Return Receipt - Return Receipt is a document issued by the taxpayer for the purchase goods or service that are returned by the customer.
  • Return Receipt Without Reference - Return Receipt Without Reference is a document issued by the taxpayer for the purchase goods or service that are returned by the customer for international return receipts or return receipt that are referencing sales receipts that are not captured on the system..

Outputs

Successful Response

On a successful submission API returns unique submission ID. This ID will be used to track the status of the submission

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 (30) Unique ID of the submission. TZRKK8MFZCPSTW9XCYWBMKME10
acceptedDocuments Document Accepted[] List of documents that are accepted. See structure
rejectedDocuments Document Rejected[] List of documents that are not accepted together with their error information. See structure

Document Accepted

Output parameter Type Description Value example
uuid UUID Unique document ID, SHA256 format 68e656b251e67e835…
longId String (200) Unique long Id that was assigned by eInvoicing and eReceipt solution BFNGXFA17265TQX34…
receiptNumber String (50) Internal ID used in submission for the document PZ-234-A

Document Rejected

Output parameter Type Description Value example
receiptNumber String (50) Internal ID used in submission for the document 232522
uuid UUID Unique document ID, SHA256 format 68e656b251e67e835…
error Error Error information detailing why the document was not accepted in this submission See structure

Note Sample of rejected document

Error

Output parameter Type Description Value example
message String (4000) Human readable error message. If available, message is returned in user’s preferred language. Issuance date time value is out of the range of submission workflow parameter
target String The target/subject of the error, e.g. UUID of the document (in top level error), parameter that caused the error (in errors under details). 68e656b251e67e835… or Datetimeissued
propertyPath String Optional: Document property name that caused the error receipts.datetimeissued
details Error[] Optional: list of multiple errors detected that caused document to get rejected. See Structure.

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.

Document Signature

Element Type Description Value example
signatureType String Type of the signature: Issuer (I), ServiceProvider (S) I
value String Signature value contains CAdES-BES standard Base64 encoded signature Base64 encoded string

Note! The function to perform signature validation will not be deployed at this point until a decision is provided by ETA to test and deploy the component.

Additional considerations

Mapping Internal IDs to ETA Assigned Ones

To support mapping of internal documents managed in Taxpayer ERP and POS solution to documents issued or received through eInvoicing solution, when submitting documents to eInvoicing taxpayers can supply their internal invoice identifiers (used in ERP and POS 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.

Note: Only Taxpayers assigned with B2C tag will be allowed to submit receipts.

Throttling

Given large amounts of submissions coming from multiple taxpayers, it is recommended that taxpayers submit receipts in batches, it is important that ERP and POS 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.