Get Receipt

API allows taxpayers to retrieve receipt/return receipt source JSON with additional tax authority added metadata.

Get Receipt Details Get receipt details anonymously

Overview

API allows caller to get full details of the Receipt when requested by unique ID assigned to receipt by eInvoicing & eReceipt solution.

Details include original JSON submission and additional ID and validation details, current status added by the tax authority. Because document is submitted in JSON, this API returns receipt information in JSON.

Signature

API is REST based API that takes unique ID of the document as URL parameter and returns document details that were received from the issuer and additional details added after registration and validation of the document in the tax authority.

Signature: GET /api/v1/receipts/{uuid}/raw

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
uuid UUID Unique ID of the document to retrieve. 68e656b251e67e835…

Outputs

Successful Response

API returns HTTP status code 200.

The resulting structure is a single object of type ReceiptExtended.

Document Extended contains:

Output parameter Type Description Value example
rawDocument String Document in raw format  
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 Document Type 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 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. amounts 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 Optional, 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) Name of Activity Code 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 Egyptian Museum
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 GS1: 6221218058490, EGS: EG-113317713-1234
unitType String (30) 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) Mandatory, 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 received and cancelled status.