Overview
Debit note is the document type used to change the amounts of previously issued invoice(s) that have been registered in eInvoicing solution. This document type is registered with the Tax Authority.
Data Structure
Core
The data structure of the debit note v1.0 documents follows the structure of the Invoice v1.0 and has a single document element.
Debit Note has additional references to prior documents and has validation restrictions to ensure that debit note is changing the amounts of referenced documents only.
Note that this description defines the data structure while actual attribute naming could be different for JSON and XML data structures.
| Element |
Type |
Description |
Value example |
| issuer |
Issuer |
Structure representing the issuer information. |
|
| receiver |
Receiver |
Structure representing the receiver |
|
| documentType |
String |
Document type name. Must be d for debit note. |
d |
| documentTypeVersion |
String |
Document type version name. Must be 1.0 for this version. |
1.0 |
| dateTimeIssued |
Date |
The date and time when the document was issued. Date and time cannot be in future. Time to be supplied in UTC timezone. |
2015-02-13T13:15:00Z |
| taxpayerActivityCode |
String |
Tax activity code of the business issuing the document representing the activity that caused it to be issued. Must be valid activity type code. |
9478 |
| internalId |
String |
Internal document ID used to link back to the ERP document number. Value defined by the submitter. |
AZ-24883 |
| purchaseOrderReference |
String |
Optional: reference to purchase order that this document is related to. |
P-233-A6375 |
| purchaseOrderDescription |
String |
Optional: Additional information about the purchase order provided to the recipient of the document. |
|
| salesOrderReference |
String |
Optional: Reference to the previous sales order for informational purposes. |
828874-023/233 |
| salesOrderDescription |
String |
Optional: Additional information about the sales order provided to the recipient of the document. |
|
| proformaInvoiceNumber |
String (max 50) |
Optional: Reference to the previous proforma invoice. |
2020A-012 |
| references |
String[] |
Optional: Array of document references/UUIDs to previous invoices for which debit note is being issued. |
S98L2CP1SMVBIU |
| payment |
Payment |
Optional: Structure containing fields providing information on how payments needs to be made. |
See structure. |
| delivery |
Delivery |
Optional: Structure containing fields providing information on how the delivery of goods |
See structure. |
| invoiceLines |
Invoice Line[] |
Invoice lines of the invoice. Needs to have at least one invoice line. |
See structure. |
| totalSalesAmount |
Decimal |
Sum all all InvoiceLine/SalesTotal items |
8873.29765 |
| totalDiscountAmount |
Decimal |
Total amount of discounts: sum of all Discount amount elements of InvoiceLine items. |
663.98723 |
| netAmount |
Decimal |
TotalSales – TotalDiscount |
8183.28763 |
| taxTotals |
Tax Total[] |
Totals per tax type. |
See structure. |
| extraDiscountAmount |
Decimal |
Additional discount amount applied at the level of the overall document, not individual lines. |
12.87650 |
| totalItemsDiscountAmount |
Decimal |
Total amount of item discounts: sum of all Item Discount amount elements of InvoiceLine items. |
663.28763 |
| totalAmount |
Decimal |
Total amount of the invoice calculated as NetAmount + Totals of tax amounts. 5 decimal digits allowed. |
8934.76800 |
| signatures |
Signature[] |
Structure containing one or two digital signatures. At least signature of the Issuer must be present. Signature of the Service provider is optional. |
See structure. |
Issuer
| Element |
Type |
Description |
Value example |
| type |
String |
Type of the issuer - supported values - B for business in Egypt, P for natural person, F for foreigner. Note that P and F are reserved values for future use. |
B |
| id |
String |
Registration number. For business in Egypt must be registration number. |
10201020102 |
| name |
String |
Registration name of the company. |
My company |
| address |
Address |
Address structure of the issuer branch including branch code. |
See the structure |
Issuer Address
| Element |
Type |
Description |
Value example |
| branchId |
String |
Mandatory when issuer is of type B, otherwise optional. The code of the branch as registered with tax authority for the company submitting the document. |
1234 |
| country |
String |
Country represented by ISO-3166-2 2 symbol code of the countries. Must be EG for internal business issuers. |
EG |
| governate |
String |
Governorate information as textual value |
Giza Governorate |
| regionCity |
String |
Region and city information as textual value |
Dokki |
| street |
String |
street information |
17 Nabil Al Wakad |
| buildingNumber |
String |
building information |
17 |
| postalCode |
String |
Optional: Postal code |
|
| floor |
String |
Optional: the floor number |
|
| room |
String |
Optional: the room/flat number in the floor |
|
| landmark |
String |
Optional: nearest landmark to the address |
|
| additionalInformation |
String |
Optional: any additional information to the address |
|
Receiver
| Element |
Type |
Description |
Value example |
| type |
String |
Type of the issuer - supported values - B for business in Egypt, P for natural person, F for foreigner. |
B |
| id |
String |
Registration number. For business in Egypt must be registration number. For residents must be national ID. For foreign buyers must be VAT ID of the foreign company. Optional if person buyer and invoice amount less than threshold limit defined. Receiver and issuer cannot be the same. |
10201020102 |
| name |
String |
Registration name of the company or name and surname of the person. Optional if person buyer and invoice amount less than threshold limit defined. |
My company |
| address |
Address |
Address of the receiver. Optional if person buyer and invoice amount less than threshold limit defined. |
See the structure |
Receiver Address
| Element |
Type |
Description |
Value example |
| country |
String |
Country represented by ISO-3166-2 2 symbol code of the countries. Must be EG for internal business issuers. |
EG |
| governate |
String |
Governorate information as textual value |
Giza Governorate |
| regionCity |
String |
Region and city information as textual value |
Dokki |
| street |
String |
street information |
17 Nabil Al Wakad |
| buildingNumber |
String |
building information (number, name or both) |
17 |
| postalCode |
String |
Optional: Postal code |
|
| floor |
String |
Optional: the floor number |
|
| room |
String |
Optional: the room/flat number in the floor |
|
| landmark |
String |
Optional: nearest landmark to the address |
|
| additionalInformation |
String |
Optional: any additional information to the address |
|
Payment
| Element |
Type |
Description |
Value example |
| bankName |
String |
Optional: Name of the bank of document issuer. |
Alpha Bank |
| bankAddress |
String |
Optional: Address of the bank of document issuer. Captured as single line of text, not a structure. |
|
| bankAccountNo |
String |
Optional: Local bank account number in the bank |
12-1982939 |
| bankAccountIBAN |
String |
Optional: International bank account number used primarily for international documents. |
|
| swiftCode |
String |
Optional: International Swift code of the bank. |
|
| terms |
String |
Optional: Description of the payment terms describing when and how payments needs to be made, for example. |
|
Delivery
| Element |
Type |
Description |
Value example |
| approach |
String |
Optional: Information on the approach for delivery used, means of transportation. |
|
| packaging |
String |
Optional: Information on types of packages used when delivering the goods |
|
| dateValidity |
String |
Optional: Validity date for exported products. |
2015-02-13T13:15:00Z |
| exportPort |
String |
Optional: Port exporting the goods. |
|
| countryOfOrigin |
String |
Optional: Country of origin of goods/services. Country represented by ISO-3166-2 2 symbol code of the countries. |
SA |
| grossWeight |
Decimal |
Optional: Total weight of the goods delivered. Value in kilograms. |
9929.00000 |
| netWeight |
Decimal |
Optional: Net weight of the goods delivered. Value in kilograms. |
9400.00000 |
| terms |
String |
Optional: Delivery terms/shipping terms information. |
|
Invoice Line
| Element |
Type |
Description |
Value example |
| description |
String |
Description of the item being sold. |
One ton of Aria apples. |
| itemType |
String |
Coding schema used to encode the item type. Must be GS1 or EGS for this version. |
GS1 |
| itemCode |
String |
Code of the goods or services item being sold. GS1 codes targeted for managing goods, EGS codes targeted for managing goods – goods or services. |
10003752 |
| unitType |
String |
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. |
4.44444 |
| unitValue |
Value |
The structure defining the price of a single unit sold. |
See structure. |
| salesTotal |
Decimal |
Total amount for the invoice line considering quantity and unit price in EGP (with excluded factory amounts if they are present for specific types in documents). |
23.67657 |
| total |
Decimal |
Total amount for the invoice line after adding all pricing items, taxes, removing discounts. |
455.18652 |
| valueDifference |
Decimal |
Value difference when selling goods already taxed (accepts +/- numbers), e.g., factory value based. |
10.08764 |
| totalTaxableFees |
Decimal |
Total amount of additional taxable fees to be used in final tax calculation. |
1.22876 |
| netTotal |
Decimal |
Total amount for the invoice line after applying discount. |
23.67765 |
| itemsDiscount |
Decimal |
Non-taxable items discount. |
12.87622 |
| discount |
Discount |
Optional: the structure defining the discount applied on a single unit sold. |
See structure |
| taxableItems |
Taxable Item[] |
Optional: List of taxable items. Can have zero or more of supported tax items below from the list of all tax types including VAT, WHT and table tax, local authority fees (municipality), development. |
See structure. |
| internalCode |
String |
Optional: Internal code used for the product being sold – can be used to simplify references back to existing solution. |
8383S |
Value
| Element |
Type |
Description |
Value example |
| currencySold |
String |
Currency code used from ISO 4217. |
EGP |
| amountEGP |
Decimal |
Price of unit of goods/services sold in EGP. Should be valid decimal with max 5 decimal digits. Value rounded to 5 decimal digits if calculated using currency sold and exchange rate. |
1.27861 |
| amountSold |
Decimal |
Mandatory if currencySold <> EGP. Should not have value otherwise |
1.27891 |
| currencyExchangeRate |
Decimal |
Exchange rate of the Egyptian bank on the day of invoicing used to convert currency sold to the value of currency EGP. Mandatory if currencySold is not EGP. Should be valid decimal with max 5 decimal digits. |
1.92992 |
Discount
| Element |
Type |
Description |
Value example |
| rate |
Decimal |
Optional: discount percentage rate applied. Must be from 0 to 100. |
5.00 |
| amount |
Decimal |
Optional: amount of discount provided to customer for this item. Should be smaller or equal to value Total. If percentage specified should be valid amount calculated from total by applying discount percentage. Value with the precision of 5 decimal digits. |
10.00000 |
Taxable Item
| Element |
Type |
Description |
Value example |
| taxType |
String |
Type of tax applied - from the list of approved tax type codes. The TaxType needs to be unique across the invoice line (no VAT twice in one invoice line), TaxType is from the list of supported tax types. |
123 |
| 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 5 |
2.00000 |
| subType |
String |
Subtype of the tax type that might mean exemption rate is applied or specific rate linked to product type being sold is applied. |
|
| rate |
Decimal |
Tax rate applied for the invoice line. Value from 0 to 999. |
2.00 |
Tax Total
| Element |
Type |
Description |
Value example |
| taxType |
String |
Type of tax applied - from the list of approved tax type codes. The TaxType needs to be unique across the invoice line (no VAT twice in one invoice line), TaxType is from the list of supported tax types. |
123 |
| amount |
Decimal |
Sum of all amounts of given tax in all invoice lines. 5 decimal digits allowed. |
838.13876 |
Signature
| Element |
Type |
Description |
Value example |
| type |
String |
Type of the signature: Issuer (I), ServiceProvider (S) |
I |
| value |
String |
Signature value that contains CADES-BES structure containing signer certificate, hash value signed and actual signature value. |
Base64 encoded string |
Additional Considerations
Debit Note Restrictions
When creating debit notes submitters need to consider these restrictions:
- the structure of the receiver and issuer should not be changed
- the taxpayer activity code reference should not be changed
- referenced invoices (if multiple) all should be issued by the submitter taxpayer
- referenced invoices (if multiple) all should be issued for the same recipient
- referenced invoices should be issued before issuance date of the debit note
- the invoice lines in the debit note should be the same as in the combination of all invoices referenced - only quantities and amounts can be changed
Signature Creation
Signed content is entire Document structure except signature section for I signature type and entire structure + previous I signature for S type of signature. SHA256 hashing used for creating hash of the elements to sign.
More details on how to define structure of the document to hash, create canonical version, apply hashing, sign the hash and then embed the signature are provided in section Signature Creation.
Signature Validation
The validation rules for signatures are:
- Base64 encoded value that is a valid CADES-BES structure.
- CADES-BES signing certificate is valid at the date of submission of document for validation.
- Signing certificate is issued to:
- issuer of the document, i.e., taxpayer registration number matches in certificate and document,
- person representative who is active representative of taxpayer at the document issuance date and time.
- CADES-BES signature is valid RSA signature created using one of the approved eSeal or natural person signature certificates in Egypt.