Overview
Get package requests API allows callers to list previously requested packages and check their status.
System limits the number of the packages that can be received in one request through implementing paging mechanism for this API.
List is ordered based on package request date descending.
Signature
API is REST based API that takes optional URL parameters to enable paging.
Signature:
GET /api/v1.0/documentpackages/requests?pageNo={pageNo}&pageSize={pageSize}
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call.
URL parameters accepted:
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| pageNo | Number | Optional: number of the page to retrieve. Typically this parameter value is derived from initial parameter less call when caller learns total amount of page of certain size | 3 |
| pageSize | Number | Optional: number of the packages to retrieve per page. Page size cannot exceed system configured maximum page size for this API | 20 |
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is part of a single object containing result structure and metadata structure.
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| result | Document Package Information[] | Array of document package information objects | See structure |
| metadata | Metadata[] | Information about the results retrieved or results matching the query | See structure |
Document Package Information
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| packageId | String | Unique ID of the package. | KLJHH78NJUHQ |
| submissionDate | DateTime | The date and time of submission of the package request | 2015-02-13T14:20Z |
| status | Number | Status of the package preparation. Values - 1: in progress, 2: complete, 3: error, 4: deleted |
2 |
| type | Number | Type of the data to return for each document. Values - 1: full, 2: summary. Full represents the structure of the document including invoice lines. Summary represents only document summary lines. |
1 |
| format | Number | Format of the data to create. Allowed values - 1: CSV (only used for summary requests), 2: XML, 3: JSON |
3 |
| requestorTypeId | Number | Entity which requested the package. Allowed values - 1: Intermediary, 2: Taxpayer,3: Internal User, 4: ERP |
2 |
| requestorTaxpayerRIN | String | ID of taxpayer used either in issuer ID or receiver ID fields of the document | 115519213 |
| requestorTaxpayerName | String | Name of the taxpayer used either in issuer ID or receiver ID fields of the document | Company Name |
| deletionDate | DateTime | Optional: the date and time when it is planned to remove prepared package. Has value only if status is 2: complete |
2015-02-23T14:20Z |
| isExpired | Boolean | Flag ro indicate if the package is expired | false |
| queryParameters | Query Parameters | Query parameters to apply when creating the package | JSON |
Query Parameters
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| dateFrom | DateTime | The date and time of the start of the interval requested | 2015-02-13T14:20Z |
| dateTo | DateTime | The date and time of the end of the interval requested | 2015-02-20T21:30Z |
| documentTypeName | String | Optional: document type requested. Allowed values - i, c, d |
i |
| statuses | String | Optional: comma seperated string of document status to filter. Allowed values - , valid, invalid, rejected, cancelled |
valid |
| productsInternalCodes | String | Optional: comma seperated string of Internal codes used for the product being sold | 8383S |
| receiverSenderType | Number | Type of entity used either in issuer ID or receiver ID fields of the document with the specefied Taxpayer in requestorTaxpayerRIN. Allowed values - , 0: Business, 1: Person, 2: Foreign |
0 |
| receiverSenderId | String | ID of party used either in issuer ID or receiver ID fields of the document. Value depends on the receiverSenderType value |
345987378 |
| branchNumber | String | Branch Number of the issuer | 0 |
| itemCodes | String | JSON string which contains an array of the item codes used in filtering line items of the document | {"ItemCodes": [{"CodeValue": "1000000000003","CodeType": "GS1"},{"CodeValue": "EG-113317713-121212","CodeType": "EGS"} |
Metadata
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| totalPages | Number | Total count of pages based on the supplied (or default) page size | 23 |
| totalCount | Number | Total count of matching objects | 157 |
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 |
|---|---|---|
| 403 | Forbidden | Returned when caller of the endpoint is trying to request document package while caller profile has ‘B2B Deny ERP Document Retrieval’ tag assigned to it by ETA Admin. |
Additional considerations
API is limited to retrieve only certain page size to prevent huge queries to be executed. Maximum page size is defined by eInvoicing system administrators.
When taxpayer representative system is requesting packages, all packages requested by any representative (including person) of this taxpayer are returned.