Overview
List of recent documents can be received and paged through using Get Recent Documents API. But if it is required to retrieve larger set of documents including those that were submitted or received also prior to those returned by Recent Documents API, this API should be used.
This API allows request for extraction of larger Document set submitted to the eInvoicing 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/documentpackages/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 document. Allowed values - full, summary. Full represents the structure of the document including invoice lines. Summary represents only document summary lines. |
full |
| format | String | Format of the data to create. Allowed values - CSV (only allowed for summary requests), JSON, XML |
JSON |
| queryParameters | Query Parameters | Query parameters to apply when creating the package | JSON |
Requesting package on behalf of taxyaper:
If you are an intermediary and you are requesting package on behalf of the taxpayer you are representing, then you need to add the following parameters in the request body
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| representedTaxpayerFilterType | integer | This field is a reference to the packages intermediary is requesting, if you set the value to be, ‘1’: this means you are requesting package for all taxpayers you are representing, ‘2’: this means that you are requesting a package on behalf of specific taxpayer & you need to provide his taxpayer RIN, ‘3’: this means you are requesting package for yourself as a taxpayer | All = 1 ,Specific = 2, Me = 3 |
| representeeRin | String | (Optional) Registration number for business in Egypt must be registration number | 100015840 |
Query Parameters
| Input 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 |
| documentTypeNames | String[] | Optional: Array of document type requested. Allowed values - i, c, d |
i |
| statuses | String[] | Optional: Array of document statuses to filter. Allowed values - valid, invalid, rejected, cancelled |
valid |
| productsInternalCodes | String[] | Optional: Array of internal code used for the product being sold, exact match | 8383S |
| receiverSenderType | String | Type of the other entity 0(Business), 1(Person), 2(Foreign) |
0 |
| receiverSenderId | String | Optional: Value depends on the selected ‘receiverSenderType’. RIN of Taxpayer (Business), National ID (Person), ID (Foreign) used either in issuer ID or receiver ID fields of the document | 345987378 |
| branchNumber | String | Optional: Branch Number of the issuer | 0 |
| itemCodes | Item Codes | Optional: Array of the item codes used in filtering line items of the document | JSON |
| truncateifexceeded | Boolean | Optional: Boolean value to confirm the creation of document package if the document count between the requested time intervals exceeds the pre-configured size. When set to false, if the document count exceeds the pre-configured size, it will throw a validation error, else, it creates the package successfully. When set to true, if the document count exceeds the pre-configured size, it will continue to create the document package by truncating it to the pre-configured size. Default is false |
false |
Item Codes
| Input parameter | Type | Description | Value example |
|---|---|---|---|
| codeValue | String | code value of the item code | 1000000000003 |
| codeType | String | 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 document type specified, all document type documents are included in result set.
Outputs
Successful Response
On a successful submission API returns 201 status code and the object containing assigned package ID. This package 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. 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 documents 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 |
| 403 | Forbidden | Returned when caller of the endpoint is trying to request documents package while caller profile has ‘B2B Deny ERP Document Retrieval’ tag assigned to it by ETA Admin. |
Additional considerations
For the documents received by calling taxpayer system does not include documents in status invalid or submitted into the package prepared.
Before accepting request and issuing package ID system validates the count of documents to be extracted and if it exceeds pre-configured throttling thresholds, request is rejected by asking submitter to limit the request via date period or other parameters.