Overview
List of recent receipts can be received and paged through using Get Recent Receipts API. But if it is required to retrieve larger set of receipts including those that were submitted or received also prior to those returned by Recent Receipts API, this API should be used.
This API allows request for extraction of larger receipts set submitted to the eReceipt system. The request is processed by the system asynchronously, caller is notified or queries the status and can download the prepared package.
Signature
API is REST based API that receives that does not take any URL parameters.
Signature:
POST /api/v1.0/receiptpackages/requests
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call.
Body of the request contains a single object that contains these fields:
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| type | String | Type of the data to return for each receipt. Allowed values - Full, Summary. Full represents the structure of the receipt including item lines. Summary represents only receipt summary lines. |
Full |
| format | String | Format of the data to create. Allowed values - CSV (only allowed for summary requests), JSON |
JSON |
| queryParameters | Query Parameters | Query parameters to apply when creating the package | JSON |
Query Parameters
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| represntedTaxpayerTypeId | String(10) | Type of represented taxpayer. Allowed values - Issuer, Receiver, Both |
Issuer |
| dateFrom | DateTime | The date and time of the start of the interval requested in UTC format | 2015-02-13T14:20Z |
| dateTo | DateTime | The date and time of the end of the interval requested in UTC format | 2015-02-20T21:30Z |
| posSerial | String(200) | Optional: To filter the requested receipts by POS serial number | SN-123456 |
| receiptUUID | String(64) | Optional: To filter the requested receipts by UUID | 68e656b251e67e835… |
| submissionUUID | String(64) | Optional: To filter the requested receipts by submissionUUID | JU7GH07JNA23N |
| receiverSenderType | String(10) | Optional: Type of the other entity B(Business), P(Person), F(Foreign). This value is only used if the receiverSenderId input parameter is provided |
B |
| receiverSenderId | String(50) | Optional: Value depends on the selected receiverSenderType. It could be the RIN of Taxpayer (Business), National ID (Person), ID (Foreign), used either in issuer ID or receiver ID fields of the receipt |
345987378 |
| documentTypeNames | String[] | Optional: Array of receipt type requested. Allowed values - s, r in addition receipt types Receipt Types |
s |
| branchNumber | String(50) | Optional: Branch Number of the issuer | 0 |
| itemCodes | Item Codes | Optional: Array of the item codes used in filtering line items of the receipt | See structure. |
Item Codes
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| codeValue | String(100) | code value of the item code | 1000000000003 |
| codeType | String(30) | type of the code, allowed values are EGS, GS1 |
GS1 |
Parameters are applied with AND operation. If optional parameters are not provided, they are not included in the filter, i.e., if no receipt type specified, all receipt type receipts are included in result set.
Outputs
Successful Response
On a successful submission API returns 201 status code and the object containing assigned request ID. This request Id can later be used to download the package.
Error Response
Error situations are reported back by this API through the standard error response.
Additional specialized error messages can be returned:
| HTTP Status Code | Error Code | Description |
|---|---|---|
| 400 | OperationExceedsLimit | Returned when caller has submitted query parameters so broad that resulting data set would exceed pre-configured size of 3000. In this case caller system should adjust the query parameters by restricting data interval to retrieve less objects. Error parameter in body of the message includes the count of receipts that would be matching the current request and system limit. |
| 400 | BadArgument | Returned when supplied parameter values are not correct format and also when type full is used for CSV format |
Additional considerations
Before accepting request and issuing package ID system validates the count of receipts to be extracted and if it exceeds pre-configured throttling thresholds of 3000, request is rejected by asking submitter to limit the request via date period or other parameters.