Overview
A new updated API that replaces the existing Get Recent Documents API. The Search Documents API has various enhanced filters for precise queries and provides access to even quite large result set in a paginated way.
Search documents allows users to query the system and return list of documents that have been received or issued so that they can be reviewed, downloaded (through a separate call to Get Document Printout API for example).
To invoke this API, user initially should omit the continuationToken parameter, and should provide values for the filter parameters submissionDateFrom and submissionDateTo or the filter parameters issueDateFrom and issueDateTo. User can use various combination of the provided optional filters to receive precise results.
Results will return in a paginated approach respecting on the pageSize provided, to navigate to the next page(s) of results in the result set, user needs to send the value of the continuationToken which is received in Metadata response in the continuationToken input parameter and so on. When the user navigates through the entire result set and reaches the last page, the eInvoicing system will return the value EndofResultSet in the continuationToken property in the Metadata, this means that all results are returned for the provided search query.
Note: Provided input filters parameters values should not change when requesting next page(s) of results in the result set using the the continuationToken filter.
Days difference between submissionDateFrom and submissionDateTo filter parameters, and issueDateFrom and issueDateTo filter parameters should not exceed a configured number of days set by eInvoicing system administrators (Current configuration is 30 days).
Results list is ordered based on registration date of the submission descending (newest documents registered into the eInvoicing system appear first).
Signature
API is REST based that accepts the below URL filter parameters to search for documents.
Signature:
GET /api/v1.0/documents/search?&submissionDateFrom={submissionDateFrom}&submissionDateTo={submissionDateTo}&issueDateFrom={issueDateFrom}&issueDateTo={issueDateTo}&continuationToken={continuationToken}&uuid={uuid}&internalID={internalID}
Inputs
This API accepts standard eInvoicing API header parameters for authenticated call.
URL parameters accepted:
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| submissionDateFrom | DateTime | Optional: The start date and time when the document was submitted to the eInvoicing API, Time to be supplied in UTC timezone. Mandatory when ‘submissionDateTo’ is provided or issueDate filters are not used | 2022-11-25T01:59:10 |
| submissionDateTo | DateTime | Optional: The end date and time when the document was submitted to the eInvoicing API, Time to be supplied in UTC timezone. Mandatory when ‘submissionDateFrom’ is provided or issueDate filters are not used | 2022-12-22T23:59:59 |
| continuationToken | string | Optional: Token provided to navigate to the next page. Must be omitted or use an empty string when requesting the first page. | 1674529517710| Y4RWK9617T0TJNRBF4CSVGQG10 |
| pageSize | Number | Optional: number of the documents to retrieve per page. Page size cannot exceed system configured maximum page size for this API. Default is 100 | 100 |
| issueDateFrom | DateTime | Optional: The start date and time when the document was issued. Mandatory when ‘issueDateTo’ is provided or submissionDate filters are not used | 2021-02-25T23:55:10 |
| issueDateTo | DateTime | Optional: The end date and time when the document was issued. Mandatory when ‘issueDateFrom’ is provided or submissionDate filters are not used | 2021-03-10T01:59:10 |
| direction | Text | Optional: direction of the document. Possible values: (‘Sent’, ‘Received’). When not provided sent and received documents are retrieved. | Sent |
| status | Text | Optional: status of the document. Possible values: (‘Valid’, ‘Invalid’, ‘Rejected’, ‘Cancelled’, ‘Submitted’) | Valid |
| documentType | Text | Optional: Unique name of the document type. Possible values: ‘i’ [invoice], ‘c’ [credit note], ‘d’ [debit note], ‘ii’ [import invoice], ‘ei’ [export invoice], ‘ec’ [export credit note], ‘ed’ [export debit note] | i |
| receiverType | Text | Optional: Document recipient type. Only can be used when ‘Direction’ filter is set to Sent. Possible values: (‘B’ [Business], ‘F’ [Foreigner], ‘P’ [Person]) |
F |
| receiverId | Text | Optional: Document recipient identifier. Only can be used when ‘Direction’ filter is set to Sent. Possible values: (Business registration number, Passport Number, National ID, Foreign company registration ID) |
327389457 |
| issuerType | Text | Optional: Document issuer type. Only can be used when ‘Direction’ filter is set to Received. Possible values: (‘B’ [Business], ‘F’ [Foreigner]) |
B |
| issuerId | Text | Optional: Document issuer identifier. Only can be used when ‘Direction’ filter is set to Received. Possible values: (Business registration number, Foreign company registration ID) |
827388957 |
| uuid | Text | Optional: Unique document identifier | 42S512YACQBRSRHYKBXBTGQG22 |
| internalID | Text | Optional: Internal identifier used in submission for the document | PZ-234-A |
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 Summary[] | Array of document summary objects | See structure |
| metadata | Metadata | Information how to navigate in result set. | See structure |
Document Summary
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String | Unique document ID in eInvoicing | 42S512YACQBRSRHYKBXBTGQG22 |
| submissionUUID | String | Unique ID of the submission tht document was part of | XYE60M8ENDWA7V9TKBXBTGQG10 |
| longId | String | Unique long temporary Id that can be used to query document data anonymously | YQH73576FY9VR57B… |
| publicUrl | String | Public URL which can be used to access document anonymously. Note: sharing this URL will grant read access to the document. | https://{baseUrl}/{uuid}/share/{longId} |
| internalId | String | Internal ID used in submission for the document | PZ-234-A |
| typeName | String | Unique name of the document type that can be used in submission of the documents. Possible values: ‘i’ [invoice], ‘c’ [credit note], ‘d’ [debit note], ‘ii’ [import invoice], ‘ei’ [export invoice], ‘ec’ [export credit note], ‘ed’ [export debit note] | i |
| typeVersionName | String | Name of the document type version within the document type that can be used in document submission to identify document type version being submitted | 1.0 |
| issuerId | String | Registration number of issuer | 927398557 |
| issuerName | String | Issuer company name | My company |
| issuerType | String | Document issuer type (‘B’ [Business], ‘F’ [Foreigner]) | B |
| receiverId | String | Optional: receiver registration number (can be national ID or foreigner ID). | 087377381 |
| receiverName | String | Optional: receiver name (can be company name or person’s name) | Their company |
| receiverType | String | Document receiver type (‘B’ [Business], ‘F’ [Foreigner], ‘P’ [Person]) | B |
| dateTimeIssued | DateTime | The date and time when the document was issued. | 2015-02-13T13:15Z |
| dateTimeReceived | DateTime | The date and time when the document was submitted. | 2015-02-13T14:20Z |
| totalSales | Decimal | Total sales amount of the document in EGP. | 10.10 |
| totalDiscount | Decimal | Total discount amount of the document in EGP. | 50.00 |
| netAmount | Decimal | Total net amount of the document in EGP. | 100.70 |
| total | Decimal | Total amount of the document in EGP. | 124.09 |
| status | String | Status of the document - “Submitted”, “Valid”, “Invalid”, “Rejected”, “Cancelled” | Valid |
| cancelRequestDate | Date | Refer to the document cancellation request that has been initiated by the taxpayer “issuer” of the document on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| rejectRequestDate | Date | Refer to the document rejection request that has been initiated by the taxpayer “receiver” of the document on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| cancelRequestDelayedDate | Date | Refer to the date when this document will be marked as cancelled if the receiver taxpayer didn’t decline the cancellation request that was raised by issuer taxpayer, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| rejectRequestDelayedDate | Date | Refer to the date when this document will be marked as rejected if the issuer taxpayer didn’t decline the rejection request that was raised by receiver taxpayer, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| declineCancelRequestDate | Date | Refer to the decline cancellation request that has been initiated by the receiver taxpayer on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| declineRejectRequestDate | Date | Refer to the decline rejection request that has been initiated by the issuer taxpayer of the document on the system, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| documentStatusReason | String | Optional: Reason of the cancellation or rejection of the document. | Wrong invoice details |
| createdByUserId | String | User created the document. Can be ERP ID or User Email | someone@mycompany.com |
| freezeStatus | Freeze Status | Information about the Freeze status of the document | See structure |
| lateSubmissionRequestNumber | String | Optional: Late submission request identifier. Used to identify which late request no. used when submitting the document. | 927398557-23-1585 |
Freeze Status
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| frozen | Boolean | Flag to indicate if the document is frozen | false |
| type | Number | Indicates the current freeze type on the document after performing the Unfreeze operation (0/null:Unfreezed, 1:Temporary Freeze, 2:Permanent) | 1 |
| scope | Number | Indicates the current freeze scope on the document (0/null:not-set, 1:Full, 2:Cancellation) | 1 |
| actionDate | Date | Refer to the date when the last Freeze or Unfreeze action took place, will be in UTC format | 2021-02-25T01:59:10.2095172Z |
| auCode | string | Accounting Unit Code | 13300101 |
| auName | string | Accounting Unit Name | Supreme Council for Media Regulation |
Metadata
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| continuationToken | string | Token returned when there are more results to be retrieved, used to navigate to next page. When there are no more results, value returned is ‘EndofResultSet’ | 1674529517710| Y4RWK9617T0TJNRBF4CSVGQG10 |
Throttling and Rate limiting
To allow consistent performance for all taxpayers using eInvoicing API and prevent overuse of resources, this API has throttling limits set per taxpayer (current configuration is 1 Request every 2 Seconds). Subject to change by eInvoicing system administrators.
See the standard error response for more details when your calls to the API are throttled.
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 |
|---|---|---|
| 403 | forbidden | Returned when caller of the endpoint is trying to query recent documents while caller profile has ‘B2B Deny ERP Document Retrieval’ tag assigned to it by ETA Admin. |
Additional considerations
Days difference between submissionDateFrom and submissionDateTo filter parameters, and issueDateFrom and issueDateTo filter parameters are currently configured to 30 days. Days difference value can be changed by eInvoicing system administrators.
There are no maximum number of documents that can be returned by this endpoint. You can use the various optional filters to get the desired documents results.
For data extraction there is another asynchronous API available that allows document packages to be prepared for extraction.
Receiver of the documents can retrieve documents that are in statuses Valid, Rejected or Cancelled. If document exists, and is issued to given receiver, but status is Submitted or Invalid, document will not be part of the response. Issuer of the documents can retrieve documents in any status.