Overview
Get recent documents allows users to query the system and return list of receipts that have been recently received or issued to that they can be reviewed.
System limits the number of the documents that can be received in one request by implementing paging mechanism for this API .
Signature
API is REST based API that takes optional URL parameters to enable paging.
Signature:
GET /api/v1/receipts/recent?Uuid={Uuid}&SubmissionUuid={SubmissionUuid}&ReceiptNumber={ReceiptNumber}&DocumentTypeCode={DocumentTypeCode}&DocumentTypeVersion={DocumentTypeVersion}&ReceiverName={ReceiverName}&ReceiverRegisterationNumber={ReceiverRegisterationNumber}&PosSerialNumber={PosSerialNumber}&PaymentMethod={PaymentMethod}&SubmissionChannel={SubmissionChannel}&Status={Status}&Direction={Direction}&SortBy={SortBy}&SortDir={SortDir}&PageNo={PageNo}&PageSize={PageSize}
Inputs
This API accepts standard eInvoicing & eReceipt API header parameters for authenticated call.
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| Uuid | UUID | Unique identifier of the receipt | 68e656b251e67e835… |
| SubmissionUuid | String (30) | Unique identifier of the submission | 68e656b251e67e835… |
| ReceiptNumber | String (50) | Receipt Number | 98e656b251 |
| DocumentTypeCode | String (20) | Unique code of the document type that can be used in submission of the documents. | s (for receipt), r (for return receipt) |
| DocumentTypeVersion | String (100) | Version of Document Type | 1.0 |
| ReceiverName | String (200) | Name of the receiver | ABC |
| ReceiverRegisterationNumber | String (30) | RIN of the receiver, this filter is only applicable if buyer type is B | 087377381 |
| DeviceSerialNumber | String (100) | Serial Number of POS | YV200T568 |
| PaymentMethod | String (50) | Payment Method Codes | C |
| submissionChannel | String, Submission Channels | The channel through which receipt submission was made. | POS |
| Status | String (250) | Status of the receipt - valid, cancelled |
valid |
| Direction | String | Represents whether the receipt is received or submitted | Received |
| 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 | 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 |
| firstReceiptDateTimeReceived | DateTime | The date and time of first receipt received by eInvoicing & eReceipts. | 2015-02-13T14:20Z |
| lastReceiptDateTimeReceived | DateTime | The date and time of last receipt received by eInvoicing & eReceipts. | 2015-02-13T14:20Z |
| maxRecordCount | Number | Max count of records | 157 |
| showReceiptsReceivedSinceMonthCount | Number | Count of receipts received in 1 month | 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.