Overview
Important Note! This API has a newer replacement Search Documents API with better performance, various filter options, and no restrictions on the returned records count. Current "Get Recent Documents" API will be subject to more limits in terms of maximum number of records returned and throttling limits in the near feature. Our recommendation is to upgrade your integration from "Get Recent Documents" API to Search Documents API.
Get recent documents allows users to query the system and return list of documents that have been recently received or issued to that they can be reviewed, downloaded (through a separate call to Get Document Printout API for example).
System limits the number of the documents that can be received in one request by implementing paging mechanism for this API and also by not allowing to request documents that are issued more than configured days ago. To export older documents, use Request Document Package API.
List is ordered based on registration date of the submission descending.
Signature
API is REST based API that takes optional URL parameters to enable paging.
Signature:
GET /api/v1.0/documents/recent?pageNo={pageNo}&pageSize={pageSize}&submissionDateFrom={submissionDateFrom}&submissionDateTo={submissionDateTo}&issueDateFrom={issueDateFrom}&issueDateTo={IssueDateTo}&direction={direction}&status={status}&documentType={documentType}&receiverType={receiverType}&receiverId={receiverId}&issuerType={issuerType}&issuerId={issuerId}
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 documents to retrieve per page. Page size cannot exceed system configured maximum page size for this API | 20 |
| 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 | 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 | 2022-12-22T23:59:59 |
| issueDateFrom | DateTime | Optional: The start date and time when the document was issued. Mandatory when ‘issueDateTo’ is provided | 2021-02-25T23:55:10 |
| issueDateTo | DateTime | Optional: The end date and time when the document was issued. Mandatory when ‘issueDateFrom’ is provided | 2021-03-10T01:59:10 |
| direction | Text | Optional: direction of the document. Possible values: (‘Sent’, ‘Received’) | 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 |
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 about the results retrieved or results matching the query | 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 reuest 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 |
|---|---|---|---|
| totalPages | Number | Total count of pages based on the supplied (or default) page size | 23 |
| totalCount | Number | Total count of matching objects | 157 |
| queryContainsCompleteResultSet | Boolean | Flag indicates if the provided filters for the query return more records than the maximum number of documents that can be returned. When ‘false’ caller might need to use more targeted filters to get complete result set. | false |
| remainingRecordsCount | Number | Remaining number of records which exceeds the maximum number of documents that can be returned. When ‘0’ provided filters for the query return all results. | 1500 |
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
API is limited to retrieve only certain maximum number of documents and to query only certain “time window” of the documents to prevent huge queries to be executed. These maximum parameters are defined by eInvoicing system administrators.
Time window is a configurable parameter configured by ETA. Current configuration is 30 days.
The maximum number of documents that can be returned by this endpoint is 10,000 documents. 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.