Search Documents

API allows taxpayer systems to search the documents sent or received which are available on the eInvoicing solution using various filters.

Get Recent Documents Request Document Package

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.