Overview
API allows caller to get full details of the receipt when requested by unique ID assigned to the receipt by eReceipt solution, including the detailed validation results and any associated return receipts linked to the sales receipts.
Signature
API is REST based API that takes unique ID of the receipt as URL parameter and returns receipt details that were received from the issuer and additional details added after registration and validation of the receipt in the tax authority.
Signature:
GET /api/v1/receipts/{uuid}/details
Inputs
This API accepts standard eInvoicing & eReceipt API header parameters for authenticated call.
| URL parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | String(64) | Unique ID of the receipt to retrieve. | 68e656b251e67e835… |
| dateTimeIssued | DateTime | The date and time when the receipt was Issued . | 2015-02-13T13:15Z (datetime format would be yyyy-mm-dd and time zone would be UTC.) |
Document can be either:
- Receipt - Receipt is the document issued by the taxpayer for the good or service purchased by customer.
- Return Receipt - Return Receipt is a document issued by the taxpayer for the purchase goods or service that are returned by the customer
- Return Receipt Without Reference - Return Receipt Without Reference is a document issued by the taxpayer for the purchase goods or service that are returned by the customer for international return receipts or return receipt that are referencing sales receipts that are not captured on the system..
Outputs
Successful Response
API returns HTTP status code 200.
The resulting structure is a single object of type ReceiptDetails.
Receipt Details contains:
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| submissionUUID | String (30) | Unique ID of the submission tht document was part of | JU7GH07JNA23N |
| dateTimeReceived | DateTime | The date and time when the document was submitted. | 2015-02-13T14:20Z |
| dateTimeIssued | DateTime | The date and time when the document was submitted. | 2015-02-13T14:20Z |
| submissionChannel | String, Submission Channels | The channel through which receipt submission was made. | POS |
| maxPrecision | Decimal | maximum precision value of decimal fields | 3 |
| receipt | Document Summary | Document object depending on the type | See structure. |
Document Summary
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| uuid | UUID | Unique document ID in eInvoicing and eReceipt | 68e656b251e67e835… |
| longId | String (200) | Long document ID | BFNGXFA17265TQX34… |
| previousUUID | UUID | Reference to previous receipt | 68e656b251e67e835… |
| referenceOldUUID | UUID | This is used for the resent receipt case in case of validation failure and requirement to change something in the receipt and resend it with a different UUID. | 68e656b251e67e835… |
| referenceUUID | UUID | This field is present only for return receipt as it represents reference UUID of sales receipt | 68e656b251e67e835… |
| 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 |
| receiptNumber | String (50) | Number of the receipt | 12345678 |
| currency | String (3) | Currency code used from ISO 4217, Currency Codes | EGP |
| exchangeRate | Decimal | Exchange rate | 0.12345 |
| sOrderNameCode | String (200) | Order name code | ABC12345 |
| orderdeliveryMode | String (30) | Delivery mode | AIR |
| grossWeight | Decimal | Gross weight | 12.12345 |
| netWeight | Decimal | Net weight | 12.12345 |
| documentType | documentType | Structure representing the documentType information. | See structure. |
| totalSales | Decimal | sum of all sales total elements of receipt lines | 1921.12345 |
| totalAmount | Decimal | totalAmount = sum of all receipt line total – total extraDiscountAmount | 19281.12345 |
| totalCommercialDiscount | Decimal | sum of all discount amount elements of receipts lines | 12.12345 |
| totalItemsDiscount | Decimal | sum of all itemsDiscountAmount elements of receipt lines | 12.12345 |
| netAmount | Decimal | Sum of all receipt lines netTotal | 19271.12345 |
| feesAmount | Decimal | Is the additional fees amount of receipt level | 0.0 |
| paymentMethod | String (50) | Payment Method Codes | C |
| adjustment | Decimal | monetary amount that will be added to the total of the receipt to perform final adjustments to the total amount of the receipt. | 0.0 |
| seller | seller | Structure representing the seller information. | See structure. |
| buyer | buyer | Structure representing the buyer information. | See structure. |
| itemData | ItemData | This would be collection of objects .Structure representing the itemData information. | See structure. |
| extraReceiptDiscount | Array of discount | This would be collection of objects of extra receipt level discount. | See structure. |
| taxTotals | TaxTotals | Structure representing the total tax information. | See structure. |
| contractor | Contractor | Structure representing the contractor information. | See structure. |
| beneficiary | Beneficiary | Structure representing the beneficiary information. | See structure. |
| status | String (250) | Status of the document | valid |
| statusReason | String (250) | Status reason of the document | |
| hasReturnReceipts | Boolean | return receipts availability flag. | True / False |
| returnReceipts | Array of ReturnReceipt | Structure representing the return receipt information. | See structure. |
| history | ReceiptHistory | Optional. Structure representing the receipt history information. | See structure. |
DocumentType
| Element | Type | Description | Value example |
|---|---|---|---|
| receiptTypeCategory | String (100) | Category for receipt type | Receipt |
| receiptTypeBase | String (100) | It is the receipt base type, its value is either SR or RR | SR |
| receiptType | String (20) | the Value must be ‘s’ for Sale Receipt and ‘r’ for return receipt | s |
| receiptTypeName | String (100) | Type name | Sale Receipt |
| receiptTypeNameAr | String (100) | Type name in Arabic | إيصال البيع |
| typeVersion | String (100) | Document type version | 1.0 |
Seller
| Element | Type | Description | Value example |
|---|---|---|---|
| sellerId | String (30) | Registration number. For business in Egypt must be registration number | 200173707 |
| sellerName | String (200) | Registration name of the seller. | ABC Corp |
| branchCode | String (50) | The code of the branch as registered with tax authority for the company submitting the document | 0 |
| deviceSerialNumber | String (100) | This is the POS serial number | 123 |
| syndicateLicenseNumber | String (30) | It is number in case if it is person and “C” in case if it is a professional | 123 |
| activityCode | String (10) | Activity Codes | 123 |
| branchAddress | BranchAddress | Structure representing the branchAddress information. | See structure. |
| branchName | String (100) | Name of Branch | Branch 1 |
| branchNameAr | String (100) | Name of Branch in Arabic | فرع 1 |
BranchAddress
| Element | Type | Description | Value example |
|---|---|---|---|
| country | String (2) | Country represented by ISO-3166-2 2 symbol code of the countries. | EG |
| governate | String (100) | Governorate information as textual value | Giza Governorate |
| regionCity | String (100) | Region and city information as textual value | Dokki |
| street | String (200) | Street information | 17 Nabil Al Wakad |
| buildingNumber | String (100) | Building information (number, name or both) | 17 |
| postalCode | String (30) | Postal code | 11311 |
| floor | String (100) | The floor number | 1 |
| room | String (100) | The room/flat number in the floor | 3 |
| landmark | String (500) | Nearest landmark to the address | Egyptian Museum |
| additionalInformation | String (500) | Any additional information to the address | ABC |
| countryName | String (250) | Name of Country | Egypt |
| countryNameAR | String (250) | Name of Country in Arabic | مصر |
Buyer
| Element | Type | Description | Value example |
|---|---|---|---|
| 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) | Registration name of the company or name and surname of the person | ABC |
| type | String (1) | Type of the issuer - supported values - B for business in Egypt, P for natural person, F for foreigner | B |
| mobileNumber | String (30) | Mobile number of receiver | +201020567362 |
| paymentNumber | String (30) | a reference to a payment number for which the receipt was issued, this is used for specialized industries that have such reference numbers such as utilities bill for example. It can alternatively contain a reference to the payment method reference such as authorization code in case of credit card payment. | 123 |
ItemData
| Element | Type | Description | Value example |
|---|---|---|---|
| internalCode | String (50) | Internal code is used for the product being sold – can be used to simplify references back to existing solution. | 8806092129306 |
| description | String (500) | Description of the item being sold | Samsung A02 32GB*LTE_BLACK_DS_SM-A022FZKDMEB_A022 * A022_SM-A022FZKDMEB |
| itemType | String (30) | Coding schema used to encode the item type. Must be GS1 or EGS for this version | GS1 |
| itemCode | String (100) | Code of the goods or services item being sold. GS1 codes targeted for managing goods, EGS codes targeted for managing goods – goods or services | 10007020 |
| unitType | String (100) | Code of the unit type used from the code table of the measures | kg |
| quantity | Decimal | Number of units of the defined unit type being sold. Number should be larger than 0. | 17.12345 |
| unitPrice | Decimal | Price per unit. | 17.12345 |
| netSale | Decimal | Total amount for the receipt line after applying discount. | 36.12345 |
| totalSale | Decimal | sum of all sales total elements of receipt lines | 425.12345 |
| total | Decimal | Total amount for the receipt line after adding all pricing items, taxes, removing discounts | 460.12345 |
| valueDifference | Decimal | Value difference when selling goods already taxed (accepts +/- numbers), e.g., factory value based | 0.12345 |
| commercialDiscount | Array of discount | Optional, This would be collection of objects of commercial discounts applied to this item. | See structure. |
| itemDiscount | Array of discount | Optional, This would be collection of objects of non-taxable items discounts. | See structure. |
| additionalCommercialDiscount | discount | Optional, Additional commercial discount after net sale on the item level | 10.0 |
| additionalItemDiscount | discount | Optional, Additional item discount after net sale on the item level | 10.0 |
| taxableItems | Array of TaxableItem | Structure representing the taxableItems information. | See structure |
| itemCodeName | String (250) | Item Code Name | Mobile Phone/Smartphone Accessories |
| itemCodeNameAr | String (250) | Item Code Name in Arabic | اكسسوارات الهاتف المحمول / الهواتف الذكية |
| unitTypeName | String (250) | Unit Type Name | Kilogram |
| unitTypeNameAr | String (250) | Unit Type Name in Arabic | كيلوغرام |
Discount
| Element | Type | Description | Value example |
|---|---|---|---|
| amount | Decimal | Mandatory, amount of the discount applied | 100.12345 |
| description | String (50) | Mandatory, description of the discount applied | ABCD12345 |
| rate | Decimal | Optional, Tax rate applied for the invoice line. Value from 0 to 100. If 0 value is provided then the amount will take precedence | 1.12 |
TaxableItem
| Element | Type | Description | Value example |
|---|---|---|---|
| taxType | String (30) | Type of tax applied - from the list of approved tax type codes. Tax Types. | T1-T20 |
| amount | Decimal | Amount of the tax applied, tax type defined type of tax applies to support different taxes that are possible depending on the type of sales, customer etc. Value with the precision of 2 | 2.12345 |
| subType | String (50) | Subtype of the Tax Types that might mean exemption rate is applied or specific rate linked to product type being sold is applied. | V001 |
| rate | Decimal | Tax rate applied for the invoice line. Value from 0 to 100. | 2.12 |
| sign | Integer | 1 for Sales, -1 for Return | 1 |
| exchangeRate | Decimal | Exchange rate | 0.12345 |
| taxTypeName | String (250) | Name of Tax Type in english | Value added tax |
| taxTypeNameAr | String (250) | Name of Tax Type in arabic | ضريبة القيمة المضافة |
TaxTotals
| Element | Type | Description | Value example |
|---|---|---|---|
| taxType | String (30) | Type of tax applied - from the list of approved tax type codes. | T1-T20 |
| amount | Decimal | Mandatory, Sum of all amounts of given tax in all line items. 5 decimal digits allowed. | 838.12345 |
| taxTypeName | String (250) | Name of Tax Type | Value added tax |
| taxTypeNameAr | String (250) | Name of Tax Type in Arabic | ضريبة القيمة المضافة |
Contractor
| Element | Type | Description | Value example |
|---|---|---|---|
| name | String (200) | Optional, Name of the Contractor | ABC CORP |
| amount | Decimal | Optional, this is the amount that the contractor is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. | 1536.12345 |
| rate | Decimal | Optional, this is the rate that the contractor is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. | 1.12 |
Beneficiary
| Element | Type | Description | Value example |
|---|---|---|---|
| amount | Decimal | Optional, this is the amount that the beneficiary or buyer is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. | 1536.12345 |
| rate | Decimal | Optional, this is the rate that the beneficiary or buyer is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. | 1.12 |
ReturnReceipt
| Element | Type | Description | Value example |
|---|---|---|---|
| uuid | String(64) | Unique ID of the return receipt. | 68e656b251e67e835… |
| dateTimeIssued | DateTime | The date and time when the return receipt was Issued. | 2015-02-13T13:15Z (datetime format would be yyyy-mm-dd and time zone would be UTC.) |
ReceiptHistory
| Element | Type | Description | Value example |
|---|---|---|---|
| date | DateTime | Date time of the receipt in history. | 2015-02-13T13:15Z (datetime format would be yyyy-mm-dd and time zone would be UTC.) |
| status | String | Status of the receipt in history. | Valid. |
| reason | String | Optional, status reason of the receipt in history. | |
| submissionUuid | String | Submission Uuid of the receipt in history. | |
| canceledBy | String | Optional, cancelled by of the receipt in history. |
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
Receiver of the receipts can retrieve receipts that are in statuses valid only. If receipt exists, and is issued to given receiver, but status is cancelled, not found code is returned.
Issuer of the receipt can retrieve receipt in valid and cancelled status.