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.