Overview
Returns list of receipts and return receipts to representatives of the taxpayer that submitted the receipts.
This API enables search for recently submitted or recently received documents only.
Signature
Since there can be quite some number of receipts in the response, list of the receipts returned by this API is paged.
Signature:
GET /api/v1/receipts/search?FreeText={FreeText}&Direction={Direction}&DateTimeIssuedFrom={DateTimeIssuedFrom}&DateTimeIssuedTo={DateTimeIssuedTo}&DateTimeReceivedFrom={DateTimeReceivedFrom}&DateTimeReceivedTo={DateTimeReceivedTo}&DocumentTypeCode={DocumentTypeCode}&DocumentTypeVersion={DocumentTypeVersion}&ReceiverName={ReceiverName}&ReceiverRegisterationNumber={ReceiverRegistrationNumber}&PosSerialNumber={PosSerialNumber}&SubmissionChannel={SubmissionChannel}&SortBy={SortBy}&SortDir={SortDir}PageNo={PageNo}&PageSize={PageSize}
Inputs
This API accepts standard eInvoicing & eReceipt API header parameters for authenticated call. The content type parameter can define the expected output format - JSON .
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| FreeText | String (100) | Search by fragment or exact:• Receipt/Internal/Submission ID (minimum 5 characters),• Issuer Registration Number (minimum 5 characters) / Issuer Name (minimum 5 characters)• Receiver ID (minimum 5 characters) / Receiver Name (minimum 5 characters)• POS Serial Number (min 5 characters),• Issued Date (exact date, and no time),• Total Value (exact value including decimal precision symbols) | M7YU8897A* |
| Direction | String (10) | Represents whether the receipt is received or submitted | Received |
| DateTimeIssuedFrom | DateTime | Represents the start of the issuance date range | 2022-04-18T12:12:35.756Z |
| DateTimeIssuedTo | DateTime | Represents the end of the issuance date range | 2022-04-18T12:12:35.756Z |
| DateTimeReceivedFrom | DateTime | Represents the start of the received date range | 2022-04-18T12:12:35.756Z |
| DateTimeReceivedTo | DateTime | Represents the end of the received date range | 2022-04-18T12:12:35.756Z |
| DocumentTypeCode | String (20) | Code letter for different types of receipts | R, S |
| DocumentTypeVersion | String (100) | Version of the receipt type | 1.0 |
| ReceiverName | String (200) | Name of the receiver | abc |
| ReceiverRegisterationNumber | String (30) | RIN of the receiver, this filter is applicable only if buyer type is B. If buyer type is P or F use FreeText Field to filter by Receiver ID |
100034624 |
| PosSerialNumber | String (100) | Serial No. of the POS device | YV200T573 |
| submissionChannel | String, Submission Channels | The channel through which receipt submission was made. | POS |
| SortBy | String | Parameter value by which the results should be sorted | None, DateTimeIssued, DateTimeReceived |
| SortDir | String | Direction in which the results should be sorted | None, Asc, Desc |
| PageNo | Integer | Page no for which the results are required | 1 |
| PageSize | Integer | Number of records per page | 10 |
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is a single object containing the attributes as defined in the table:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| receipts | Document Summary[] | List of the retrieved batch documents in current page. | See structure. |
| metadata | Metadata | Information on object count. | See structure. |
Document Summary
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| submissionUuid | String (30) | Unique document submission ID in eInvoicing | 68e656b251e67e835… |
| uuid | UUID | Mandatory, SHA256 format | 68e656b251e67e835… |
| referenceUuid | UUID | This field is present only for return receipt as it represents reference UUID of sales receipt | 68e656b251e67e835… |
| direction | String (10) | Represents whether the receipt is received or submitted | none, all, received, submitted |
| receiptNumber | String (50) | Receipt Number | 98e656b251 |
| dateTimeIssued | DateTime | The date and time when the submission was issued by eInvoicing & eReceipts. | 2015-02-13T14:20Z |
| dateTimeReceived | DateTime | The date and time when the submission was received by eInvoicing & eReceipts. | 2015-02-13T14:20Z |
| totalAmount | Decimal | totalAmount = sum of all receipt line total – total extraDiscountAmount | 1000.00 |
| posSerialNumber | String (100) | Serial Number of POS | YV200T568 |
| paymentMethod | String (50) | Payment Method Codes | C |
| submitterName | String (250) | Name of Submitter | Device1 |
| submissionChannel | String, Submission Channels | The channel through which receipt submission was made. | POS |
| status | String (250) | Status of the document - valid, cancelled |
valid |
| issuerId | String (30) | Registration number of issuer | 927398557 |
| issuerName | String (200) | Name of issuer | abc |
| receiverId | String (30) | Registration number of receiver | 927398557 |
| receiverName | String (200) | Name of receiver | abc |
| typeName | String (100) | Type name | Sale Receipt |
| documentTypeNamePrimaryLanguage | String (250) | Name of Document in Primary Language | Receipt |
| documentTypeNameSecondaryLanguage | String (250) | Name of Document in Secondary Language | |
| typeVersionName | String (100) | Name of the receipt type version | 1.0 |
| currency | String (3) | Currency code | EGP |
| currencyNamePrimaryLang | String (250) | Name of currency in Primary Language | Egyptian Pound |
| currencyNameSecondaryLang | String (250) | Name of currency in Secondary Language | |
| exchangeRate | Decimal | Represents value of one currency for the purpose of conversion to another. | 0.93 |
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 |
Error Response
Error situations are reported back by this API through the standard error response.
No custom error codes are provided by this API.
Additional considerations
Maximum page size allowed is defined by eInvoicing & eReceipt system administrators. API is available to issuers that are querying their submissions. This also includes authorized intermediaries (service providers) who submitted the receipts on behalf of the taxpayer they represent.
Receipts can be retrieved for fixed duration. Default period is 1 month which is configurable
The maximum number of receipts that can be returned by this API is 3,000 (configurable)
For more details please check Receipt Issuance FAQ.