Search Receipts

API allows representatives of the taxpayers to search for submitted receipts and return receipts.

Get Receipt Submission Get Recent Receipts

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.