Request Document Package

API allows taxpayer system to request larger packages of previously sent or received documents to be prepared for download.

Search Documents Get Package Requests

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.