Overview
API allows caller to get details of a single submission to check its processing status after initially submitting it and getting back unique submission identifier.
This API is available to submitter only as it might contain receipts issued to multiple receivers.
Signature
API is REST based API that takes unique ID of the submission as URL parameter and returns details of the submission and summary information of the receipts part of the submission.
Because submission might have quite some number of the receipts as part of it, list of the documents returned by this API is paged.
Signature:
GET /api/v1/receiptsubmissions/{submissionUuid}/details?DocumentId={DocumentId}&ReceiptNumber={ReceiptNumber}&DocumentTypeCode={DocumentTypeCode}&DocumentTypeName={DocumentTypeName}&DocumentTypeVersionNumber{DocumentTypeVersionNumber}&ReceiverId={ReceiverId}&ReceiverName={ReceiverName}&Status={Status}&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 |
|---|---|---|---|
| SubmissionUuid | String (30) | Mandatory, SHA256 format | 68e656b251e67e835… |
| DocumentId | UUID | Document Id of 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) |
| DocumentTypeName | String (100) | Name of Document Type | Receipt |
| DocumentTypeVersionNumber | String (100) | Version of Document Type | 1.0 |
| ReceiverId | String (30) | receiver registration number (can be national ID or foreigner ID). | 087377381 |
| ReceiverName | String (200) | receivers registration name | ABC |
| Status | String (250) | Status of the document - Valid, Invalid, Cancelled |
Valid |
| 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 |
|---|---|---|---|
| submissionuuid | String (30) | Unique document submission ID in eInvoicing | 68e656b251e67e835… |
| sellerId | String (30) | Registration number of seller | 927398557 |
| dateTimeReceived | DateTime | The date and time when the submission was received by eInvoicing & eReceipts. | 2015-02-13T14:20Z |
| dateTimeIssued | DateTime | The date and time when the document was issued. | 2015-02-13T13:15Z |
| submitterName | String (250) | Name of Submitter | Device1 |
| deviceSerialNumber | String (100) | Serial Number of POS | YV200T568 |
| submissionChannel | String, Submission Channels | The channel through which receipt submission was made. | POS |
| receiptsCount | Number | Number of receipts in submission | 10 |
| invalidReceiptCount | Number | Number of invalid receipts in submission | 10 |
| status | String (250) | Overall status of the batch processing. Values: InProgress, Valid, Invalid |
Valid |
| submissionErrors | Submission Error | List of errors for particular submission | See structure. |
| 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 |
|---|---|---|---|
| uuid | UUID | Unique document ID in eInvoicing and eReceipt | 68e656b251e67e835… |
| receiptNumber | String (50) | Number of the receipt | ‘ZHFGG221’ |
| 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 received. | 2015-02-13T13:15Z |
| documentType | String (20) | Unique name of the document type that can be used in submission of the documents. | s (for receipt), r (for return receipt) |
| documentTypeNamePrimaryLanguage | String (250) | Name of Document in Primary Language | Receipt |
| documentTypeNameSecondaryLanguage | String (250) | Name of Document in Secondary Language | |
| 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 | |
| documentTypeVersion | String (100) | 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 |
| totalAmount | Decimal | Total amount of the document | 124.12345 |
| exchangeRate | Decimal | Represents value of one currency for the purpose of conversion to another. | 0.93 |
| sellerId | String (30) | Registration number of seller | 927398557 |
| sellerName | String (200) | Seller company name | My company |
| buyerId | String (30) | National ID or Company Registration No (RIN) or Foreigner Identification Number | Based on type values can be as follows: 1.type is B: Company Registration No. (RIN) 2.type is P: National ID 3.type is F: Any type of Foreigner Identification Number |
| buyerName | String (200) | Buyer name (can be company name or person’s name) | Their company |
| buyerType | String (1) | Buyer type | B |
| status | String (250) | Status of the document - Valid, Invalid, Cancelled |
Valid |
| longId | String (200) | Unique long Id that was assigned by eInvoicing and eReceipt solution | BFNGXFA17265TQX34… |
| deviceSerialNumber | String (100) | POS device serial number | SN-123434 |
| errors | Document Summary Errors | list of errors | See structure. |
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 |
| currentPageNo | Number | Current page number | 1 |
Document Summary Errors
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| stepId | String (4) | Step Id | 20 |
| stepName | String (100) | Step Name | Step 04 |
| stepNameAr | String (100) | Step Name in Arabic | الخطوة 04 |
| error | Submission Error | Structure representing Submission errors | See structure. |
Submission Error
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| propertyPath | String | Property Path | $.itemData[*].taxableItems[*].taxType |
| errorCode | String (100) | Error Code | CV307 |
| error | String (4000) | Error Message | ItemCode [W001] doesn’t belong to ParentCode [T3] |
| errorAr | String (4000) | Errror Message in Arabic | ItemCode [W001] لا ينتمي إلى ParentCode [T3] |
| metadata | String | Metadata | |
| innerError | Submission Error | Structure representing Inner errors | See structure. |
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.
For more details please check Receipt Issuance FAQ.