Fiscal Device Gateway API v4.2 - Clients-Dual-Translated

FISCAL DEVICE GATEWAY API
SPECIFICATION
Doc. No. v4.2

CONTENTS
Contents ................................................................................................. 2
1. Fiscal Device Gateway usage scenarios ....................................................... 4
1.1. Device registration ................................................................ 4
1.2. Fiscal device communication modes ........................................... 4
1.3. Fiscal day (in online mode) ...................................................... 5
1.4. Fiscal day (in offline mode) ...................................................... 6
2. Object statuses .................................................................................... 7
2.1. Fiscal day statuses ................................................................. 7
3. Fiscal Device Gateway API interfaces ......................................................... 8
3.1. verifyTaxpayerInformation ...................................................... 8
3.2. registerDevice ...................................................................... 8
3.3. issueCertificate .................................................................... 9
3.4. getConfig .......................................................................... 10
3.5. getStatus .......................................................................... 11
3.6. openDay ........................................................................... 12
3.7. submitReceipt .................................................................... 13
3.8. submitFile ......................................................................... 18
3.8.1. File example.................................................................... 20
3.9. getFileStatus ...................................................................... 21
3.10. closeDay ........................................................................... 21
3.11. getServerCertificate ............................................................ 22
3.12. ping ................................................................................. 23
4. Data Types ........................................................................................ 24
4.1. Address ............................................................................ 24
4.2. Contacts ........................................................................... 24
4.3. SignatureData .................................................................... 24
4.4. Enums .............................................................................. 24
4.4.1. DeviceOperatingMode ......................................................... 24
4.4.2. FiscalDayStatus ................................................................ 24
4.4.3. FiscalDayReconciliationMode ................................................ 25
4.4.4. FiscalCounterType ............................................................. 25
4.4.5. MoneyType...................................................................... 25
4.4.6. ReceiptType .................................................................... 25
4.4.7. ReceiptLineType ............................................................... 25
4.4.8. ReceiptPrintForm .............................................................. 26
4.4.9. FiscalDayProcessingError ..................................................... 26
4.4.10. FileProcessingStatus ......................................................... 26
4.4.11. FileProcessingError........................................................... 26
5. Fiscal counters ................................................................................... 27
6. Integration Setup Requirements.............................................................. 28
6.1. Communication and security protocols ...................................... 28
6.2. Environment addresses ......................................................... 28
6.3. Authentication and authorization ............................................ 28
6.4. Timeout Settings ................................................................. 28
7. Errors .............................................................................................. 29
7.1. Http statuses...................................................................... 29
7.2. Error codes........................................................................ 29
7.3. Validation errors ................................................................. 30
8. Requirements for fiscal devices .............................................................. 32
9. Standard fiscal receipt, invoice and report views ........................................ 34
Fiscalisation Back-end Solution for ZIMRA 2 of 59

9.1. Receipt48 view ................................................................... 34
9.2. InvoiceA4 view ................................................................... 36
9.3. Receipt and invoice view fields descriptions ............................... 37
9.4. Z Report / X Report .............................................................. 41
9.5. Z report and X report fields description .................................... 42
10. Receipt QR code rules .......................................................................... 45
11. Certificate signing request (CSR) and Certificate examples ............................. 46
11.1. Example keys used .............................................................. 46
11.1.1. ECC ECDSA on SECG secp256r1 ............................................. 46
11.1.2. RSA 2048 ....................................................................... 46
11.2. CSRs and Certificates ........................................................... 48
11.2.1. ECC ECDSA on SECG secp256r1 ............................................. 48
11.2.1.1. CSR ........................................................................ 48
11.2.1.2. Certificate ............................................................... 49
11.2.2. RSA 2048 ....................................................................... 50
11.2.2.1. CSR ........................................................................ 50
11.2.2.2. Certificate ............................................................... 51
12. Signatures generation and verification rules .............................................. 54
12.1. Signature an hash generation algorithm .................................... 54
12.2. Receipt signature generation and verification ............................. 54
12.2.1. Receipt device signature .................................................... 54
12.2.2. Receipt FDMS signature ..................................................... 57
12.3. Fiscal day signature generation and verification .......................... 58
12.3.1. Fiscal day device signature ................................................. 58
12.3.2. Fiscal day FDMS signature ................................................... 59

1. FISCAL DEVICE GATEWAY USAGE SCENARIOS
1.1. Device registration
The process starts when a taxpayer initially registers or updates their information using
the Zimra registration portal. After completing this process, the taxpayer is provided with
device ID and Activation Key. Device registration must be done once before starting to use a
new device. After device registration, it needs to get its configurations (config) from FDMS.
1.2. Fiscal device communication modes

Fiscal device communicates with Fiscal Device Gateway API in one of two possible
communication modes:
 Online
 Offline
Online communication mode represents fiscal device communication in a way when

fiscal device must have online access to FDMS (must have internet connection available) when
it wants to close fiscal day. Fiscal day opening and submission of a receipt to FDMS should be
done immediately after opening a day or printing receipt or invoice for buyer respectively,
however in case of missing internet connection, day opening message and submission of a
receipt may be delayed but must be done before closing a fiscal day. In case fiscal day was
opened and receipt was issued without internet connection, it is mandatory, that fiscal day
opening message would be sent before sending receipts. Otherwise, receipts will not be
accepted.
Offline communication mode represents fiscal device communication in a way, when
fiscal device may not have internet, and its receipts and fiscal report data will be provided to

FDMS by using files (by uploading file using Self-service, or by sending file to Fiscal Device
Gateway API, whenever connection will be available).
1.3. Fiscal day (in online mode)

After successful device registration, it can be used for submitting sales to FDMS. Sales
submission is possible only when fiscal day is opened. When work is finished with device, it
must close fiscal day.
In case of error in fiscal day report processing report must be corrected on device and
resubmitted to FDMS. Report resubmission can be done unlimited number of times. In case it
does not give successful result, and supplier cannot fix it to submit successful report, fiscal day
may be closed manually by supplier in Public Portal, or by ZIMRA officer.

1.4. Fiscal day (in offline mode)
If device has internet connection, it should call getConfig method, to get device
configuration information.
Device opens fiscal day, if device has internet connection it can send information using
submitFile method (file with only header) about opened day.
Invoices are issued which are saved in device if device has internet connection it can
send information using submitFile method (file with header and content) about already issued
invoices.
After fiscal day is closed information is saved in device, if device has internet connection
it should send information using submitFile method (file with header and footer) about closed
day. However, if there are still unsent invoices left, it should send information using submitFile
method (file with header, content and footer) about receipts and closed day.
After sending file device should call getFileStatus method to get sent file status.

2. OBJECT STATUSES
2.1. Fiscal day statuses
Status Description
1. FiscalDayClosed Status used when fiscal device has successfully closed fiscal day. New fiscal day opening is
possible only from this status.
2. FiscalDayOpened Fiscal day is opened. Invoices can be created only when fiscal day is in this status.
3. FiscalDayCloseInitiated Closure of fiscal day is initiated, however FDMS not yet validated fiscal counters.
While Fiscal day is in status “FiscalDayCloseInitiated”, no new request to initiate fiscal day
closure will be accepted from device or user. New invoices will not be accepted as well.
4. Is processing successful? If processing of report is successful, fiscal day status is changed to FiscalDayClosed, if
processing of report is not successful status is changed to FiscalDayCloseFailed.
5. FiscalDayCloseFailed FDMS validated fiscal day report received from device, however there are validation errors.
Device must correct issues and repeatedly submit fiscal day closure message.

3. FISCAL DEVICE GATEWAY API INTERFACES
Fiscal Device Gateway API exposes its methods using REST JSON interface. All methods
except closeDay and submitFile are synchronous. closeDay and submitFile methods return
response about accepted request synchronously, however processing of information is done
asynchronously.
Each request must contain these HTTP headers:

Header name Mandatory Description
DeviceModelName Yes Device model name as registered in ZIMRA
DeviceModelVersionNo Yes Device model version number as registered in ZIMRA
3.1. verifyTaxpayerInformation
verifyTaxpayerInformation endpoint is used to retrieve taxpayer information from FDMS
before device registration (in order user could double check if device is going to be registered
to correct taxpayer).
This API endpoint does not require certificate for authentication.
Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID
activationKey String (8) Yes Activation key.
deviceSerialNo String (20) Yes Device serial number assigned by manufacturer.
Output parameters:
operationID String (60) Yes Operation ID assigned by FDMS.
taxPayerName String (250) Yes Taxpayer name
taxPayerTIN String (10) Yes Taxpayer TIN code
vatNumber String (9) No Taxpayer’s VAT number. Field is not returned if taxpayer
is not a VAT payer.
deviceBranchName String (250) Yes Device branch name (or trade name) assigned by
taxpayer.
deviceBranchAddress Address Yes Device branch address.
deviceBranchContacts Contacts No Device branch contacts information.
3.2. registerDevice
registerDevice endpoint is used to get device certificate and register device in FDMS
(link device with FDMS).
Input parameters:
activationKey String (8) Yes Activation key.
Case insensitive 8 symbols key.
certificateRequest String Yes Certificate signing request (CSR) for which certificate will be
generated (in PEM format).

Assigned by ZIMRA device name (format: ZIMRA-
<Fiscal_device_serial_no>-<zero_padded_10_digit_deviceId>) should
be provided in CSR`s Subject CN.
Example of CN value, when fiscal device serial no is “SN: 001” and
device id is “187”: “ZIMRA-SN: 001-0000000187”.
Other CSR’s Subject fields are optional, however if provided must
match these values (otherwise device registration will be rejected):
 C = ZW
 O = Zimbabwe Revenue Authority
 S = Zimbabwe
Supported algorithms and key types (in order of suggested

preference):
1) ECC ECDSA on SECG secp256r1 curve (also named as ANSI
prime256v1, NIST P-256); Signature Algorithm: ecdsa-with-
SHA256.
2) RSA 2048; Signature Algorithm - SHA256WithRSA.
Note: RSA 2k and ECC 256 implement same security level, which is
considered safe until 2030 year (considering trends due to upgrade in
computer software and hardware combination).
Most cryptographic tools and libraries support this format giving easy-
to-use API and hiding all technical representation and encoding
details.
CSR is “CertificationRequest” structure, as defined by PKCS #10 (CSR
syntax specified by RFC2986).
Serialized in PEM format (i.e., base64 encoded with “------BEGIN
CERTIFICATE REQUEST-----” header and “-----END CERTIFICATE
REQUEST-----” footer).
For more info, please refer to “11 Certificate signing request (CSR)
and Certificate examples”.
Output parameters:
certificate String Yes X.509 v3 type device certificate (in PEM format).
It must be used by device in further communication with Fiscal
Device Gateway API. Certificate is multi-purpose:
 Client Certificate for SSL with Client Authentication.

 For data signing when device signature is required.
Certificate is “Certificate” structure specified by RFC5280.

Serialized in PEM format (i.e. base64 encoded with “-----BEGIN
CERTIFICATE-----” header and “-----END CERTIFICATE-----” footer).
For more info, please refer to “11 Certificate signing request (CSR)
and Certificate examples”.
3.3. issueCertificate
issueCertificate endpoint is used to renew certificate before the expiration of the
current certificate.
It is recommended to renew certificate a month before its expiration.
Certificate reissuance can be done at any time. It does not depend on fiscal day status,
however it is recommended to be done before opening a new fiscal day.
Input parameters:

certificateRequest String Yes Certificate signing request (CSR) for which certificate will be
generated (in PEM format).
certificateRequest requirements are specified in registerDevice
endpoint description.
Output parameters:
certificate String Yes X.509 v3 type device certificate (in PEM format).
Certificate requirements are specified in registerDevice endpoint
description.
3.4. getConfig
getConfig endpoint is used to retrieve taxpayers and device information and
configuration.
Input parameters:
Output parameters:
taxPayerName String (250) Yes Taxpayer name
taxPayerTIN String (10) Yes Taxpayer TIN code
vatNumber String (9) No Taxpayer’s VAT number. Field is not returned if taxpayer
is not a VAT payer.
If taxpayer which is not a VAT taxpayer, gets VAT number
and its fiscal device has opened fiscal day, fiscal day
must be closed and newly opened in order taxpayer could
submit receipts with VAT.
deviceSerialNo String (20) Yes Device serial number assigned by manufacturer.
deviceBranchName String (250) Yes Device branch name (or trade name) assigned by
taxpayer.
deviceBranchAddress Address Yes Device branch address.
deviceBranchContacts Contacts No Device branch contacts information.
deviceOperatingMode DeviceOperatingMode Yes Specifies what are allowed receipt processing modes for
this device.
Possible values:
- Online
- Offline
Device operational mode can be changed only by ZIMRA
officer.
taxPayerDayMaxHrs Int Yes Maximum fiscal day duration in hours.
taxpayerDayEndNotificationHrs Int Yes How much time in hours before end of fiscal day device
should show notification to salesperson.
applicableTaxes Tax array Yes List of applicable tax rates which can be used by this
taxpayer and are valid during getConfig request time or
will be valid in the future.
certificateValidTill Date Yes Date till when device certificate is valid. Device must
reissue new certificate before this date. After this date
device will not be able to submit any request to Fiscal
Device Gateway.
qrUrl String (50) Yes URL for QR preparation. This URL needs to be used by
device when generating QR code printed on invoice.

Tax:
taxID Int Yes Tax ID uniquely identifying a tax. This tax ID must be used in
submitting invoices.
taxPercent Decimal (5,2) No Tax percent. In case of exempt, field will not be returned.
taxName String (50) Yes Tax name.
taxValidFrom Date Yes Date from which tax is valid.
taxValidTill Date No Date till which tax is valid.
3.5. getStatus
getStatus endpoint is used to get fiscal day status.
Request can’t be sent if DeviceOperatingMode is Offline. If DeviceOperatingMode is
Offline error DEV01 is received.
Input parameters:
Output parameters:
fiscalDayStatus FiscalDayStatus Yes Device Fiscal day status.
fiscalDayReconciliationMode FiscalDayReconciliationMode No In case fiscal day status is “FiscalDayClosed”

defines how it was closed: automatically or
manually.
fiscalDayServerSignature SignatureDataEx No Fiscal day report signature prepared by FDMS.
This field is returned only when fiscalDaySatus is
“FiscalDayClosed”.
This signature is not used in further
communication or any data preparation for FDMS.
It is confirmation from FDMS that fiscal day is
closed and should be stored on device.
Signature verification rules are described in
section 12.3.
fiscalDayClosed DateTime No Date and time when fiscal day report was
processed, and fiscal day status was changed to
“FiscalDayClosed”. Time is provided in local time
without time zone information.
This field is returned only when fiscalDaySatus is
“FiscalDayClosed”.
If device has never started a new fiscal day, this
field is not returned.
fiscalDayClosingErrorCode FiscalDayProcessingError No Code of error which appears during fiscal day
closure. Possible codes are defined in section
4.4.9 FiscalDayProcessingError. This field is
returned only when fiscalDayStatus is
“FiscalDayCloseFailed”.Error codes
fiscalDayCounters FiscalDayCounter array No List of fiscal day counters. This field is returned
only when fiscalDayStatus is “FiscalDayClosed”
and fiscalDayReconciliationMode is “Manual”.
List contains only non-zero value fiscal counters.
FiscalDayCounter type description provided in

closeDay endpoint.
fiscalDayDocumentQuantities FiscalDayDocumentQuantity No List of fiscal day document quantities. This field is
array returned only when fiscalDayStatus is
“FiscalDayClosed” and
fiscalDayReconciliationMode is “Manual”.

FiscalDayDocumentQuantity type description
provided in FiscalDayDocumentQuantity table.
lastReceiptGlobalNo Int No Last submitted receiptGlobalNo field value of
fiscal invoice, credit note or debit note. In case
no document is yet submitted from this fiscal
device, this field is not returned.
lastFiscalDayNo Int No In case fiscal day is opened, current fiscal day
fiscalDayNo is returned. In case fiscal day is
closed, last closed fiscal day fiscalDayNo is
returned.
In case fiscal device is new and not yet opened its
first fiscal day, this field is not returned.
FiscalDayDocumentQuantity:
receiptType ReceiptType Yes Type of receipt.
receiptCurrency String (3) Yes Receipt currency (ISO 4217 currency code).
receiptQuantity Int Yes Total quantity of receipts of particular receipt type and currency for
fiscal day.
receiptTotalAmount Decimal (19,2) Yes Total receipt amount (including tax) of receipts of particular receipt
type and currency for fiscal day.
3.6. openDay
openDay endpoint is used to open a new fiscal day. Opening of new fiscal day is possible
only when previous fiscal day is successfully closed (fiscal day status is “FiscalDayClosed”).
Opening of a new fiscal day in a fiscal device may be done without internet connection. It is
important that such delayed request about day opening is sent before sending receipts. Request
can’t be sent if DeviceOperatingMode is Offline. If DeviceOperatingMode is Offline error DEV01
is received.
Input parameters:
fiscalDayOpened DateTime Yes Date and time when fiscal day was opened on a device. Time is
provided in local time without time zone information.
fiscalDayNo Int No Fiscal day number assigned by device.
If this field is not sent, FDMS will generate fiscal day number and
return it to device.
Validation rules:
- fiscalDayNo must be equal to 1 for the first fiscal day of fiscal
device
- fiscalDayNo must be greater by one from the last closed fiscal day
fiscalDayNo.
Output parameters:
fiscalDayNo Int Yes Fiscal day number of opened day.

In case device has sent fiscalDayNo in request, it is returned in this
field. In case device has not sent it, new fiscal day number will be
generated by FDMS.

3.7. submitReceipt
submitReceipt endpoint is used to submit a receipt to FDMS in online mode and get a
FDMS signature for it (signature is not a QR code, it is an acknowledgement of FDMS about
received receipt). Receipt can be submitted only when fiscal day status is “FiscalDayOpened”
or “FiscalDayCloseFailed”.
In case device tried to close a fiscal day and attempt was unsuccessful, device still have
a possibility to submit a new receipt. In case it fails to submit, there should be retries of the
unsent invoices to be sent.
In case the same receipt (with the same deviceID, receiptGlobalNo and receiptHash) is
submitted more than once, Fiscal Device Gateway API will return successful result to fiscal
device with the same original receipt receiptID, receiptServerSignature, however different
operationID.
Each submitted receipt is validated. Receipt will not be accepted, error will be returned
to fiscal device (as specified in 7.2 Error codes), in these cases:
 fiscal device status is other than “Active”;

 fiscal day status is other than “FiscalDayOpened” or “FiscalDayCloseFailed”;
 receipt message structure is not valid.
In case the above-mentioned validations have passed, but receipt has other validation
issues specified below (described in “Validation rules”), receipt will be accepted and signed,
but will be marked as invalid with validation color code assigned (as specified in 7.3.
Validation errors).
Each submitted receipt, must increase fiscal day counters as specified in 5. Fiscal
counters.
Input parameters:
receipt Receipt Yes Receipt data
Receipt:
receiptType ReceiptType Yes Type of receipt.
receiptCurrency String (3) Yes Receipt currency (ISO 4217 currency code).
Validation rules
RCPT010: currency code must be present in FDMS and
must be valid at the time of receiptDate.
receiptCounter Int Yes Daily ascending serial number of receipt assigned by
taxpayer’s device.
Validation rules:
RCPT011: receiptCounter must be equal to 1 for the first
receipt in fiscal day and receiptCounter must be greater
by one from the previous receipt’s receiptCounter value
for the second and other receipt in fiscal day.
receiptGlobalNo Int Yes Cumulative ascending serial number of total receipts
issued since device activation date.
Taxpayer is allowed to reset this receiptGlobalNo
counter to start from 1, however this is allowed to be
done only for the first receipt in a fiscal day.
Validation rules:

RCPT012: receiptGlobalNo must be greater by one from
the previous receipt’s receiptGlobalNo or may be equal
to 1 for the first receipt in fiscal day.
invoiceNo String (50) Yes Invoice number generated by accounting system.
Validation rules:
RCPT013: invoiceNo must be unique in taxpayer context.
buyerData Buyer No Buyer information.
receiptNotes String No* Receipt notes. Usually used for CreditNote and
DebitNote, mandatory for CreditNote and DebitNote.
Validation rules:
RCPT034:
- receiptNotes is mandatory for receiptType CreditNote
and DebitNote
receiptDate DateTime Yes Date and time of device when receipt is printed for
customer. Time is provided in local time without time
zone information.
Validation rules:
RCPT014:
- receiptDate must be greater than fiscal day opening
date and time
RCPT030:
- receiptDate must be greater than previously submitted
receiptDate
RCPT031:
- receiptDate must not be greater than current time
(time difference set in
AllowedTimeDifferenceForReceiptSubmission setting is
allowed).
RCPT041:
- receiptDate must be less or equal than fiscal day
opened + taxpayerDayMaxHrs.
creditDebitNote CreditDebitNote No* Credited or debited receipt information. This field is
mandatory in case receipt type is CreditNote or
DebitNote.
Validation rules:
RCPT015:
- creditDebitNote object is mandatory for receiptType
CreditNote and DebitNote
RCPT032:
- credited or debited receipt must exist in FDMS,
received also if credited or debited receipt does not
belong to the same taxpayer of submitted credit or debit
note
RCPT033:
- credited or debited receipt must be issued not earlier
than 12 months before credit or debit note receiptDate
RCPT035:
- total credit note amount must not exceed original
receipt amount with all previously submitted credit and
debit notes amounts (where amount is calculated in this
way original receipt amount – all submitted credit notes
amounts + all submitted debit notes amounts. Result
must be >= 0).
RCPT036:
- credit or debit note must have all or part of tax
percentages plus tax ids used as in the original invoice. It
cannot have new taxes, that are not in original invoice
(example, if original invoice has exempt and 15% VAT tax
lines, credit or debit note may have only exempt, 15%
VAT or both tax lines, but cannot have 0% tax line). Non
VAT taxpayer can still send VAT tax line if it was present
on original invoice.
RCPT029:
- in case CreditDebitNote object is provided for
FiscalInvoice document, received data will be saved with
validation RCPT029 error.

RCPT042: currency code must be same as in the original
invoice. Credit/debit note cannot have different
currency, than in original invoice.
receiptLinesTaxInclusive Boolean Yes Specifies if receipt lines are tax inclusive or not. Possible
values:
- True, all receipt lines are tax inclusive
- False, all receipt lines are tax exclusive
receiptLines ReceiptLine array Yes Receipt lines.
Validation rules:
RCPT016: at least one line must be provided.
receiptTaxes ReceiptTax array Yes Receipt taxes.
Validation rules:
receiptPayments Payment array Yes Means of payments how receipt was paid.
Validation rules:
receiptTotal Decimal (19,2) Yes Total receipt amount which is paid/received by buyer.
Validation rules:
RCPT019:
- receiptTotal must be equal to sum of receiptLineTotal
of all receiptLines in case receiptLinesTaxInclusive is
true.
RCPT037:
- receiptTotal must be equal to sum of receiptLineTotal
of all receiptLines plus sum of taxAmount of all
receiptTaxes in case receiptLinesTaxInclusive is false.
RCPT038:
- receiptTotal must be equal to sum of
salesAmountWithTax of all receiptTaxes.
RCPT039:
- receiptTotal must be equal to sum of paymentAmount
of all receiptPayments.
RCPT040:
- receiptTotal must be greater than or equal to 0 for
FiscalInvoice and DebitNote, receiptTotal must be less
than or equal to 0 for CreditNote.
receiptPrintForm ReceiptPrintForm No The format in which printed invoice was delivered to
buyer (as a receipt, on A4 paper, etc.).
Default value if field is not sent: Receipt48.
receiptDeviceSignature SignatureData Yes SignatureData structure with SHA256 hash of receipt
fields (hash used for signature) and receipt device
signature prepared by using device private key as
described in section 12.2.
Validation rules:
RCPT020: receiptDeviceSignature must be valid
Buyer:
buyerRegisterName String (250) Yes Buyer company name or physical person name and surname.
buyerTradeName String (250) No Buyer trade name (store name, or branch name).
buyerTIN String (10) No Buyer TIN (provided for companies having TIN number). Foreign
companies and local not registered companies will provide only
buyerRegisterName.
VATNumber String (9) No Buyer VAT number.
buyerContacts Contacts No Buyer contacts.
buyerAddress Address No Buyer address.
CreditDebitNote:

receiptID Bigint No Receipt ID of credited or debited receipt which is credited or
debited by current receipt. receipID must be sent or deviceID with
receiptGlobalNo and fiscalDayNo must be sent.
deviceID Int No Device ID of credited or debited receipt which is updated by
current receipt.
In case receiptID is sent, this field is ignored.
receiptGlobalNo Int No Receipt global No of credited or debited receipt which is updated
by current receipt.
In case receiptID is sent, this field is ignored.
fiscalDayNo Int No fiscalDayNo of credited or debited receipt which is updated by
current receipt.
ReceiptLine:
receiptLineType ReceiptLineType Yes Type of receipt line (for example sales or discount).
receiptLineNo Int Yes Line sequence number in receipt.
receiptLineHSCode String (8) No Product or service code from National Harmonized System codes
list.
receiptLineName String (200) Yes Product or service name
receiptLinePrice Decimal (19,3) No Price of product or service in receipt currency (for single item).
It may not be provided if the price for quantity of several prices
is set (i.e., when selling 3 items for 1 USD).
Validation rules:
RCPT022: receiptLinePrice value must be:
- greater than 0 for FiscalInvoice and DebitNote if
ReceiptLineType is Sale;
- less than 0 for FiscalInvoice and DebitNote if ReceiptLineType
is Discount;
- less than 0 for CreditNote if ReceiptLineType is Sale;
- greater than 0 for CreditNote if ReceiptLineType is Discount.
receiptLineQuantity Decimal (19,3) Yes Product quantity
Validation rules:
RCPT023: value must be greater than 0
receiptLineTotal Decimal (19,2) Yes Total price of receipt line (receiptLinePrice *
receiptLineQuantity).
Validation rules:
RCPT024: in case receiptLinePrice is provided, receiptLineTotal
must be equal to receiptLinePrice * receiptLineQuantity
taxCode String (3) No Tax code representation in receipt. This field is not mandatory;
however, it must be provided for all receipt lines or none of
them. It is not allowed to provide taxCode for just a part of
lines.
taxPercent Decimal (5,2) No Applied tax percent. In case of no VAT sale, 0 value should be
used, in case of exempt this field should not be provided.
Validation rules:
RCPT025:
- Tax percent and tax ID combination must be the same as in
FDMS.
taxID Int Yes Applied tax ID uniquely identifying used tax.
Validation rules:
RCPT025:
- VAT tax ID value must be one of the allowed tax ID values
- receiptDate must be in a period of tax valid from and valid till
period
RCPT021:
- VAT tax percent value determined by tax ID is greater than 0%
and taxpayer is not VAT taxpayer.
ReceiptTax:

taxCode String (3) No Tax code representation in receipt.
taxPercent Decimal (5,2) No Applied tax percent. In case of no VAT sale, 0 value should be
used, in case of exempt this field should not be provided.
Validation rules:
RCPT025:
-Tax percent and tax ID combination must be the same as in
FDMS.
taxID Int Yes Applied tax ID uniquely identifying used tax.
Validation rules:
RCPT025:
- VAT tax ID value must be one of the allowed tax ID values
- receiptDate must be in a period of tax valid from and valid
till period
RCPT021:
- VAT tax percent value determined by tax ID is greater than
0% and taxpayer is not VAT taxpayer.
taxAmount Decimal (19,2) Yes Total tax amount for this tax percent.
taxAmount = SUM (receiptLineTotal of the same taxCode) *
taxPercent/(1+taxPercent).
In case of Non VAT and exempt, 0 should be sent in this field.
Validation rules:
RCPT026:
- taxAmount must be equal to SUM (receiptLineTotal) *
taxPercent/(1+taxPercent) of all receiptLines with the same
taxPercent and taxCode values in case
receiptLinesTaxInclusive is true
- taxAmount must be equal to SUM (receiptLineTotal) *
taxPercent of all receiptLines with the same taxPercent and
taxCode values in case receiptLinesTaxInclusive is false
salesAmountWithTax Decimal (19,2) Yes Total sales amount (including tax) for this tax percent.
Validation rules:
RCPT027:
- salesAmountWithTax must be equal to sum of
receiptLineTotal of all receiptLines with the same taxPercent
and taxCode values in case receiptLinesTaxInclusive is true
- salesAmountWithTax must be equal to SUM
(receiptLineTotal)*(1+ taxPercent) of all receiptLines with the
same taxPercent and taxCode values in case
receiptLinesTaxInclusive is false
Payment:
moneyTypeCode MoneyType Yes Code of payment mean by which payment was done.
paymentAmount Decimal (19,2) Yes Amount paid by this payment type in receipt currency. In case
customer gave bigger amount (bill) in cash than total amount
to be pay, it is needed to send amount without change to
buyer.
Validation rules:
RCPT028: paymentAmount value must be greater than or equal
to 0 for FiscalInvoice and DebitNote, value be less than or
equal to 0 for CreditNote.
Output parameters:
receiptID Bigint Yes Receipt ID assigned by FDMS.
serverDate DateTime Yes Date and time when FDMS signed a receipt.
receiptServerSignature SignatureDataEx Yes Receipt FDMS signature generated by FDMS.
This signature is not used in further communication or any
data preparation for FDMS. It is confirmation from FDMS that
receipt is accepted and should be stored on device.
Signature verification rules are described in section 12.2.

3.8. submitFile
submitFile endpoint is used to submit a batch of invoices to FDMS in a single file.
Request can be sent if DeviceOperatingMode is Offline.
File can have three parts: Header (fiscal day information), Content (invoices
information) and Footer (Z report information). Header is always mandatory, Content and
Footer are optional (Footer can be sent without Content, Content can be sent without Footer).
File can have information only for one fiscal day. Elements sequence in file must be assured to
be: Header, Content, Footer, otherwise file format error will be returned.
File must be JSON format sent as base64 encoded string.
File will not be accepted, error will be returned to fiscal device (as specified in 7.2 Error
codes), in these cases:

 fiscal device operating mode is other than “Offline”;
 file is bigger than 3 MB;
 request structure is not valid;
 file Header failed to be parsed.
In case the above-mentioned validations have passed, file is processed asynchronously.

File status can be received by calling 3.9 getFileStatus API method.
If other validation issues during asynchronous processing will be detected error
information may be retrieved in 3.9 getFileStatus response.
During asynchronous processing these steps will be executed:
 file structure will be validated;

 fiscal day status validated by information provided in header;
 invoices will be imported from file to FDMS (same validation rules will be applied
as described in 3.7 submitReceipt);
 Z report will be validated same validation rules will be applied as described in
3.10 closeDay).
Additional validation rules:
 If Content and Footer are sent in a single file, they are processed as separate
parts. It means that Content can be processed successfully, but Footer not
successfully. In such case, invoices from Content part remains in FDMS. In case
Content part fails to be processed, Footer part processing is skipped.
 Invoice is created in FDMS only if it does not yet exist (with the same deviceID,
fiscalDayNo, receiptGlobalNo and receiptHash). It means if the same file with
the same invoice is sent once again, or the same invoice is sent in another file
invoice processing is skipped (because it is already saved in FDMS).
 If two files have same fiscal fiscalDayNo value but different fiscalDayOpened
values. First received fiscalDayOpened value is saved, later received value is
ignored.
Input parameters:
deviceID Int Yes Device ID.

file File in Yes File containing invoices and other information related
multipart/form- to fiscal day. Base64 encoded.
data
processImmediately Boolean Yes Parameter if file should be processed immediately or
after some time (4 hours).
Possible values:
- True, file is processed immediately.
- False, file is not processed immediately.
Processing of file will be done when one of these
will be fulfilled:
o Another file from device with
processImmediately = yes is received
o or 4 hours have passed after file
submittion.
File:
header FileHeader Yes File header with fiscal day information.
content FileContent No* File content information. Mandatory if invoices are
sent.
footer FileFooter No* File footer information. Mandatory if Z report is sent.
Fiscal day closure procedure should be initiated.
FileHeader:
fiscalDayNo Int Yes Fiscal day number. Must be same as in FDMS if fiscal
day is opened or greater by 1 if previous fiscal day is
closed in case processImmediately is true. Otherwise,
fiscal day number must be equal or greater than saved
in FDMS.
fiscalDayOpened DateTime Yes Date and time when fiscal day was opened on a
device. Time is provided in local time without time
zone information.
fileSequence Int Yes Sequence number of file in fiscal day files sequence.
FileContent:
receipts Receipt array Yes List of receipts in file. Receipt type description is
provided in 3.7 submitReceipt endpoint description.
FileFooter:
fiscalCounters FiscalDayCounter No List of fiscal counters.
array Zero value counters must not be submitted to FDMS.
FiscalDayCounter type description provided in
3.10closeDay endpoint.
fiscalDayDeviceSignature SignatureData Yes SignatureData structure with SHA256 hash of fiscal day
report fields (hash used for signature) and fiscal day
report device signature prepared by using device
private key as described in section 12.3.
Validation rules:
- fiscalDayDeviceSignature must be valid
receiptCounter Int Yes receiptCounter value of last receipt of current fiscal
day.
fiscalDayClosed DateTime Yes Date and time when fiscal day was closed on a device.
Time is provided in local time without time zone
information.
Output parameters:

3.8.1. File example
{
"header": {
"deviceID": 1111,
"fiscalDayNo": 5,
"fiscalDayOpened": "2023-05-30T08:38:54",
"fileSequence": 2
},
"content": {
"receipts": [
{
"receiptType": "FiscalInvoice",
"receiptCurrency": "USD",
"receiptCounter": 5,
"receiptGlobalNo": 1112,
"invoiceNo": "IV-2023/1256",
"receiptDate": "2023-05-30T18:38:54",
"receiptLinesTaxInclusive": true,
"receiptLines": [
{
"receiptLineType": "Sale",
"receiptLineNo": 1,
"receiptLineHSCode": "85456852",
"receiptLineName": "Man's shoes",
"receiptLinePrice": 25,
"receiptLineQuantity": 1,
"receiptLineTotal": 25,
"taxCode": "A",
"taxPercent": 15,
"taxID": 1
}
],
"receiptTaxes": [
{
"taxCode": "A",
"taxPercent": 15,
"taxID": 1,
"taxAmount": 3.75,
"salesAmountWithTax": 28.75
}
],
"receiptPayments": [
{
"moneyTypeCode": "Cash",
"paymentAmount": 28.75
}
],
"receiptTotal": 28.75,
"receiptPrintForm": "Receipt48",
"receiptDeviceSignature": {
"hash": "Yjkjy =",
"signature": "Yy ="
}
},
{
//invoice No 2 data
"receiptCurrency": "USD"
},
{
//invoice No 3 data
"receiptCurrency": "USD"
}
]
},
"footer": {
"fiscalDayCounters": [
{
"fiscalCounterType": "SaleByTax",
"fiscalCounterCurrency": "USD",
"fiscalCounterTaxPercent": 15,
"fiscalCounterTaxID": 0,
"fiscalCounterMoneyType": "Cash",

"fiscalCounterValue": 28.75
}
],
"fiscalDayDeviceSignature": {
"hash": "Yjkjy =",
"signature": "Yy ="
},
"receiptCounter": 1,
"fiscalDayClosed": "2023-05-30T22:38:54"
}
}
3.9. getFileStatus
getFileStatus endpoint is used by device to get previously sent file processing status
from FDMS.
Request can be sent if DeviceOperatingMode is Offline.
Request will not be accepted, error will be returned to fiscal device (as specified in 7.2
Error codes), in these cases:

 fiscal device operating mode is other than “Offline”;
 request structure is not valid.
Input parameters:
fiscalDayNo Int No* Fiscal day number. Mandatory if operationID is not sent.
operationID Int No* operationID. Unique operation identifier received. in 3.8 submitFile
response. Mandatory if fiscalDayNo is not sent.
Output parameters:
fileStatus FileStatus array Yes List of files statuses.
FileStatus:
operationID Int Yes Operation ID received in 3.8 submitFile request.
fileSequence Int Yes Sequence number of file in fiscal day files sequence.
fileProcessingStatus FileProcessingStatus Yes File processing status. Possible statuses are defined in section
4.4.10 FileProcessingStatus.
fileProcessingErrorCode FileProcessingError No List of error codes which appear during submitted file processing,
array returned if FileProcessingStatus is FileProcessingWithErrors.
Possible codes are defined in section 4.4.11 FileProcessingError.
3.10. closeDay
closeDay endpoint is used to initiate fiscal day closure procedure. This method is allowed
when fiscal days status is “FiscalDayOpened” or “FiscalDayCloseFailed”.
In case fiscal day contains at least one “Grey” or “Red” receipt (as specified in 7.3.
Validation errors), FDMS will respond to closeDay request with error (fiscal day will remain
opened). Otherwise, if fiscal day does not have “Grey” and “Red” receipts, validation of
submitted closeDay request will be executed. In case of fiscal day validation fails (as specified

below in “Validation rules”), fiscal day remains opened, and its status is changed to
“FiscalDayCloseFailed”.
Input parameters:
fiscalDayNo Int Yes Fiscal day number.
Validation rules:
- fiscalDayNo must be the same as provided/received
fiscalDayNo value in openDay request.
fiscalDayCounters FiscalDayCounters Yes List of fiscal counters.
array Zero value counters must not be submitted to FDMS.
fiscalDayDeviceSignature SignatureData Yes SignatureData structure with SHA256 hash of fiscal day
report fields (hash used for signature) and fiscal day
report device signature prepared by using device
private key as described in section 12.3.
Validation rules:
- fiscalDayDeviceSignature must be valid
receiptCounter Int Yes receiptCounter value of last receipt of current fiscal
day.
FiscalDayCounter:
fiscalCounterType FiscalCounterType Yes Fiscal counter type.
fiscalCounterCurrency String (3) Yes Fiscal counter currency (ISO 4217 currency code).
fiscalCounterTaxID Int No* Tax ID of fiscal counter.
Must be provided for all fiscal counter types “byTax”.
fiscalCounterTaxPercent Decimal (5,2) No* Tax percentage of fiscal counter.
Must be provided for all fiscal counter types “byTax”.
In case of exempt, this field must not be provided.
fiscalCounterMoneyType MoneyType No* Code of payment mean of fiscal counter.
Must be provided for fiscal counter type
“BalanceByMoneyType”.
fiscalCounterValue Decimal (19,2) Yes Fiscal counter value in counter currency.
Validation rules:
- value must be greater than or equal to 0 for SaleByTax,
SalesTaxByTax, DebitNoteByTax and DebitNoteTaxByTax fiscal
counter types
- value must be less than or equal to 0 for CreditNoteByTax
and CreditNoteTaxByTax fiscal counter types
Output parameters:
3.11. getServerCertificate
getServerCertificate endpoint is used to retrieve FDMS certificate for FDMS signature
validation.
Input parameters:
thumbprint Binary (20) No Thumbprint of FDMS signing certificate which should be returned. If
field is not provided, currently active FDMS signing certificate is

returned. Together with the certificate, all certificate chain is
returned.
Output parameters:
certificate String array Yes FDMS certificate chain (according to x.509 standard) to
validate FDMS signatures.
certificateValidTill Date Yes Date till when FDMS signing certificate is valid (despite that
in the certificate parameter all the certificate chain is
returned, this field shows validity time of the child
certificate in the chain). Value is provided in UTC time.
3.12. ping
ping endpoint is used to report device is online to FDMS. When device is turned on, it
must regularly report to FDMS that it is online. Reporting periodicity is specified in
reportingFrequency parameter received in response from FDMS.
Input parameters:
Output parameters:
reportingFrequency int Yes Reporting frequency in minutes.

4. DATA TYPES
4.1. Address
Address object is used to define address object for returning information from FDMS
and for accepting buyers information.
province String (100) Yes Province name
city String (100) Yes City, town, growth point, farming area, mining area
street String (100) Yes Street, stand number, village
houseNo String (100) Yes House number
4.2. Contacts
Contacts object is used to define Taxpayers and device contact information.
phoneNo String (20) No* Phone number
email String (100) No* E-mail address
* at least one of field is mandatory.
4.3. SignatureData
SignatureData:
hash Binary (32) Yes SHA-256 hash.
signature Binary (256) Yes Cryptographic signature, for which hash was used.
More details see in “12 Signatures generation and verification
rules”.
Field length is variable depends on cryptographic algorithm.
SignatureDataEx:
SignatureData fields
certificateThumbprint Binary (20) Yes SHA-1 Thumbprint of Certificate used for signature.
4.4. Enums
Enum, short for "enumerated," is a data type that consists of predefined values. A
variable defined as an enum can store one of the values listed in the enum declaration.
4.4.1. DeviceOperatingMode
Specifies what are allowed receipt processing modes for this taxpayer, possible values:
Enum value Enum order
Online 0
Offline 1
4.4.2. FiscalDayStatus
Device Fiscal day status, possible values:
FiscalDayClosed 0

FiscalDayOpened 1
FiscalDayCloseInitiated 2
FiscalDayCloseFailed 3
4.4.3. FiscalDayReconciliationMode
Defines how fiscal day was closed, possible values:
Auto 0
Manual 1
4.4.4. FiscalCounterType
Fiscal counter type, possible values:
SaleByTax 0
SaleTaxByTax 1
CreditNoteByTax 2
CreditNoteTaxByTax 3
DebitNoteByTax 4
DebitNoteTaxByTax 5
BalanceByMoneyType 6
4.4.5. MoneyType
Code of payment mean of fiscal counter, possible values:
Cash 0
Card 1
MobileWallet 2
Coupon 3
Credit 4
BankTransfer 5
Other 6
4.4.6. ReceiptType
Type of receipt. Possible values:
FiscalInvoice 0
CreditNote 1
DebitNote 2
4.4.7. ReceiptLineType
Type of receipt line. Possible values:
Sale 0
Discount 1

4.4.8. ReceiptPrintForm
Type of receipt or invoice visual representation template in which form it was printed
and delivered to buyer. Possible values:
Enum value Enum order Description
Receipt48 0 Printed as receipt on receipt paper, 48 characters per line.
InvoiceA4 1 Printed on A4 paper as invoice.
4.4.9. FiscalDayProcessingError
Messages which are shown in case of error during fiscal day closure. Validations are
performed in this sequence. Possible values:
BadCertificateSignature 0 Close day is not allowed. Bad certificate signature is used.
MissingReceipts 1 Close day is not allowed. There are missing receipts in fiscal day
(“Grey” validation error).
ReceiptsWithValidationErrors 2 Close day is not allowed. There are receipts with validation errors
in fiscal day (“Red” validation error).
CountersMismatch 3 Close day is not allowed. There are mismatches between
counters.
4.4.10. FileProcessingStatus
File processing status, possible values:
FileProcessingInProgress 0
FileProcessingIsSuccessful 1
FileProcessingWithErrors 2
4.4.11. FileProcessingError
Messages which are shown in case of error during submitted file processing. Possible
values:
IncorrectFileFormat 0 File structure is incorrect, elements sequence is incorrect.
OpenDayIsNotAllowed 1 New fiscal day opening is not allowed because previous fiscal day
is not closed.
FileSentForClosedDay 2 Fiscal day for which file is sent is closed.
BadCertificateSignature 3 Closing day is not allowed. Bad certificate signature is used.
MissingReceipts 4 Closing day is not allowed. There are missing receipts in fiscal
day (“Grey” validation error).
ReceiptsWithValidationErrors 5 Closing day is not allowed. There are receipts with validation
errors in fiscal day (“Red” validation error).
CountersMismatch 6 Closing day is not allowed. There are mismatches between
counters.

5. FISCAL COUNTERS
With each submitted receipt (FiscalInvoice, CreditNote and DebitNote), fiscal counters
are updated.
After fiscal device finishes a fiscal day, it must close it by sending fiscal day report with
fiscal counters provided in the table below to Fiscal Device Gateway API. Fiscal counter is
optional to be sent in case it’s value is zero.
Counters list and calculation rules for different types of receipt and different types of
receipt lines are provided below. Please take a note to use correct sign when calculating a
counter (add or subtract value from counter). In case negative receipt total amount is sent,
fiscal counters become a negative sign too.
Fiscal day counters are reset after fiscal day close. Starting from a new fiscal day,
counters start to be counted from zero.
Table below lists fiscal counters and specifies either they are calculated for different
tax percents, currencies and/or payment methods:
Counter By tax By By payment Description
currency method
SaleByTax Total sales amount (after discount) by tax and by currency during
X X fiscal day including tax. Does not include debit notes and credit
notes.
SaleTaxByTax Total tax amount by tax and by currency from sales (after
X X discount) during fiscal day. Does not include debit notes and credit
notes.
CreditNoteByTax Total credit notes amount by tax and by currency during fiscal day
X X including tax.
CreditNoteTaxByTax Total tax amount by tax and by currency from credit notes during
X X fiscal day.
DebitNoteByTax Total debit notes amount by tax and by currency during fiscal day
X X including tax.
DebitNoteTaxByTax Total tax amount by tax and by currency from debit notes during
X X fiscal day.
BalanceByMoneyType Total collected or paid amount of money, by money type and by
X X currency during fiscal day.
Table below shows, which counters each submitted receipt type is changing and which
fields from submitted receipt are used:
Receipt type
Fiscal invoice Credit note Debit note
Counter
SaleByTax +salesAmountWithTax
SaleTaxByTax +taxAmount
CreditNoteByTax +salesAmountWithTax*
CreditNoteTaxByTax +taxAmount*
DebitNoteByTax +salesAmountWithTax
DebitNoteTaxByTax +taxAmount
BalanceByMoneyType +paymentAmount +paymentAmount* +paymentAmount
* - for credit note salesAmountWithTax, taxAmount, paymentAmount counters will be

used with negative numbers so with each credit note counter value will decrease.

6. INTEGRATION SETUP REQUIREMENTS
6.1. Communication and security protocols
Fiscal Device Gateway API can be accessed using HTTPS protocol only. All Fiscal Device
Gateway API methods except registerDevice and getServerCertificate use client authentication
certificate which is issued by FDMS.
6.2. Environment addresses

Fiscal Device Gateway API is accessible in testing and production (real) environments.
URL to access API:
Environment URL
Testing environment https://fdmsapitest.zimra.co.zw
Testing environment’s API can also be accessed using Swagger on
https://fdmsapitest.zimra.co.zw/swagger/index.html
Production environment https://fdmsapi.zimra.co.zw
6.3. Authentication and authorization

Fiscal Device Gateway uses mutual TLS authentication
(https://en.wikipedia.org/wiki/Mutual_authentication) to authenticate fiscal device using
fiscal device certificate. Fiscal device certificate is validated against issuing certificate to allow
or deny access to API endpoints.
Note: endpoints 3.1 verifyTaxpayerInformation, 3.2 registerDevice, 3.11 getServerCertificate

are public and do not require authentication. After authentication, provided fiscal device
certificate is checked against issued certificate (see 3.2 registerDevice and 3.3 issueCertificate
and methods for fiscal device certificate issuing) to check if the fiscal device certificate was
issued to calling device (by method parameter deviceId) and the fiscal device certificate was
not revoked.
The Fiscal Device Gateway will return HTTP 401 unauthorized code if:
 The provided fiscal device certificate was issued not by Fiscal Device
Gateway.
 The provided fiscal device certificate was revoked.
 The provided fiscal device certificate expired.
 The provided fiscal device certificate was not issued to calling fiscal
device.
6.4. Timeout Settings

Fiscal Device Gateway API response timeout for any synchronous operation – 30 seconds.

7. ERRORS
In case of API error, the system will return 4xx or 5xx http error code with response
body containing a detailed problem details structure as described in https://www.rfc-
editor.org/rfc/rfc7807 .
ProblemDetails:
type String Yes
title String Yes human readable problem definition
status Integer Yes Http status code
errorCode String No specific error code, for exact meaning see below
7.1. Http statuses

API can return such http statuses for errors:
Http status Description

400 bad request – the message is malformed and could not be processed by Fiscal Backend Gateway
401 Authentication error (see Authentication and authorization)
404 Resource not found (call to not existing endpoint)
405 method not allowed – trying to access API using unsupported HTTP methos, e.g., POST to get config
422 Unprocessable Content – the instructions given by fiscal device to Fiscal Backend Gateway are incorrect,
the response object ProblemDetails should contain ErrorCode to indicate the exact failing condition (e.g.,
DEV01 – device is blocked and therefore no instructions could be processed from such device)
500 Infrastructure error – the Fiscal Backend Gateway server is not available, or some infrastructure error
occurred. The fiscal device should retry to send message later.
502 Bad gateway - the Fiscal Backend Gateway server could not be contacted. The fiscal device should retry to
send message later.
7.2. Error codes
Error Code Description API methods

DEV01 Device not found or not active All
DEV02 Activation key is incorrect registerDevice
DEV03 Certificate request is invalid registerDevice

issueCertificate
RCPT01 Submitting receipt is not allowed. Fiscal day is closed or fiscal day submitReceipt
close initiated
RCPT02 Submit receipt failed. The receipt structure invalid or field submitReceipt
requirements not satisfied (e.g., provided field value length is
greater then allowed)
FISC01 Open day is not allowed openDay
FISC03 Closing day is not allowed. Close day is in progress. closeDay
FISC04 Closing day is not allowed. Fiscal day not opened. closeDay
FILE01 File is too big. Allowed file size: 3 MB. submitFile

FILE02 The request structure invalid or field requirements not satisfied (e.g submitFile
not sent mandatory field). getFileStatus
FILE03 Device operating mode is not Offline. submitFile
getFileStatus
FILE04 File structure is invalid, sequence of elements is incorrect. submitFile
getFileStatus
7.3. Validation errors

When sumbitReceipt request is received by FDMS and it is not rejected, FDMS validates
receipt data. In case previous receipt is missing, validation rules which require previous receipt
to be present are temporarily marked as grey and are revalidated when previous receipt is
received. After a validation, receipt is stored and signed by FDMS. Receipt validation status
may be valid or invalid. In case of invalid receipt, validation errors are categorized by one of
these colors:
Color Description
Grey This means that received receipt violates receipt chain and makes a gap in receipt chain (previous receipt is
missing). Such receipt is marked in “Grey”. With each of the next received receipt, such “Grey” receipt will
be revalidated (in case newly received receipt is the previous for the “Grey” receipt). After repeated
validation it will remain “Grey” (if newly received receipt is not the previous for it) or become valid.
Fiscal day will not be allowed to be closed automatically if it has at least one “Grey” receipt.
Yellow “Yellow” validation errors are minor ones. Fiscal day will be allowed to be closed automatically if it
contains only “Yellow” validation errors.
Red “Red” validation errors are major ones. Fiscal day fill is not allowed to be closed automatically if it has at
least one “Red” receipt.
Possible validation errors and their color codes:

Validation Color Do validation requires Validation error text
error previous receipt to be
present?
RCPT010 Red No Wrong currency code is used
RCPT011 Red Yes Receipt counter is not sequential.
RCPT012 Red Yes Receipt global number is not sequential.
RCPT013 Red No Invoice number is not unique
RCPT014 Yellow No Receipt date is earlier than fiscal day opening date
RCPT015 Red No Credited/debited invoice data is not provided
RCPT016 Red No No receipt lines provided
RCPT017 Red No Taxes information is not provided
RCPT018 Red No Payment information is not provided
RCPT019 Red No Invoice total amount is not equal to sum of all invoice lines
RCPT020 Red No Invoice signature is not valid
RCPT021 Red No VAT tax is used in invoice while taxpayer is not VAT taxpayer
RCPT022 Red No Invoice sales line price must be greater than 0 (less than 0 for Credit
note), discount line price must be less than 0 (greater than 0 for
Credit note)
RCPT023 Red No Invoice line quantity, must be positive
RCPT024 Red No Invoice line total is not equal to unit price * quantity

RCPT025 Red No Invalid tax is used
RCPT026 Red No Incorrectly calculated tax amount
RCPT027 Red No Incorrectly calculated total sales amount (including tax)
RCPT028 Red No Payment amount must be greater than or equal 0 (less than or equal
to 0 for Credit note)
RCPT029 Red No Credited/debited invoice information provided for regular invoice
RCPT030 Red Yes Invoice date is earlier than previously submitted receipt date
RCPT031 Yellow No Invoice is submitted with the future date
RCPT032 Red No Credit / debit note refers to non-existing invoice
RCPT033 Red No Credited/debited invoice is issued more than 12 months ago
RCPT034 Red No Note for credit/debit note is not provided
RCPT035 Red No Total credit note amount exceeds original invoice amount
RCPT036 Red No Credit/debit note uses other taxes than are used in the original
invoice
RCPT037 Red No Invoice total amount is not equal to sum of all invoice lines and taxes
applied
RCPT038 Red No Invoice total amount is not equal to sum of sales amount including
tax in tax table
RCPT039 Red No Invoice total amount is not equal to sum of all payment amounts
RCPT040 Red No Invoice total amount must be greater than or equal to 0 (less than or
equal to 0 for Credit note)
RCPT041 Yellow No Invoice is issued after fiscal day end
RCPT042 Red No Credit/debit note uses other currency than is used in the original
invoice

8. REQUIREMENTS FOR FISCAL DEVICES
This chapter specifies requirements for fiscal devices to be met:
1. Fiscal device must open a new fiscal day before issuing receipts and
invoices.
2. Fiscal device if internet connection is available must retrieve
configuration from FDMS (getConfig endpoint) before opening a new fiscal
day.
3. Fiscal device must save data from getConfig response about taxpayer
and/or its branch (taxpayer name, address, contacts, etc.) and use it for
receipt and invoice printing.
4. Fiscal device must track the time passed from opening a fiscal day, that
it would not exceed maximum allowed fiscal day length (specified in
parameter taxPayerDayMaxHrs) and forbid issuing new receipts and
invoices after that.
5. Fiscal device must inform user about the approaching fiscal day end.
Notification must be shown to the user a few hours before maximum fiscal
day length is reached. The exact number of hours left to maximum fiscal
day length is specified in parameter taxpayerDayEndNotificationHrs.
6. Fiscal device must assign receiptGlobalNo value to a receipt in a
sequential order starting from 1 and continue numbering despite fiscal
day close.
7. In case receiptGlobalNo value becomes very big and taxpayer would like
to reset it, this can be done by submitting the first receipt in a new fiscal
day.
8. Fiscal device must assign receiptCounter value to a receipt in a sequential
order starting from 1 and continue numbering only in the same fiscal day.
After fiscal day closure, receiptCounter must be reset to 0.
9. Fiscal device must not allow to add goods or services with VAT tax to
receipt or invoice if taxpayer is not a VAT taxpayer (VATNumber value is
received in getConfig response). In case taxpayer gets VAT number in the
middle of fiscal day, fiscal device must not allow to issue new receipts or
invoices and must require closing fiscal day first.
10. Fiscal day opening message must be sent immediately after opening a
fiscal day, however if there is no connection, it can be delayed.
11. Receipt must be sent to Fiscal Device Gateway API only after successfully
opening a fiscal day.
12. Fiscal device must send receipt to Fiscal Device Gateway API only after
finishing it (when receipt is printed).
13. Fiscal device must send receipt to Fiscal Device Gateway API one by one
in ascending receiptGlobalNo order, not skipping any of receipt. In case
submission of receipt failed, issue must be fixed, and receipt submission
must be repeated.
14. Fiscal device must send receipt to Fiscal Device Gateway API immediately
after finishing it in case there is an internet connection and there are no

waiting receipts to be sent, otherwise receipt must be put to the queue
on device and send later when connection will be restored.
15. Fiscal device must update counters after issuing a receipt and reset
counters after starting a new fiscal day as specified in 5. Fiscal counters.
16. Fiscal device must renew certificate which is near to expire before its
expiration date.
17. Offline Fiscal device must send file content only for a single fiscal day.
File cannot contain invoices from more than one fiscal day.
18. If file is bigger than 3 MB, content should be split into separate files,
footer can’t be split to two or more separate parts.
19. If fiscal day has a lot of receipts, it is recommended to split receipts and
Z report to separate files.
20. If offline fiscal device prepared more than one file for a single fiscal day,
these files must be sent to FDMS one by one in sequential order.
21. Offline fiscal device can send files with invoices even if fiscal day is not
yet closed. It is recommended that device sends file with newly issued
invoices whenever device gets internet connection.
22. Offline fiscal devices must be able to export file with invoices when user
request it for manual upload to FDMS.
23. User must not uninstall application from device if there are unsent
invoices.

9. STANDARD FISCAL RECEIPT, INVOICE AND REPORT VIEWS
9.1. Receipt48 view
Receipt48 view is used for tax inclusive invoice printed on receipt paper, which can
print 48 characters of text per line.
Receipt field name

[1] Taxpayer logo
Company legal name [2] Taxpayer company legal name

TIN: 123111000 [3] Taxpayer TIN
VAT No: 12341234 [4] VAT number
Downtown location [5] Taxpayer's branch name

Z B C e n t r e C n r
N k w a m e N k r u m a h A v e / F i r s t S t r e e t ,
[6] Taxpayer's branch address
H a r a r e
[email protected] [7] Taxpayer's branch e-mail
(0242)758 891-5 [8] Taxpayer's branch phone
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CREDIT NOTE [9] Static text: Fiscal tax invoice or Fiscal invoice or Credit note or Debit note
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Buyer: [10] Buyer's information
Company ABC, Ltd. [11] Buyer's registered name
Food Market ABC [12] Buyer's trade name
TIN: 19870123 [13] Buyer's TIN
12 Southgate Hwange [14] Buyer's address
[email protected] [15] Buyer's e-mail
(081) 20875 [16] Buyer's phone
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
R e c e i p t C o u n t e r : 1 5 / 4 5 1 F i s c a l d a y N o : 4 5 [17], [18], [19] Receipt numbers, Fiscal day number
I n v o i c e N o : C I S N - 0 0 0 0 4 0 3 2 1 [20] Invoice number
D e v i c e S e r i a l N o : 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 [21] Device serial number
D e v i c e I D : 6 5 4 3 2 1 0 [22] Fiscal device ID
D a t e : 0 3 / 0 7 / 2 3 1 8 : 4 8 [23] Receipt date and time
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Printed ony for Debit and Credit note
CREDITED INVOICE [24] Static text "Credited invoice" or "Debited invoice"
D e v i c e S e r i a l N o : 9 8 7 6 5 4 3 2 1 0 1 2 3 4 5 6 7 8 9 [25]Credited/debited invoice device serial No
R e c e i p t N o : 4 5 0 D a t e : 0 3 / 0 7 / 2 3 1 8 : 4 8 [26], [27] Credited/debited receipt No and date
I n v o i c e N o : C I S N - 0 0 0 0 4 0 3 2 0 [28] Credited/debited invoice No
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
D e s c r i p t i o n A m o u n t List of receipt items, if If line type is discount static text "Discount" is shown.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
I t e m 1 n a m e 1 3 2 0 0 . 0 0 V T [30] , [33] , [34], Item name, total amount, tax code
I t e m 2 w i t h v e r y l o n g n a m e w h i c h d o e s n o t f i t i n
a s i n g l e l i n e
3 e a c h @ 5 0 0 0 . 0 0 1 5 0 0 0 . 0 0 V T [31], [32] item quantity, unit price
I t e m 3 n a m e
0 . 5 5 5 @ 1 0 8 1 . 08 6 0 0 . 0 0 N V
D i s c o u n t : I t e m 4 n a m e - 1 2 0 0 . 0 0 E X
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
T o t a l Z W L 3 0 0 0 0 . 0 0 [35], [36] receipt currency, total amount to pay
Z W L C a s h 5 0 0 0 . 0 0
Z W L C a r d 2 5 0 0 0 . 0 0 [35], [37], [38] receipt currency, payment method, paid amount
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
N u m b e r o f I t e m s : 5.555 [39] number of items
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
V A T % N e t.A
. A m t V A T A m o u n t Tax table
E X 1 2 0 0 . 0 0 0 . 0 0 1 2 0 0 . 0 0
N V 0 6 0 0 . 0 0 0 . 0 0 6 0 0 . 0 0 [40], [41], [42], [43], [44] tax code, tax percent, amount without tax, tax
V T 1 5 2 4 5 2 1 . 7 4 3 6 7 8 . 2 6 2 8 2 0 0 . 0 0 amount, total amount inclusive tax
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
I n v o i c e i s i s s u e d a f t e r p u r c h a s i n g g o o d s [45] Credit/debit/invoice note
[46] QR code
V e r i f c a t i o n c o d e :
4 C 8 B - E 2 7 6 - 6 3 3 3 - 0 4 1 7 [47] Receipt verification code
You can verify this receipt manually at

https://receipt.zimra.org/ [48] URL

Receipt field name
[1] Taxpayer logo


ZB Centre Cnr
Nkwame Nkrumah Ave / First Street,
Harare
------------------------------------------------
FISCAL TAX INVOICE [9] Static text: Fiscal tax invoice or Fiscal invoice or Credit note or Debit note
------------------------------ ------------------
Buyer: [10] Buyer's information
Company ABC, Ltd. [11] Buyer's registered name
Food Market ABC [12] Buyer's trade name
TIN: 19870123 [13] Buyer's TIN
12 Southgate Hwange [14] Buyer's address
[email protected] [15] Buyer's e-mail
(081) 20875 [16] Buyer's phone
------------------------------ ------------------
Receipt Counter: 15/451 Fiscal day No: 45 [17], [18], [19] Receipt numbers, Fiscal day number
Invoice No: CISN-000040321 [20] Invoice number
Device Serial No: 123456789012 34567890 [21] Device serial number
Device ID: 6543210 [22] Fiscal device ID
Date: 03/07/23 18:48 [23] Receipt date and time
------------------------------ ------------------ Printerd ony for Debit and Credit note
D e s c riptio n Amo u nt List of receipt items, if If line type is discount static text "Discount" is shown.
- - - - ------ ---------------------------- ---- - -----
I t e m 1 name 1 3200 . 00 VT [30] , [33] , [34], Item name, total amount, tax code
I t e m 2 with very long name which does n ot f i t in
a s i ngle l ine
3 each @ 5000.00 1 5000.00 VT [31], [32] item quantity, unit price
Ite m 3 name
0 . 5 5 5 @ 1 0 8 1 . 08 6 0 0 . 0 0 NV
Dis c ount:I tem4 name -1 2 0 0 . 0 0 EX
--- - ------ ----------------------------- - - - - - ----
Tot a l ZWL 30 0 0 0 . 0 0 [35], [36] receipt currency, total amount to pay
Z WL Cas h 5 0 0 0 . 0 0
Z WL Car d 25 0 0 0 . 0 0 [35], [37], [38] receipt currency, payment method, paid amount
------------------------------------------------
Number of Items: 5.555 [39] number of items
------------------------------------------------
VA T% N e t.A
.A m t V A T A m o u n t Tax table
E X 1200. 0 0 0 . 0 0 1 2 0 0 . 0 0
N V 0 600. 0 0 0 . 0 0 6 0 0 . 0 0 [40], [41], [42], [43], [44] tax code, tax percent, amount without tax, tax
V T 15 24521. 7 4 3678 . 2 6 28 2 0 0 . 0 0 amount, total amount inclusive tax
- ----- --------------- - -------- - - ---------- - - - - - -
I nvoic e is issued aft e r purcha s i ng goods [45] Credit/debit/invoice note
[46] QR code
Verifcation code:
4C8B-E276-6333-0417 [47] Receipt verification code

https://receipt.zimra.org/ [48] URL

9.2. InvoiceA4 view
InvoiceA4 view is used for tax inclusive, or tax exclusive invoice printed on A4 paper.
Verification code
4C8B-E276-6333-0417 [46]
https://receipt.zimra.org/ [48]
[1] Taxpayer logo [45] QR code
CREDIT INVOICE [9]

SELLER BUYER
Company legal name [2] Company ABC, Ltd. [11]
TIN: 1234567890 [3] Food Market ABC [12]
VAT No: 12345678 [4] TIN: 19870123 [13]
Downtown location [5] 12 Southgate Hwange [14]
ZB Centre Cnr Nkwame Nkrumah Ave/ First Street, Harare [6]
[email protected] [15]
[email protected] [7] (081) 20875 [16]
(0242)758 891-5 [8]
Receipt Counter: 15[17]/451[18] Fiscal day No: 45 [19]

Invoice No: CISN-0000040012 [20] Date: 03/07/23 18:48 [23]
Device Serial No: 12345678901234567890 [21] Fiscal device ID: 674473 [22]
CREDITED INVOICE [24]

Receipt No: 450 [26] Date: 03/07/23 18:48 [27]
Invoice No: CISN-0000040011 [28]
Device Serial No: 12345678901234567890 [25]
Code [29] Description [30] Qty [31] Price [32] VAT Amount
[34] (excl. tax) [33]
12345678 Item1 name 1 13200.00 15% 13200.00
11223344 Item2 name with very long name 3 5000.00 15% 15000.00
which does not fit in a single line
12312312 Item3 name 1 600.00 0% 600.00
12341234 Discount: Item4 name 1 -1200.00 -1200.00
Total [47] 28800.00

Total15% [41] VAT 4320.00 [44]
Invoice total, ZWL [36] 33120.00 [35]
Invoice is issued after purchasing goods according to agreement No555 [49]

Verification code
4C8B-E276-6333-0417 [46]
https://receipt.zimra.org/ [48]
[1] Taxpayer logo [45] QR code
FICAL TAX INVOICE [9]

SELLER BUYER
Company legal name [2] Company ABC, Ltd. [11]
TIN: 1234567890 [3] Food Market ABC [12]
VAT No: 12345678 [4] TIN: 19870123 [13]
Downtown location [5] 12 Southgate Hwange [14]
ZB Centre Cnr Nkwame Nkrumah Ave/ First Street, Harare [6]
[email protected] [15]
[email protected] [7] (081) 20875 [16]
(0242)758 891-5 [8]
Receipt Counter: 15[17]/451[18] Fiscal day No: 45 [19]

Invoice No: CISN-0000040012 [20] Date: 03/07/23 18:48 [23]
Device Serial No: 12345678901234567890 [21] Fiscal device ID: 674473 [22]
Code [29] Description [30] Qty [31] Price [32] VAT Amount
[34] (excl. tax) [33]
12345678 Item1 name 1 13200.00 15% 13200.00
11223344 Item2 name with very long name 3 5000.00 15% 15000.00
which does not fit in a single line
12312312 Item3 name 1 600.00 0% 600.00
12341234 Discount: Item4 name 1 -1200.00 -1200.00
Total [47] 28800.00

Total15% [41] VAT 4320.00 [44]
Invoice total, ZWL [36] 33120.00 [35]
Invoice is issued after purchasing goods according to agreement No555 [49]
9.3. Receipt and invoice view fields descriptions

Fields in “Field name in which device sends data to FDMS” refers to Fiscal Device
Gateway API endpoint submitReceipt fields. Fields in “Field name in which device receives data
from FDMS” refers to Fiscal Device Gateway API endpoint getConfig fields.
Ob. Object Object description Field name in which Field name in which Mandatory
No name device sends data to device receives data
FDMS from FDMS
Taxpayer block
[1] Taxpayer’s Taxpayer’s logo. If printer is not - - N
logo capable to print logo, field is not
displayed.

[2] Taxpayer’s Taxpayer’s company legal name. - taxpayerName Y
name
[3] Taxpayer’s Taxpayer’s identification number, - taxpayerTIN Y
TIN displayed with label “TIN: ”.
[4] Taxpayer’s Taxpayer’s VAT number. Must be - vatNumber Y
VAT No displayed if taxpayer is VAT taxpayer
Taxpayer address and contacts block
[5] Taxpayer’s Taxpayer’s branch name (to which - deviceBranchName Y*
branch fiscal device is assigned) Field
name displayed only if it differs from
Taxpayer’s name.
[6] Taxpayer’s Taxpayer’s branch address, where - deviceBranchAddress Y
branch fiscal device is located.
address Displayed in this order: houseNumber,
street, city, province
[7] Taxpayer’s E-mail address. - deviceBranchContacts. N
branch e- email
mail
[8] Taxpayer’s Phone number. - deviceBranchContacts. N
branch phoneNo
phone
number
Fiscal tax invoice block
[9] Label Static text “FISCAL TAX INVOICE” if - - Y
document is fiscal invoice and
taxpayer is VAT payer or “FISCAL
INVOICE” if document is fiscal invoice
and taxpayer is non VAT payer or
“CREDIT NOTE” if document is credit
note or “DEBIT NOTE” if document is
debit note
Buyer block
Buyer block is displayed only if buyer information is provided.
[10] Block label Static text “Purchaser:”. - - Y
[11] Buyer’s Buyer’s register name (or individual buyerRegisterName - Y
Name. person name, foreign company name
or not registered trader name).
[12] Buyer’s Buyer’s trade name buyerTradeName - N
trade
name
[13] Buyer TIN Buyer’s TIN. buyerTIN - N
[14] Buyer’s Buyer’s address. Displayed in this buyerAddress - N
address order: houseNumber, street, city,
province
[15] Buyer’s e- Buyer’s e-mail address. buyerContacts. - N
mail email
[16] Buyer’s Purchaser’s phone number. Field buyerContacts. - N
phone displayed if not empty. phoneNo
number
Receipt information block
[17] Receipt No Receipt number in fiscal day - current receiptCounter - Y
day receipt counter.
[18] Receipt Receipt global No. receiptGlobalNo - Y
global No
[19] Fiscal day Receipt Fiscal day number. - fiscalDayNo Y
No
[20] Invoice No Receipt’s invoice number must be invoiceNo Y
unique at taxpayer level

[21] Device Fiscal device serial number. - deviceSerialNo Y
Serial No
[22] Device ID Fiscal device ID (assigned by FDMS deviceID - Y
during device registration).
[23] Receipt Receipt date and time. receiptDate - Y
date and
time
Credit note or Debit Note information block (displayed only in case of receipt type Credit Note or Debit
Note)
[24] Label Static text “Credited invoice” or - - Y
“Debited invoice”. Displayed only for
Credit notes and Debit notes
respectively.
[25] Device Device Serial No of credited or creditNote.deviceID - Y
Serial No debited receipt
[26] Receipt Receipt global No of credited or creditNote. - Y
global No debited receipt. receiptGlobalNo
[27] Receipt Date of credited or debited receipt receiptDate of - Y
date credited or debited
receipt
[28] Invoice No Invoice No of credited or debited invoiceNo of - Y
receipts, is unique at taxpayer level credited or debited
receipt
Receipt lines block
[29] Item HS Receipt line item National receiptLineHSCode - N
code Harmonized System code.
[30] Item name Item name. receiptLineName - Y
 If item name does not fit into 1
row it is split into more rows
depending on item name length.
 If ReceiptLineType is Discount
static text “Discount:” is added as
prefix.
[31] Quantity Receipt line item Quantity. May not receiptLineQuantity, - N
be displayed in case quantity is 1.
[32] Unit price Receipt line item unit price. May not receiptLinePrice - N
be displayed in case quantity is 1. If
Quantity is more than 1 word “each”
is shown in Receipt48 view.
[33] Total Receipt line total. receiptLineTotal - Y
amount In case of InvoiceA4 view, amount can
be displayed inclusive or exclusive
tax. In case total amount of exclusive
tax is used, this must be indicated in
column header.
[34] Tax code Tax code of receipt line. taxCode or - N
In case of InvoiceA4 view, tax percent taxPercent
value may be used alternatively.
Receipt settlement block
[35] Currency Receipt currency code. receiptCurrency - Y
[36] Total Total receipt amount to be paid. receiptTotal - Y
receipt
amount
[37] Payment Payment method. moneyTypeCode - Y
method
[38] Total paid Total paid by payment method. paymentAmount - Y
Number of Items block

[39] Number of Number of items in receipt. - - Y
Items SUM(Quantity) of all Sales lines. If
item is weighed weight is added. For
example: if one item is quantitative
and quantity is 4, and another item is
weighed, and weight is 0,555 kg,
number of items should be
4+0,555=4,555. Always positive
number (for credit note Number of
Items also will be showed as positive
number).
Taxes block
Receipt rows are grouped by tax percent and tax code. This block is not shown on receipt, if taxpayer is not VAT
taxpayer.
[40] Tax code Tax code - - N
[41] Vat % Tax percentage. In case of exempt, - - Y
no value is displayed.
[42] Net.Amt Amount without tax, - - Y
salesAmountWithTax - taxAmount
[43] VAT Tax amount taxAmount - Y
[44] Amount Sales amount with tax salesAmountWithTax - Y
[47] Total Used in InvoiceA4 when exclusive tax N
line totals are used. It sums total
amount exclusive tax.
Receipt verification block
[45] QR code Generated QR code. More details in - - N*
Receipt QR code rules.
Optional if printer cannot print QR
picture.
[46] Receipt QR code value (receiptQRData) of - - Y
verification generate QR displayed in four
code characters groups separated by “- “.
More details in Receipt QR code rules.
[48] URL URL for QR validation. - qrUrl Y
[49] Note Note for credit note/debit note/invoice. receiptNotes - Y*
*Mandatory for credit note or debit note.

9.4. Z Report / X Report
Receipt field name


ZB Centre Cnr
Nkwame Nkrumah Ave / First Street,
Harare
------------------------------------------------
Z REPORT [8] Static text: Z REPORT or X REPORT
- - - - - -------- ---------- -------------------------
F i s c a l day No : 45 [9] Fiscal day number
F i s c a l day op ened: 03/0 4/2023 18:01 [10] Fiscal day opening date
F i s c a l day cl osed: 04/0 4/2023 18:01 [11] Fiscal day closing date
D e v i c e Serial No: 98765 43210123456789 [12]Device serial No
D e v i c e Id: 14 50 [13]Device Id
- - - - - -------- ---------- -------------------------
Daily totals [14] Static text: Daily totals
------------------------------------------------ List of counters in particular currency. Currency/counters information is shown only if there are sales with corresponding currency.
ZWL [15] Currency (currencies are in alphabetical order)
------------------------------------------------
Total net sales [16] Static text: Total net sales
N e t , V A T 1 5% 1 0,0 0 0 . 0 0 [17], [18] Static text "Net", tax name, net amount (sales without tax) (ordered by tax percentage descending)
N e t , V A T 9% 5,0 0 0 . 0 0
N e t ,
0% N o n-V AT 1 5,0 0 0 . 0 0
N e t , E x emp t 2 5,0 0 0 . 0 0
Total net amount 5 5,0 0 0 . 0 0 [19], [20] Static text: Total net amount, total amount
------------------------------------------- - - - - -
Total taxes [21] Static text: Total taxes
Tax,VAT 15% 1,5 0 0 . 0 0 [22] [23 ] Static text "Tax", tax name, tax amount (tax amount) (ordered by tax percentage descending)
Tax,VAT 9% 4 5 0 . 0 0
Total tax amount 1,9 5 0 . 0 0 [24], [25] Static text: Total tax amount, total amount
---------------- --------------------------- - - - - -
Total gross sale s [26] Static text: Total gross sales
Total,VAT 15% 1 1,5 0 0 . 0 0 [27], [28 ] Static text "Total", tax name, total amount (sales with tax) (ordered by tax percentage descending)
Total,VAT 9% 5,4 5 0 . 0 0
Total,Non-VAT 0% 1 5,0 0 0 . 0 0
Total,Exempt 2 5,0 0 0 . 0 0
Total gross amou nt 5 6,9 5 0 . 5 0 [29], [30] Static text: Total gross amount, total amount
---------------- --------------------------- - - - - -
Documents Quantity T o t a l a m o u n t [31], [32],[33] Static texts: Documents,Quantity, Total amount
Invoices 50 5 6,9 5 0 . 5 0 [34] ,[35 ],[36] Static text "Invoices", quantity of documents, total amount (sales with tax for invoices)
Credit notes 1 -500 . 0 0 [37], [38 ],[39] Static text "Credit notes", quantity of documents, total amount (sales with tax for credit notes, value can be negative)
Debit notes 1 500 . 0 0 [40] ,[41 ],[42] Static text "Debit notes", quantity of documents, total amount (sales with tax for debit notes)
Total documents 52 5 6,9 5 0 . 5 0 [43], [44], [45] Static text "Total documents", total quantity, total sum of amounts
============================================= = = =
------------------------------------------------
USD
------------------------------------------------
Total net sales
N e t , V A T 1 5% 1,0 0 0 . 0 0
N e t , V A T 9% 1 0 0 . 0 0
N e t ,
0% N o n-V AT 5 0 0 . 0 0
N e t , E x emp t 2,0 0 0 . 0 0
Total net amount 3,6 0 0 . 0 0
------------------------------------------- - - - - -
Total taxes
N e t , V A T 1 5% 150 . 0 0
N e t , V A T 9% 9 . 0 0
N e t , N o n-V AT 0% 0 . 0 0
N e t , E x emp t 0 . 0 0
Total tax amount 159 . 0 0
---------------- ----------------------------- - - -
Total gross sale s
Net,VAT 15% 1,1 5 0 . 0 0
Net,VAT 9% 109 . 0 0
Net,Non-VAT 0% 500 . 0 0
Net,Exempt 2,0 0 0 . 0 0
Total gross amou nt 3,7 5 9 . 0 0
---------------- ----------------------------- - - -
Documents Quantity Total amount
Invoices 10 3,7 5 9 . 0 0
Credit notes 2 -1 0 0 . 0 0
Debit notes 3 1 0 0 . 0 0
Total documents 15 3,7 5 9 . 0 0
========================================= == = = = = =

9.5. Z report and X report fields description
Z report /X report are daily reports. Fields are described according getConfig,
openDay, getStatus APIs, Enums and Fiscal counters.
Ob. No Object name Object description Field name

Taxpayer block
[1] Taxpayer Taxpayer’s company legal name. taxpayerName
name
[2] Taxpayer TIN Taxpayer’s identification number, displayed with taxpayerTIN
label “TIN: ”.
[3] Taxpayer VAT Taxpayer’s VAT number, displayed with label “VAT vatNumber
No No:”. Must be displayed if taxpayer is VAT taxpayer
Taxpayer address and contacts block
[4] Taxpayer’s Taxpayer’s branch name (to which fiscal device is deviceBranchName
branch name assigned) Field displayed only if it differs from
Taxpayer’s name.
[5] Taxpayer’s Taxpayer’s branch address, where fiscal device is deviceBranchAddress
branch located.
address Displayed in this order: houseNumber, street, city,
province
[6] Taxpayer’s E-mail address. deviceBranchContacts.
branch e-mail email
[7] Taxpayer’s Phone number. deviceBranchContacts.
branch phone phoneNo
number
Report block
[8] Label Static text “Z REPORT” or “X REPORT”. If -
FiscalDayStatus is FiscalDayClosed text “Z REPORT”
is shown. If FiscalDayStatus is not FiscalDayClosed
text “X REPORT” is shown.
[9] Fiscal day No Fiscal day number. fiscalDayNo
[10] Fiscal day Fiscal day opening date. fiscalDayOpened
opening date
[11] Fiscal day Fiscal day closing date. Is shown if FiscalDayStatus fiscalDayClosed
closing date is FiscalDayClosed.
[12] Device Serial Fiscal device serial number. deviceSerialNo
No
[13] Device ID Fiscal device ID (assigned by FDMS during device deviceID

registration).
Daily totals block
[14] Label Static text: Daily totals. -
[15] Currency List of counters in particular currency. Block for fiscalCounterCurrency
particular currency is shown only if there are sales
with corresponding currency. Blocks by currency is
listed in alphabetical ascending order by currency
code.
[16] Total net sales Static text “Total net sales”. -
text
[17] Net name List of Net amounts for each tax. taxName
Static text “Net” + tax name.
Taxes are ordered by tax percentage in descending
order. If tax percent is equal to 0%, or exempt –
line for that tax is not shown.
[18] Net amount Total net amount (sales without tax) by tax. SaleByTax – SaleTaxByTax +
NB. Credit note counter is added total because that CreditNoteByTax –
it’s value is negative. CreditNoteTaxByTax +

DebitNoteByTax –
DebitNoteTaxByTax
by particular tax.
[19] Total net Static text “Total net amount” -
amount text
[20] Total net Total net amount for all values, all taxes. Sum of (SaleByTax – SaleTaxByTax
amount NB. Credit note counter is added total because that + CreditNoteByTax –
it’s value is negative. CreditNoteTaxByTax +
DebitNoteByTax -
DebitNoteTaxByTax)
[21] Total taxes Static text “Total taxes”. -
text This block is skipped if no taxes were collected
(there were no sales with tax which percent is
greater than 0%)
[22] Tax name List of Tax amounts for each tax. taxName
Static text “Tax” + tax name.
order. If tax percent is equal to 0%, or exempt –
line for that tax is not shown.
[23] Tax amount Tax amount. SaleTaxByTax +
NB. Credit note counter is added total because that CreditNoteTaxByTax +
it’s value is negative. DebitNoteTaxByTax
by particular tax.
[24] Total tax Static text “Total tax amount” -
amount text
[25] Total tax Total tax amount for all values, all taxes. Sum of (SaleTaxByTax +
amount NB. Credit note counter is added total because that CreditNoteTaxByTax +
it’s value is negative. DebitNoteTaxByTax)
[26] Total gross Static text “Total gross sales”. -
sales text
[27] Tax name List of Total gross amounts for each tax. taxName
Static text “Total” + tax name.
order. If tax percent is equal to 0, or exempt – line
for that tax is not shown.
[28] Gross sales Gross sales amount (sales with tax). SaleByTax + CreditNoteByTax +
amount NB. Credit note counter is added total because that DebitNoteByTax
it’s value is negative. by particular tax.
[29] Total gross Static text “Total gross amount” -
amount text
[30] Total gross Total gross amount for all values, all taxes. Sum of (SaleByTax +
amount NB. Credit note counter is added total because that CreditNoteByTax +
it’s value is negative. DebitNoteByTax)
[31] Documents Static text “Documents”. -
text
[32] Quantity text Static text “Quantity”. -
[33] Total amount Static text “Total amount”. -
text
[34] Invoices text Static text “Invoices”. -
[35] Quantity of Quantity of invoices during fiscal day. Number of issued documents
invoices where ReceiptType=FiscalInvoice
[36] Total amount Total amount (sales with tax for invoices). Sum of SaleByTax
for invoices
[37] Credit notes Static text “Credit notes”. -
text
[38] Quantity of Quantity of credit notes during fiscal day. Number of issued documents
credit notes where ReceiptType=CreditNote

[39] Total amount Total amount (sales with tax for credit notes). Is Sum of CreditNoteByTax
for credit shown with minus sign.
notes
[40] Debit notes Static text “Debit notes”. -
text
[41] Quantity of Quantity of debit notes during fiscal day. Number of issued documents
debit notes where ReceiptType=DebitNote
[42] Total amount Total amount (sales with tax for debit notes). Sum of DebitNoteByTax
for debit notes
[43] Total Static text “Total documents”. -
documents
text
[44] Total quantity Quantity of documents during fiscal day. Number of issued documents
NB. Credit note counter is added total because that
it’s value is negative.
[45] Total amount Total amount for all documents, all taxes. Sum of SaleByTax + Sum of
NB. Credit note counter is added total because that CreditNoteByTax + Sum of
it’s value is negative. DebitNoteByTax

10. RECEIPT QR CODE RULES
Each issued receipt and invoice must contain QR code value printed as text and
preferably also QR code picture (in case printer is capable to print it). QR code represents deep
link URL with receipt identification information. QR code consists of this information:
Name Length* Description

qrUrl URL for QR validation
deviceID 10 Device ID represented in 10 digits number with leading zeros.
receiptDate 8 Invoice date (receiptDate field value) represented in 8 digits (format:
ddMMyyyy).
receiptGlobalNo 10 Receipt global number (receiptGlobalNo field value) issued by device
represented in 10 digits with leading zeros
receiptQrData 16 Receipt QR data field (first 16 hexadecimal characters of MD5 hash from
ReceiptDeviceSignature value).
* - length specifies a fixed length of value, which should be included in QR. In case
value is shorter than indicated length, leading zeros must be added in front.
Example
Name Example No 1 Example No 2
qrUrl https://invoice.zimra.co.zw/ https://invoice.zimra.co.zw/
deviceID 0000000321 0000000322
receiptDate 03042023 04042023
receiptGlobalNo 1112223331 0000001332
receiptQrData 4C8BE27663330417 C10B0476B3B14678
Result https://invoice.zimra.co.zw/00000003210304 https://invoice.zimra.co.zw/00000003220404
(receiptQrCode) 202311122233314C8BE27663330417 20230000001332C10B0476B3B14678
QR

11. CERTIFICATE SIGNING REQUEST (CSR) AND CERTIFICATE EXAMPLES
11.1. Example keys used
NOTE.
Those example keys are supplied only for illustration of CSR and Certificate
generation, they are in unencrypted form and should NEVER BE USED IN REAL LIFE.
Device should generate their own keys and securely store them in encrypted form,
never letting private key to go outside of device.
11.1.1. ECC ECDSA on SECG secp256r1

ECC ECDSA on SECG secp256r1 (ANSI prime256v1, NIST P-256) private key used in
examples:
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIBXgREh8BvsXj0FjjcZ29EQiVjWGJuqHQp55+LlZd6waoAoGCCqGSM49
AwEHoUQDQgAE+79w72O6UYOJc9mfO8EjMEl9uysJaWJ0kVellIj46atl7FAG4NpY
VDe6t5pTSWlM6qCj5qKealESKalMnV32qQ==
-----END EC PRIVATE KEY-----
This key in textual representation form:

Private-Key: (256 bit)
priv:
15:e0:44:48:7c:06:fb:17:8f:41:63:8d:c6:76:f4:
44:22:56:35:86:26:ea:87:42:9e:79:f8:b9:59:77:
ac:1a
pub:
04:fb:bf:70:ef:63:ba:51:83:89:73:d9:9f:3b:c1:
23:30:49:7d:bb:2b:09:69:62:74:91:57:a5:94:88:
f8:e9:ab:65:ec:50:06:e0:da:58:54:37:ba:b7:9a:
53:49:69:4c:ea:a0:a3:e6:a2:9e:6a:51:12:29:a9:
4c:9d:5d:f6:a9
ASN1 OID: prime256v1
NIST CURVE: P-256
11.1.2. RSA 2048

RSA 2048 private key used in examples:
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA52kCd2bXK+W72vC0+KlQ+tLUBNBsYNk9Gg+NPTxfD+92lFg9
sPW8B1MFxTO+Kpw5MRzArB6M3LZ3pj0O525vLcgT301bridwTgpSfzqtoHFhgTox
My94lMiYSK94w2RxslaMyDm4dCXGfU5AlAiuuegVFz056jV/Ik7jFjQLG5GQnRhW
tGkI2TKZLOlBsjhxUKLKPwUCPtkfZmDig/fXE1XigqSOGMoxQ9BTxJ/i8wWU3AR1
Tjou41EFisaOKpan4xqeRnvNrOs0eIccBFRXBCB78tLTZgE9yqgwoQ5oQpNm845O
kFXQ0F770cy0sx+CO2OnpdQisRK8WDx95kJkIQIDAQABAoIBAFar6/KQoBKe7ucn
tIBV2jC3ehV7grwbYVk7bej7jZdIVx9klWaMAyqzG7wqjxUiggE1BazxnEymQtYO
lGB16ko5X8gJD0eBGf0AvLlOXu1yydQ+2WKUaxM+tlqy7gYwvqzO4de0VrOZ2mfg
QSuwvNCAbjXQBrsD4mQVK9SLFYXzHuYPXDVgTnBktjVQpedV+gqdLVo8yMm1Fpv3
bB/tvotBmxHKsVR6AZmGME1ttO0HR4L6Ha4d1ao5FK4+LtvowFSpSssQ7wyczJmO
ualE4qt/S87Fvm1hYU7VLbm7pAcZMa15FhIVcWZar2RRwwhvm7XwZbnippNgETMC
9bDsogECgYEA87D38++I3eCVm+bJ8Qpsu8yKVS2Bqv+dAyFLG9wFmA6OJhNrpQ+f
JxSmv6sxiz492j4I+uHXuo9ylSg8NQmdtouNRD2Gb0Xb5K6W0zftnoj05P8zJkkR
Z9RyoSXppLblazzT6LqUSk1/PWsX3OXlliNEh4babqsU6fartlWrqtECgYEA8xk9
yz46DOKtu5GEl7i2pe2mMXNG3Ed/Bas1mwa1isnKPFjNNGLuMaITYvXDK+/O9hqO
ESWIRg/sjQ1NaHrbZ3izYgqBPyPVX8inA/w+4Yb6CVHY+9KJGVqzqrvlWwkMkd6K
IqL4SQAxWJQ1Ua1znbuB5TZ6tcZ4QcbVVcgB2FECgYEAwK+xn2RLqIUoRvmZu8ou
Z+A3kVpGKVusXwk4RnMWyUDZDSpV91H+2fvuTaejqSIx7hsXJqjk11MNmvsRgC52
UhzOOqMbZWirkoqqH6Eddjl8yoUvgJpN9Pd7HAjKUb98b+rM9DxzfL0CWyIO4E+3
1ZtVWIQ8uzzzcHvnEmlzL8ECgYEA5lPOFpl4yuijDwqLBG3AsGoAgu3j/6XGFgrn
mWC79SnH8XF5y97ILEKR97s/Fov6HXd/j4NuIGPKDsLByvJMmzbjT0sAtmAvNLea

ds4yjeAjW10vJzmNKHalsGiioKRsQnEFlFewwwnptzGFa0PaPWKBajk5/qxzGG9Z
hhMgnGECgYEAh3K9PsQSTT2tjxuOyyYjlDqDn7exl81i8XLeVKDOL7uQM6m3VICo
F8KdKY2hrwe71pQMI6+P+GkDgx4J7qWO1EMZdMDcUDgzQemUQiUuFDFZ7FnUOkUS
2RbcYyo9m5kGzHzfQPAAlk9J1tJ3/xm8Hi44b2ZpiCpHYNW+RtB2qjA=
-----END RSA PRIVATE KEY-----
This key in textual representation form:

RSA Private-Key: (2048 bit, 2 primes)
modulus:
00:e7:69:02:77:66:d7:2b:e5:bb:da:f0:b4:f8:a9:
50:fa:d2:d4:04:d0:6c:60:d9:3d:1a:0f:8d:3d:3c:
5f:0f:ef:76:94:58:3d:b0:f5:bc:07:53:05:c5:33:
be:2a:9c:39:31:1c:c0:ac:1e:8c:dc:b6:77:a6:3d:
0e:e7:6e:6f:2d:c8:13:df:4d:5b:ae:27:70:4e:0a:
52:7f:3a:ad:a0:71:61:81:3a:31:33:2f:78:94:c8:
98:48:af:78:c3:64:71:b2:56:8c:c8:39:b8:74:25:
c6:7d:4e:40:94:08:ae:b9:e8:15:17:3d:39:ea:35:
7f:22:4e:e3:16:34:0b:1b:91:90:9d:18:56:b4:69:
08:d9:32:99:2c:e9:41:b2:38:71:50:a2:ca:3f:05:
02:3e:d9:1f:66:60:e2:83:f7:d7:13:55:e2:82:a4:
8e:18:ca:31:43:d0:53:c4:9f:e2:f3:05:94:dc:04:
75:4e:3a:2e:e3:51:05:8a:c6:8e:2a:96:a7:e3:1a:
9e:46:7b:cd:ac:eb:34:78:87:1c:04:54:57:04:20:
7b:f2:d2:d3:66:01:3d:ca:a8:30:a1:0e:68:42:93:
66:f3:8e:4e:90:55:d0:d0:5e:fb:d1:cc:b4:b3:1f:
82:3b:63:a7:a5:d4:22:b1:12:bc:58:3c:7d:e6:42:
64:21
publicExponent: 65537 (0x10001)
privateExponent:
56:ab:eb:f2:90:a0:12:9e:ee:e7:27:b4:80:55:da:
30:b7:7a:15:7b:82:bc:1b:61:59:3b:6d:e8:fb:8d:
97:48:57:1f:64:95:66:8c:03:2a:b3:1b:bc:2a:8f:
15:22:82:01:35:05:ac:f1:9c:4c:a6:42:d6:0e:94:
60:75:ea:4a:39:5f:c8:09:0f:47:81:19:fd:00:bc:
b9:4e:5e:ed:72:c9:d4:3e:d9:62:94:6b:13:3e:b6:
5a:b2:ee:06:30:be:ac:ce:e1:d7:b4:56:b3:99:da:
67:e0:41:2b:b0:bc:d0:80:6e:35:d0:06:bb:03:e2:
64:15:2b:d4:8b:15:85:f3:1e:e6:0f:5c:35:60:4e:
70:64:b6:35:50:a5:e7:55:fa:0a:9d:2d:5a:3c:c8:
c9:b5:16:9b:f7:6c:1f:ed:be:8b:41:9b:11:ca:b1:
54:7a:01:99:86:30:4d:6d:b4:ed:07:47:82:fa:1d:
ae:1d:d5:aa:39:14:ae:3e:2e:db:e8:c0:54:a9:4a:
cb:10:ef:0c:9c:cc:99:8e:b9:a9:44:e2:ab:7f:4b:
ce:c5:be:6d:61:61:4e:d5:2d:b9:bb:a4:07:19:31:
ad:79:16:12:15:71:66:5a:af:64:51:c3:08:6f:9b:
b5:f0:65:b9:e2:a6:93:60:11:33:02:f5:b0:ec:a2:
01
prime1:
00:f3:b0:f7:f3:ef:88:dd:e0:95:9b:e6:c9:f1:0a:
6c:bb:cc:8a:55:2d:81:aa:ff:9d:03:21:4b:1b:dc:
05:98:0e:8e:26:13:6b:a5:0f:9f:27:14:a6:bf:ab:
31:8b:3e:3d:da:3e:08:fa:e1:d7:ba:8f:72:95:28:
3c:35:09:9d:b6:8b:8d:44:3d:86:6f:45:db:e4:ae:
96:d3:37:ed:9e:88:f4:e4:ff:33:26:49:11:67:d4:
72:a1:25:e9:a4:b6:e5:6b:3c:d3:e8:ba:94:4a:4d:
7f:3d:6b:17:dc:e5:e5:96:23:44:87:86:da:6e:ab:
14:e9:f6:ab:b6:55:ab:aa:d1
prime2:
00:f3:19:3d:cb:3e:3a:0c:e2:ad:bb:91:84:97:b8:
b6:a5:ed:a6:31:73:46:dc:47:7f:05:ab:35:9b:06:
b5:8a:c9:ca:3c:58:cd:34:62:ee:31:a2:13:62:f5:

c3:2b:ef:ce:f6:1a:8e:11:25:88:46:0f:ec:8d:0d:
4d:68:7a:db:67:78:b3:62:0a:81:3f:23:d5:5f:c8:
a7:03:fc:3e:e1:86:fa:09:51:d8:fb:d2:89:19:5a:
b3:aa:bb:e5:5b:09:0c:91:de:8a:22:a2:f8:49:00:
31:58:94:35:51:ad:73:9d:bb:81:e5:36:7a:b5:c6:
78:41:c6:d5:55:c8:01:d8:51
exponent1:
00:c0:af:b1:9f:64:4b:a8:85:28:46:f9:99:bb:ca:
2e:67:e0:37:91:5a:46:29:5b:ac:5f:09:38:46:73:
16:c9:40:d9:0d:2a:55:f7:51:fe:d9:fb:ee:4d:a7:
a3:a9:22:31:ee:1b:17:26:a8:e4:d7:53:0d:9a:fb:
11:80:2e:76:52:1c:ce:3a:a3:1b:65:68:ab:92:8a:
aa:1f:a1:1d:76:39:7c:ca:85:2f:80:9a:4d:f4:f7:
7b:1c:08:ca:51:bf:7c:6f:ea:cc:f4:3c:73:7c:bd:
02:5b:22:0e:e0:4f:b7:d5:9b:55:58:84:3c:bb:3c:
f3:70:7b:e7:12:69:73:2f:c1
exponent2:
00:e6:53:ce:16:99:78:ca:e8:a3:0f:0a:8b:04:6d:
c0:b0:6a:00:82:ed:e3:ff:a5:c6:16:0a:e7:99:60:
bb:f5:29:c7:f1:71:79:cb:de:c8:2c:42:91:f7:bb:
3f:16:8b:fa:1d:77:7f:8f:83:6e:20:63:ca:0e:c2:
c1:ca:f2:4c:9b:36:e3:4f:4b:00:b6:60:2f:34:b7:
9a:76:ce:32:8d:e0:23:5b:5d:2f:27:39:8d:28:76:
a5:b0:68:a2:a0:a4:6c:42:71:05:94:57:b0:c3:09:
e9:b7:31:85:6b:43:da:3d:62:81:6a:39:39:fe:ac:
73:18:6f:59:86:13:20:9c:61
coefficient:
00:87:72:bd:3e:c4:12:4d:3d:ad:8f:1b:8e:cb:26:
23:94:3a:83:9f:b7:b1:97:cd:62:f1:72:de:54:a0:
ce:2f:bb:90:33:a9:b7:54:80:a8:17:c2:9d:29:8d:
a1:af:07:bb:d6:94:0c:23:af:8f:f8:69:03:83:1e:
09:ee:a5:8e:d4:43:19:74:c0:dc:50:38:33:41:e9:
94:42:25:2e:14:31:59:ec:59:d4:3a:45:12:d9:16:
dc:63:2a:3d:9b:99:06:cc:7c:df:40:f0:00:96:4f:
49:d6:d2:77:ff:19:bc:1e:2e:38:6f:66:69:88:2a:
47:60:d5:be:46:d0:76:aa:30
11.2. CSRs and Certificates

In examples we assume that device has:
 Keys described in “11.1 Example keys used”.

 deviceId is 42.
 Assigned by ZIMRA device name for use in CSR Subject CN is “ZIMRA-SN0001-
0000000042”.
11.2.1. ECC ECDSA on SECG secp256r1

11.2.1.1. CSR
ECC ECDSA on SECG secp256r1 CSR:
-----BEGIN CERTIFICATE REQUEST-----
MIHYMIGAAgEAMB4xHDAaBgNVBAMME1pSQi1lVkZELTAwMDAwMDAwNDIwWTATBgcq
hkjOPQIBBggqhkjOPQMBBwNCAAT7v3DvY7pRg4lz2Z87wSMwSX27KwlpYnSRV6WU
iPjpq2XsUAbg2lhUN7q3mlNJaUzqoKPmop5qURIpqUydXfapoAAwCgYIKoZIzj0E
AwIDRwAwRAIgLMEJQDh18bUE9waT2UXzP0+8FcGukpcIegMxd1A4JaQCIAZkzmEH
e0aaZ2jIcZArZo+rWzI4IwnSXtJqXLrpGUML
-----END CERTIFICATE REQUEST-----

In textual representation form:
Certificate Request:
Data:
Version: 1 (0x0)
Subject: CN = ZIMRA-SN0001-0000000042
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (256 bit)
pub:
04:fb:bf:70:ef:63:ba:51:83:89:73:d9:9f:3b:c1:
23:30:49:7d:bb:2b:09:69:62:74:91:57:a5:94:88:
f8:e9:ab:65:ec:50:06:e0:da:58:54:37:ba:b7:9a:
53:49:69:4c:ea:a0:a3:e6:a2:9e:6a:51:12:29:a9:
4c:9d:5d:f6:a9
NIST CURVE: P-256
Attributes:
a0:00
Signature Algorithm: ecdsa-with-SHA256
30:44:02:20:2c:c1:09:40:38:75:f1:b5:04:f7:06:93:d9:45:
f3:3f:4f:bc:15:c1:ae:92:97:08:7a:03:31:77:50:38:25:a4:
02:20:06:64:ce:61:07:7b:46:9a:67:68:c8:71:90:2b:66:8f:
ab:5b:32:38:23:09:d2:5e:d2:6a:5c:ba:e9:19:43:0b
11.2.1.2. Certificate
ECC ECDSA on SECG secp256r1 Certificate:
-----BEGIN CERTIFICATE-----
MIIC6TCCAdGgAwIBAgIFAKsSzWowDQYJKoZIhvcNAQELBQAwZDELMAkGA1UEBhMC
TFQxETAPBgNVBAoMCEdvb2QgTHRkMScwJQYDVQQLDB5Hb29kIEx0ZCBDZXJ0aWZp
Y2F0ZSBBdXRob3JpdHkxGTAXBgNVBAMMEEdvb2QgTHRkIFJvb3QgQ0EwHhcNMTkx
MDAzMTU1NzA1WhcNMjAxMDEyMTU1NzA1WjBfMQswCQYDVQQGEwJUWjERMA8GA1UE
CAwIWmFuemliYXIxHzAdBgNVBAoMFlphbnppYmFyIFJldmVudWUgQm9hcmQxHDAa
BgNVBAMME1pSQi1lVkZELTAwMDAwMDAwNDIwWTATBgcqhkjOPQIBBggqhkjOPQMB
BwNCAAT7v3DvY7pRg4lz2Z87wSMwSX27KwlpYnSRV6WUiPjpq2XsUAbg2lhUN7q3
mlNJaUzqoKPmop5qURIpqUydXfapo3IwcDAJBgNVHRMEAjAAMB8GA1UdIwQYMBaA
FK1RXHm1plvaintqlWaXDs1X3LX+MB0GA1UdDgQWBBRqr96XrCUbuwCQawxO0//n
TOCoNTAOBgNVHQ8BAf8EBAMCBeAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwDQYJKoZI
hvcNAQELBQADggEBANr1Wk1cVZB96yobFgK3rQQv9oXW+Jle7Jh36J2o4wSSB+RH
lfMojDrqKVQCLrFDcF+8JIA3RTRKdduIXgBAr13xQ8JkHd1/o23yN6a2DaYgh0wr
DrndlR6y1yG0vQuurJ3IgXmC0ldM5+VhalgmoCKFV9JsUD+GhOyJ6NWlc0SqvJCs
3RZLYwZ4MNViPbRy0Kbp0ufY1zTbh02Gw9aVfFzUwL8GS00iMb4MnSav1xur7wQh
BoF3PpNvu003P7f1eVJ62qVD2LWWntfn0mL1aRmDe2wpMQKAKhxto+sDb2mfJ6G6
PFtwMHe7BUfiwTzGYqav21h1w/amPkxNVQ7Li4M=
-----END CERTIFICATE-----

Certificate:
Data:
Version: 3 (0x2)
Serial Number:
ab:12:cd:6a
Signature Algorithm: sha256WithRSAEncryption
Issuer: C = LT, O = Good Ltd, OU = Good Ltd Certificate Authority, CN
= Good Ltd Root CA
Validity
Not Before: Oct 3 15:57:05 2019 GMT
Not After : Oct 12 15:57:05 2020 GMT
Subject: C = ZW, O = Zimbabwe Revenue Authority, CN = ZIMRA-SN0001-
0000000042
Public Key Algorithm: id-ecPublicKey

Public-Key: (256 bit)
pub:
04:fb:bf:70:ef:63:ba:51:83:89:73:d9:9f:3b:c1:
23:30:49:7d:bb:2b:09:69:62:74:91:57:a5:94:88:
f8:e9:ab:65:ec:50:06:e0:da:58:54:37:ba:b7:9a:
53:49:69:4c:ea:a0:a3:e6:a2:9e:6a:51:12:29:a9:
4c:9d:5d:f6:a9
NIST CURVE: P-256
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
X509v3 Authority Key Identifier:
keyid:AD:51:5C:79:B5:A6:5B:DA:8A:7B:6A:95:66:97:0E:CD:57:DC:B5:FE
X509v3 Subject Key Identifier:

6A:AF:DE:97:AC:25:1B:BB:00:90:6B:0C:4E:D3:FF:E7:4C:E0:A8:35
X509v3 Key Usage: critical
Digital Signature, Non Repudiation, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Client Authentication
da:f5:5a:4d:5c:55:90:7d:eb:2a:1b:16:02:b7:ad:04:2f:f6:
85:d6:f8:99:5e:ec:98:77:e8:9d:a8:e3:04:92:07:e4:47:95:
f3:28:8c:3a:ea:29:54:02:2e:b1:43:70:5f:bc:24:80:37:45:
34:4a:75:db:88:5e:00:40:af:5d:f1:43:c2:64:1d:dd:7f:a3:
6d:f2:37:a6:b6:0d:a6:20:87:4c:2b:0e:b9:dd:95:1e:b2:d7:
21:b4:bd:0b:ae:ac:9d:c8:81:79:82:d2:57:4c:e7:e5:61:6a:
58:26:a0:22:85:57:d2:6c:50:3f:86:84:ec:89:e8:d5:a5:73:
44:aa:bc:90:ac:dd:16:4b:63:06:78:30:d5:62:3d:b4:72:d0:
a6:e9:d2:e7:d8:d7:34:db:87:4d:86:c3:d6:95:7c:5c:d4:c0:
bf:06:4b:4d:22:31:be:0c:9d:26:af:d7:1b:ab:ef:04:21:06:
81:77:3e:93:6f:bb:4d:37:3f:b7:f5:79:52:7a:da:a5:43:d8:
b5:96:9e:d7:e7:d2:62:f5:69:19:83:7b:6c:29:31:02:80:2a:
1c:6d:a3:eb:03:6f:69:9f:27:a1:ba:3c:5b:70:30:77:bb:05:
47:e2:c1:3c:c6:62:a6:af:db:58:75:c3:f6:a6:3e:4c:4d:55:
0e:cb:8b:83
11.2.2. RSA 2048

11.2.2.1. CSR
RSA 2048 CSR:
-----BEGIN CERTIFICATE REQUEST-----
MIICYzCCAUsCAQAwHjEcMBoGA1UEAwwTWlJCLWVWRkQtMDAwMDAwMDA0MjCCASIw
DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOdpAndm1yvlu9rwtPipUPrS1ATQ
bGDZPRoPjT08Xw/vdpRYPbD1vAdTBcUzviqcOTEcwKwejNy2d6Y9Duduby3IE99N
W64ncE4KUn86raBxYYE6MTMveJTImEiveMNkcbJWjMg5uHQlxn1OQJQIrrnoFRc9
Oeo1fyJO4xY0CxuRkJ0YVrRpCNkymSzpQbI4cVCiyj8FAj7ZH2Zg4oP31xNV4oKk
jhjKMUPQU8Sf4vMFlNwEdU46LuNRBYrGjiqWp+MankZ7zazrNHiHHARUVwQge/LS
02YBPcqoMKEOaEKTZvOOTpBV0NBe+9HMtLMfgjtjp6XUIrESvFg8feZCZCECAwEA
AaAAMA0GCSqGSIb3DQEBCwUAA4IBAQBeU11K7MWhroA8Fz3O2KXI7fJqc7sj9Ip/
jhNlISfi8fJ3M3i58KqMSuXuBPF6Wv8NSncr3CmLa6noOZnfWTfrWG+4vLYi5MfA
//6orI54K8kOe1NFk4Hr+QdUtdFJ8/6AE9a5dwpo4IHSWR23kz7lAjgxrx29y2UF
9Ad4j8CM0NQifL5KHN5lEmhlDP/JCkmlMBkumSS8f1RfijWvnJ0mMc+Tbe+giMpp
qYE8b0Eqku+I3cKfVb4s7TJd6KNi6BEe2EYgczKUxdIsrZy8SgqKE7iRstPo/Xgq
o02dqr4n1W0pFUHntP9M1lhqeoXHZcrC5ShdDpSYO/1DP5Jh9Vg9
-----END CERTIFICATE REQUEST-----

Certificate Request:

Data:
Version: 1 (0x0)
Subject: CN = ZIMRA-SN0001-0000000042
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:e7:69:02:77:66:d7:2b:e5:bb:da:f0:b4:f8:a9:
50:fa:d2:d4:04:d0:6c:60:d9:3d:1a:0f:8d:3d:3c:
5f:0f:ef:76:94:58:3d:b0:f5:bc:07:53:05:c5:33:
0e:e7:6e:6f:2d:c8:13:df:4d:5b:ae:27:70:4e:0a:
52:7f:3a:ad:a0:71:61:81:3a:31:33:2f:78:94:c8:
98:48:af:78:c3:64:71:b2:56:8c:c8:39:b8:74:25:
c6:7d:4e:40:94:08:ae:b9:e8:15:17:3d:39:ea:35:
7f:22:4e:e3:16:34:0b:1b:91:90:9d:18:56:b4:69:
08:d9:32:99:2c:e9:41:b2:38:71:50:a2:ca:3f:05:
02:3e:d9:1f:66:60:e2:83:f7:d7:13:55:e2:82:a4:
8e:18:ca:31:43:d0:53:c4:9f:e2:f3:05:94:dc:04:
75:4e:3a:2e:e3:51:05:8a:c6:8e:2a:96:a7:e3:1a:
9e:46:7b:cd:ac:eb:34:78:87:1c:04:54:57:04:20:
7b:f2:d2:d3:66:01:3d:ca:a8:30:a1:0e:68:42:93:
66:f3:8e:4e:90:55:d0:d0:5e:fb:d1:cc:b4:b3:1f:
82:3b:63:a7:a5:d4:22:b1:12:bc:58:3c:7d:e6:42:
64:21
Exponent: 65537 (0x10001)
Attributes:
a0:00
5e:53:5d:4a:ec:c5:a1:ae:80:3c:17:3d:ce:d8:a5:c8:ed:f2:
6a:73:bb:23:f4:8a:7f:8e:13:65:21:27:e2:f1:f2:77:33:78:
b9:f0:aa:8c:4a:e5:ee:04:f1:7a:5a:ff:0d:4a:77:2b:dc:29:
8b:6b:a9:e8:39:99:df:59:37:eb:58:6f:b8:bc:b6:22:e4:c7:
c0:ff:fe:a8:ac:8e:78:2b:c9:0e:7b:53:45:93:81:eb:f9:07:
54:b5:d1:49:f3:fe:80:13:d6:b9:77:0a:68:e0:81:d2:59:1d:
b7:93:3e:e5:02:38:31:af:1d:bd:cb:65:05:f4:07:78:8f:c0:
8c:d0:d4:22:7c:be:4a:1c:de:65:12:68:65:0c:ff:c9:0a:49:
a5:30:19:2e:99:24:bc:7f:54:5f:8a:35:af:9c:9d:26:31:cf:
93:6d:ef:a0:88:ca:69:a9:81:3c:6f:41:2a:92:ef:88:dd:c2:
9f:55:be:2c:ed:32:5d:e8:a3:62:e8:11:1e:d8:46:20:73:32:
94:c5:d2:2c:ad:9c:bc:4a:0a:8a:13:b8:91:b2:d3:e8:fd:78:
2a:a3:4d:9d:aa:be:27:d5:6d:29:15:41:e7:b4:ff:4c:d6:58:
6a:7a:85:c7:65:ca:c2:e5:28:5d:0e:94:98:3b:fd:43:3f:92:
61:f5:58:3d
11.2.2.2. Certificate
RSA 2048 Certificate:
-----BEGIN CERTIFICATE-----
MIIDtDCCApygAwIBAgIFAKsSzWswDQYJKoZIhvcNAQELBQAwZDELMAkGA1UEBhMC
TFQxETAPBgNVBAoMCEdvb2QgTHRkMScwJQYDVQQLDB5Hb29kIEx0ZCBDZXJ0aWZp
Y2F0ZSBBdXRob3JpdHkxGTAXBgNVBAMMEEdvb2QgTHRkIFJvb3QgQ0EwHhcNMTkx
MDAzMTU1NzE2WhcNMjAxMDEyMTU1NzE2WjBfMQswCQYDVQQGEwJUWjERMA8GA1UE
CAwIWmFuemliYXIxHzAdBgNVBAoMFlphbnppYmFyIFJldmVudWUgQm9hcmQxHDAa
BgNVBAMME1pSQi1lVkZELTAwMDAwMDAwNDIwggEiMA0GCSqGSIb3DQEBAQUAA4IB
DwAwggEKAoIBAQDnaQJ3Ztcr5bva8LT4qVD60tQE0Gxg2T0aD409PF8P73aUWD2w
9bwHUwXFM74qnDkxHMCsHozctnemPQ7nbm8tyBPfTVuuJ3BOClJ/Oq2gcWGBOjEz
L3iUyJhIr3jDZHGyVozIObh0JcZ9TkCUCK656BUXPTnqNX8iTuMWNAsbkZCdGFa0
aQjZMpks6UGyOHFQoso/BQI+2R9mYOKD99cTVeKCpI4YyjFD0FPEn+LzBZTcBHVO
Oi7jUQWKxo4qlqfjGp5Ge82s6zR4hxwEVFcEIHvy0tNmAT3KqDChDmhCk2bzjk6Q
VdDQXvvRzLSzH4I7Y6el1CKxErxYPH3mQmQhAgMBAAGjcjBwMAkGA1UdEwQCMAAw
HwYDVR0jBBgwFoAUrVFcebWmW9qKe2qVZpcOzVfctf4wHQYDVR0OBBYEFDLA7tgo

7/JLz5ayFa4HP3a7Kyf2MA4GA1UdDwEB/wQEAwIF4DATBgNVHSUEDDAKBggrBgEF
BQcDAjANBgkqhkiG9w0BAQsFAAOCAQEAI7n2fUonnpbOJCUaX7/bDwDmdQ2SEJfH
ro/rWfp/fhD8sBK0ZzZ0AzHH2OszBQOwBqX3+hyMMwAyBlsHdan97lvdNuSZtTnm
HjtuOFYuF9o69BMCPMNHgj3XhikuNlh7NPzr1nU2ec6/tgx5guosoo0gZNsCpdbt
ee4pJydnA4vmx4c6wbEWBJA1YhZLloGi9VR2NVI0OnxYuvlinqIHvNypJL+3aDT5
yvjRY+suDkF+u3J8nRlrxc22b/YvPu3U4BhK6FJk/JSxy3qOMz1EUR4uPt9ci06E
5OhpF9PSdcWt8NtC4f+i4EtwGcsj5XHplOWN+KoOksK9ZcwaJpQ7DQ==
-----END CERTIFICATE-----

Certificate:
Data:
Version: 3 (0x2)
Serial Number:
ab:12:cd:6b
Issuer: C = LT, O = Good Ltd, OU = Good Ltd Certificate Authority, CN
= Good Ltd Root CA
Validity
Not Before: Oct 3 15:57:16 2019 GMT
Not After : Oct 12 15:57:16 2020 GMT
Subject: C = ZW, O = Zimbabwe Revenue Authority, CN = ZIMRA-SN0001-
0000000042
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:e7:69:02:77:66:d7:2b:e5:bb:da:f0:b4:f8:a9:
50:fa:d2:d4:04:d0:6c:60:d9:3d:1a:0f:8d:3d:3c:
5f:0f:ef:76:94:58:3d:b0:f5:bc:07:53:05:c5:33:
0e:e7:6e:6f:2d:c8:13:df:4d:5b:ae:27:70:4e:0a:
52:7f:3a:ad:a0:71:61:81:3a:31:33:2f:78:94:c8:
98:48:af:78:c3:64:71:b2:56:8c:c8:39:b8:74:25:
c6:7d:4e:40:94:08:ae:b9:e8:15:17:3d:39:ea:35:
7f:22:4e:e3:16:34:0b:1b:91:90:9d:18:56:b4:69:
08:d9:32:99:2c:e9:41:b2:38:71:50:a2:ca:3f:05:
02:3e:d9:1f:66:60:e2:83:f7:d7:13:55:e2:82:a4:
8e:18:ca:31:43:d0:53:c4:9f:e2:f3:05:94:dc:04:
75:4e:3a:2e:e3:51:05:8a:c6:8e:2a:96:a7:e3:1a:
9e:46:7b:cd:ac:eb:34:78:87:1c:04:54:57:04:20:
7b:f2:d2:d3:66:01:3d:ca:a8:30:a1:0e:68:42:93:
66:f3:8e:4e:90:55:d0:d0:5e:fb:d1:cc:b4:b3:1f:
82:3b:63:a7:a5:d4:22:b1:12:bc:58:3c:7d:e6:42:
64:21
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Basic Constraints:
CA:FALSE
X509v3 Authority Key Identifier:
keyid:AD:51:5C:79:B5:A6:5B:DA:8A:7B:6A:95:66:97:0E:CD:57:DC:B5:FE
X509v3 Subject Key Identifier:

32:C0:EE:D8:28:EF:F2:4B:CF:96:B2:15:AE:07:3F:76:BB:2B:27:F6
X509v3 Key Usage: critical
Digital Signature, Non Repudiation, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Client Authentication
23:b9:f6:7d:4a:27:9e:96:ce:24:25:1a:5f:bf:db:0f:00:e6:

75:0d:92:10:97:c7:ae:8f:eb:59:fa:7f:7e:10:fc:b0:12:b4:
67:36:74:03:31:c7:d8:eb:33:05:03:b0:06:a5:f7:fa:1c:8c:
33:00:32:06:5b:07:75:a9:fd:ee:5b:dd:36:e4:99:b5:39:e6:
1e:3b:6e:38:56:2e:17:da:3a:f4:13:02:3c:c3:47:82:3d:d7:
86:29:2e:36:58:7b:34:fc:eb:d6:75:36:79:ce:bf:b6:0c:79:
82:ea:2c:a2:8d:20:64:db:02:a5:d6:ed:79:ee:29:27:27:67:
03:8b:e6:c7:87:3a:c1:b1:16:04:90:35:62:16:4b:96:81:a2:
f5:54:76:35:52:34:3a:7c:58:ba:f9:62:9e:a2:07:bc:dc:a9:
24:bf:b7:68:34:f9:ca:f8:d1:63:eb:2e:0e:41:7e:bb:72:7c:
9d:19:6b:c5:cd:b6:6f:f6:2f:3e:ed:d4:e0:18:4a:e8:52:64:
fc:94:b1:cb:7a:8e:33:3d:44:51:1e:2e:3e:df:5c:8b:4e:84:
e4:e8:69:17:d3:d2:75:c5:ad:f0:db:42:e1:ff:a2:e0:4b:70:
19:cb:23:e5:71:e9:94:e5:8d:f8:aa:0e:92:c2:bd:65:cc:1a:
26:94:3b:0d

12.SIGNATURES GENERATION AND VERIFICATION RULES
12.1. Signature an hash generation algorithm
Below algorithm is used to generate receipt and fiscal day hash and signature:
1) Receipt or fiscal day fields must be converted to string (by rules as described in table
below) and concatenated (no concatenation character is used);
2) Concatenated line must be hashed using SHA256;
3) Hash must be signed with private key.
Formula to get a hash: Hash = SHA-256(x1|| x2||…||xn);

Formula to get a signature:
Signature = RSA(Hash,d,n) – in case RSA keys are used
or
Signature = ECC(Hash,CURVE,g,n) – in case ECC keys are used
Where
|| - means field concatenation;
x1, x2, …, xn - receipt or fiscal day fields;
d – secret RSA exponent;
n - RSA modulus
CURVE – the elliptic curve field and equation used
G – elliptic curve base point, a point on the curve that generates a subgroup of large
prime order n
n – integer order of G, means that n x G=O, where O is the identity element.
12.2. Receipt signature generation and verification

Receipt hash and signature are generated according to the rules provided in section
12.1.
12.2.1. Receipt device signature

Fields included in receipt hash which is used for device signature are (these fields must
be included in hash in the same order as provided below):
Order Field name Description
1 deviceID Device ID
2 receiptType Receipt type value in upper case.
3 receiptCurrency Currency code (ISO 4217 currency code).
4 receiptGlobalNo Receipt global number.
5 receiptDate Date in ISO 8601 format <date>T<time>, YYYY-MM-DDTHH:mm:ss (hours are
represented in 24 hours format, local time).
Example: 2019-09-23T14:43:23
6 receiptTotal Receipt total is included in signature in cents.
Examples:
- If receiptTotal is 500 ZWL, value 50000 must be used in signature.
- If receiptTotal is 12,34 USD, value 1234 must be used in signature.
- If receiptTotal is 0,05 USD, value 5 must be used in signature.
7 receiptTaxes Concatenated receiptTaxes, where each line is concatenated in this way:
taxCode || taxPercent || taxAmount || salesAmountWithTax.
In case of taxPercent is not sent, empty value should be used in signature.

Amounts are represented in cents. In case taxPercent is not an integer
there should be dot between the integer and fractional part. In case of

exempt which does not send tax percent value, empty value should be used
in signature.
In case taxPercent is an integer there should be value of tax percent, dot
and two zeros sent.
Taxes are ordered by taxID in ascending order and taxCode in alphabetical
order (if taxCode is empty it is ordered before A letter).
Examples:
- If taxPercent is 15, value 15.00 must be used in signature.
- If taxPercent is 14.5 value 14.50 must be used in signature.
- If taxPercent is 0 value 0.00 must be used in signature.
8 previousReceiptHash Previous receipt hash is included into current receipt device signature. This
will create a chain of receipts.
This field is not used in signature when current receipt is first in fiscal day.
FiscalInvoice Examples
Name Example No 1
deviceID 321
receiptType FISCALINVOICE
receiptCurrency ZWL
receiptGlobalNo 432
receiptDate 2019-09-19T15:43:12
receiptTotal 9450,00
receiptTaxes Tax lines:
taxID taxCode taxPercent taxAmount salesAmountWithTax
1 A 0,00 2500,00
2 B 0 0,00 3500,00
3 C 15 150,00 1150,00
3 D 15 300,00 2300,00
Result:
A0250000B0.000350000C15.0015000115000D15.0030000230000
previousReceiptHash hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Result used for hash 321FISCALINVOICEZWL4322019-09-
generation 19T15:43:12945000A0250000B0.000350000C15.0015000115000D15.0030000230000
hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Generated receipt hash in zDxEalWUpwX2BcsYxRUAEfY/13OaCrTwDt01So3a6uU=
base64 representation
Name Example No 2
deviceID 322
receiptType FISCALINVOICE
receiptCurrency USD
receiptGlobalNo 85
receiptDate 2019-09-19T09:23:07
receiptTotal 40,35
taxID taxPercent taxAmount salesAmountWithTax
1 0,00 7,00
2 0 0,00 10,00
3 14,5 0,05 0,35
Result:
07000.000100014.50535
Result used for hash 07000.000100014.50535 hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
generation
Generated receipt hash in 2zInR7ciOQ9PbtQlKaU5XoktQ/4/y1XShfzEEoSVO7s=
CreditNote Examples
Name Example No 1

deviceID 321
receiptType CREDITNOTE
receiptCurrency ZWL
receiptGlobalNo 432
receiptDate 2020-09-19T15:43:12
receiptTotal -9450,00
1 A 0,00 -2500,00
2 B 0 0,00 -3500,00
3 C 15 -150,00 -1150,00
3 D 15 -300,00 -2300,00
Result:
A0-250000B0.000-350000C15.00-15000-115000D15.00-30000-230000
Result used for hash 321CREDITNOTEZWL4322020-09-19T15:43:12-945000 A0-250000B0.000-350000C15.00-15000-
generation 115000D15.00-30000-230000hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Generated receipt hash in Wu21g3N0fPIa67pnAp+FZkaEfBiv696B+4QoJCWRIcY=
Name Example No 2
deviceID 322
receiptType CREDITNOTE
receiptCurrency USD
receiptGlobalNo 85
receiptDate 2020-09-19T09:23:07
receiptTotal -40,35
1 0,00 -7,00
2 0 0,00 -10,00
3 14,5 -3,00 -23,00
Result:
0-7000.000-100014.50-300-2300
Result used for hash 322CREDITNOTEUSD852020-09-19T09:23:07-40350-7000.000-100014.50-300-
generation 2300hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Generated receipt hash in F9/QB0vhxQlEF2nk+oebwP8V+qBcNlOFvoTeE/1QxPc=
DebitNote Examples
Name Example No 1
deviceID 321
receiptType DEBITNOTE
receiptCurrency ZWL
receiptGlobalNo 432
receiptDate 2020-09-19T15:43:12
receiptTotal 9450,00
1 A 0,00 2500,00
2 B 0 0,00 3500,00
3 C 15 150,00 1150,00
3 C 15 300,00 2300,00
Result:
A0250000B0.000350000C15.0015000115000D15.0030000230000

Result used for hash 321DEBITNOTEZWL4322020-09-19T15:43:12945000
generation A0250000B0.000350000C15.0015000115000D15.0030000230000hNVJXP/ACOiE8McD3pKsDlqBXpuaUq
QOfPnMyfZWI9k=
Generated receipt hash in PHcormpq5Ppb/6Quh8iOY3bDq4B4cPW5hsENb65iK/I=
Name Example No 2
deviceID 322
receiptType DEBITNOTE
receiptCurrency USD
receiptGlobalNo 85
receiptDate 2020-09-19T09:23:07
receiptTotal 40,35
1 0,00 7,00
2 0 0,00 10,00
3 14,5 3,00 23,00
Result:
07000.000100014.503002300
Result used for hash 322DEBITNOTEUSD852020-09-19T09:23:
generation 07403507000.000100014.503002300hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Generated receipt hash in YOLYzYhCaaLN2yxrM574B83WUhxSkg52uc1hrM4g8Dw=
12.2.2. Receipt FDMS signature

Receipt FDMS signature may be verified by decrypting receiptServerSignature with FDMS
public key and comparing if it matches with prepared receipt hash. receiptServerSignature is
generated only for receipt submitted in “Online” receipt mode. Hash generation algorithm is
provided in section 12.1.
Fields included in receipt hash which is used for FDMS signature are (these fields must
be included in hash in the same order as provided below):
1 receiptDeviceSignature Receipt signature generated by device.
2 receiptID Receipt ID
3 serverDate Date in ISO 8601 format <date>T<time>, YYYY-MM-DDThh:mm:ss (hours are
Example: 2019-09-23T14:43:23
Example
Name Exmple
receiptDevi YyXTSizBBrMjMk4VQL+sCNr+2AC6aQbDAn9JMV2rk3yJ6MDZwie0wqQW3oisNWrMkeZsuAyFSnFkU2A+pKm91sOHVdjeR
ceSignature BebjQgAQQIMTCVIcYrx+BizQ7Ib9iCdsVI+Jel2nThqQiQzfRef6EgtgsaIAN+PV55xSrHvPkIe+Bc=
receiptID 48377
serverDate 2019-09-19T15:43:12
Result used YyXTSizBBrMjMk4VQL+sCNr+2AC6aQbDAn9JMV2rk3yJ6MDZwie0wqQW3oisNWrMkeZsuAyFSnFkU2A+pKm91sOHVdjeR
for hash BebjQgAQQIMTCVIcYrx+BizQ7Ib9iCdsVI+Jel2nThqQiQzfRef6EgtgsaIAN+PV55xSrHvPkIe+Bc=483772019-09-
generation 19T15:43:12
Generated JQoIo/AgOsvm+PUQpvlQ/U7YMei3m/jbygNrBVfz6Sg=
hash in
base64
representati
on

12.3. Fiscal day signature generation and verification
Fiscal day report hash and signature are generated according to the rules provided in
section 12.1.
12.3.1. Fiscal day device signature

Fields included in fiscal day hash used for device signature are provided below (these
fields must be included in hash in the same order as provided below):
2 fiscalDayNo Fiscal day number
3 fiscalDayDate Fiscal day date (date when fiscal day was opened).
Date in ISO 8601 format YYYY-MM-DD.
Example: 2019-09-23
4 fiscalDayCounters Concatenated fiscal day counter lines, where each line is concatenated in this
way: fiscalCounterType || fiscalCounterCurrency || fiscalCounterTaxPercent or
fiscalCounterMoneyType || fiscalCounterValue.
All text values are concatenated in upper case.

Amounts are represented in cents.
Only non-zero value fiscal counters are included in concatenation.
Fiscal counters are concatenated in this order:
 fiscalCounterType (in ascending order)
 fiscalCounterCurrency (in alphabetical ascending order)
 fiscalCounterTaxID (in ascending order) / fiscalCounterMoneyType (in
ascending order)
In case taxPercent is not an integer there should be dot between the integer and
fractional part. In case of exempt which does not send tax percent value, empty
value should be used in signature. In case taxPercent is an integer there should be
value of tax percent, dot and two zeros sent.
Examples:
- If taxPercent is 15, value 15.00 must be used in signature.
- If taxPercent is 14.5 value 14.50 must be used in signature.
- If taxPercent is 0 value 0.00 must be used in signature.
Example
Name Exmple
deviceID 321
fiscalDayNo 84
fiscalDayDate 2019-09-23
fiscalDayCounters fiscalCounterType fiscalCounterC fiscalCounterTaxPercent/ fiscalCounterValue
urrency fiscalCounterMoneyType
SaleByTax ZWL 23000,00
SaleByTax ZWL 0 12000,00
SaleByTax USD 14,5 25,00
SaleTaxByTax USD 15 2,50
SaleTaxByTax ZWL 15 2300,00
BalanceByMoneyType ZWL CARD 15000,00
BalanceByMoneyType USD CASH 37,00
BalanceByMoneyType ZWL CASH 20000,00
Result:
SALEBYTAXZWL2300000SALEBYTAXZWL0.001200000SALEBYTAXUSD14.502500SALEBYTAXZWL15.001200SA
LETAXBYTAXUSD15.00250SALETAXBYTAXZWL15.00230000BALANCEBYMONEYTYPEUSDLCASH3700BALANCE
BYMONEYTYPEZWLCASH2000000BALANCEBYMONEYTYPEZWLCARD1500000
Result used for hash 321842019-09-
generation 23SALEBYTAXZWL2300000SALEBYTAXZWL0.001200000SALEBYTAXUSD14.502500SALEBYTAXZWL15.001200
SALETAXBYTAXUSD15.00250SALETAXBYTAXZWL15.00230000BALANCEBYMONEYTYPEUSDLCASH3700BALAN
CEBYMONEYTYPEZWLCASH2000000BALANCEBYMONEYTYPEZWLCARD1500000
Generated hash in OdT8lLI0JXhXl1XQgr64Zb1ltFDksFXThVxqM6O8xZE=
base64
representation

12.3.2. Fiscal day FDMS signature
Fiscal day FDMS signature may be verified by decrypting fiscalDayServerSignature with
FDMS public key and comparing if it matches with prepared fiscal day hash.
Hash generation algorithm is provided in section 12.1.
Fields included in fiscal day hash used for FDMS signature are provided below (these
fields must be included in hash in the same order as provided below):
2 fiscalDayNo Fiscal day number
3 fiscalDayDate Fiscal day date (date when fiscal day was opened).
Date in ISO 8601 format YYYY-MM-DD.
Example: 2019-09-23
4 fiscalDayUpdated Date and time when fiscal day was closed.
Date in ISO 8601 format <date>T<time>, YYYY-MM-DDThh:mm:ss (hours are
Example: 2019-09-23T14:43:23
fiscalDayClosed value from response to device.
5 reconciliationMode Defines how fiscal day was close: automatically or manually.
Possible values (in upper case):
- AUTO
- MANUAL
6 fiscalDayCounters Concatenated fiscal day counter lines as described above in device signature
generation.
7 fiscalDayDeviceSignature Fiscal day signature generated by device. In case fiscal day is closed manually, this
field is not included into hash for FDMS signature.
Example
Name Exmple
deviceID 321
fiscalDayNo 84
fiscalDayDate 2019-09-23
fiscalDayUpdated 2019-09-23T22:21:14
reconciliationMode AUTO
fiscalDayCounters fiscalCounterType fiscalCounterC fiscalCounterTaxPercent/ fiscalCounterValue
urrency fiscalCounterMoneyType
SaleByTax ZWL 23000,00
SaleByTax USD 15 25,00
SaleTaxByTax USD 15 2,50
SaleTaxByTax ZWL 15 2300,00
BalanceByMoneyType ZWL CARD 15000,00
BalanceByMoneyType USD CASH 37,00
BalanceByMoneyType ZWL CASH 20000,00
Result:
SALEBYTAXZWL2300000SALEBYTAXZWL0.001200000SALEBYTAXUSD15.002500SALEBYTAXZWL15.001200SALE
TAXBYTAXUSD15.00250SALETAXBYTAXZWL15.00230000BALANCEBYMONEYTYPEZWLCARD1500000BALANCEB
YMONEYTYPEUSDLCASH3700BALANCEBYMONEYTYPEZWLCASH2000000
fiscalDayDeviceSign YyXTSizBBrMjMk4VQL+sCNr+2AC6aQbDAn9JMV2rk3yJ6MDZwie0wqQW3oisNWrMkeZsuAyFSnFkU2A+pKm91sO
ature HVdjeRBebjQgAQQIMTCVIcYrx+BizQ7Ib9iCdsVI+Jel2nThqQiQzfRef6EgtgsaIAN+PV55xSrHvPkIe+Bc=
Result used for 321842019-09-232019-09-
hash generation 23T22:21:14AUTOSALEBYTAXZWL2300000SALEBYTAXZWL0.001200000SALEBYTAXUSD15.002500SALEBYTAXZ
WL15.001200SALETAXBYTAXUSD15.00250SALETAXBYTAXZWL15.00230000BALANCEBYMONEYTYPEZWLCARD1
500000BALANCEBYMONEYTYPEUSDLCASH3700BALANCEBYMONEYTYPEZWLCASH2000000YyXTSizBBrMjMk4VQ
L+sCNr+2AC6aQbDAn9JMV2rk3yJ6MDZwie0wqQW3oisNWrMkeZsuAyFSnFkU2A+pKm91sOHVdjeRBebjQgAQQI
MTCVIcYrx+BizQ7Ib9iCdsVI+Jel2nThqQiQzfRef6EgtgsaIAN+PV55xSrHvPkIe+Bc=
Generated hash in nlqwrAoFAmXLfuMJlQTdS2m0B4d5X1sTJ2gPo5/Dq+s=
base64
representation

Fiscal Device Gateway API v4.2 - Clients-Dual-Translated

Uploaded by

Copyright:

Available Formats

Fiscal Device Gateway API v4.2 - Clients-Dual-Translated

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Fiscal Device Gateway API v4.2 - Clients-Dual-Translated

Uploaded by

Copyright:

Available Formats

FISCAL DEVICE GATEWAY API

Doc. No. v4.2

Fiscalisation Back-end Solution for ZIMRA 2 of 59

Fiscalisation Back-end Solution for ZIMRA 3 of 59

1.2. Fiscal device communication modes

Online communication mode represents fiscal device communication in a way when

Fiscalisation Back-end Solution for ZIMRA 4 of 59

1.3. Fiscal day (in online mode)

Fiscalisation Back-end Solution for ZIMRA 5 of 59

Fiscalisation Back-end Solution for ZIMRA 6 of 59

Fiscalisation Back-end Solution for ZIMRA 7 of 59

Each request must contain these HTTP headers:

Fiscalisation Back-end Solution for ZIMRA 8 of 59

Supported algorithms and key types (in order of suggested

 Client Certificate for SSL with Client Authentication.

Certificate is “Certificate” structure specified by RFC5280.

Fiscalisation Back-end Solution for ZIMRA 9 of 59

Fiscalisation Back-end Solution for ZIMRA 10 of 59

fiscalDayReconciliationMode FiscalDayReconciliationMode No In case fiscal day status is “FiscalDayClosed”

FiscalDayCounter type description provided in

Fiscalisation Back-end Solution for ZIMRA 11 of 59

operationID String (60) Yes Operation ID assigned by FDMS.

fiscalDayNo Int Yes Fiscal day number of opened day.

Fiscalisation Back-end Solution for ZIMRA 12 of 59

 fiscal device status is other than “Active”;

Fiscalisation Back-end Solution for ZIMRA 13 of 59

Fiscalisation Back-end Solution for ZIMRA 14 of 59

VATNumber String (9) No Buyer VAT number.

buyerContacts Contacts No Buyer contacts.

buyerAddress Address No Buyer address.

Fiscalisation Back-end Solution for ZIMRA 15 of 59

Fiscalisation Back-end Solution for ZIMRA 16 of 59

Fiscalisation Back-end Solution for ZIMRA 17 of 59

 fiscal device status is other than “Active”;

In case the above-mentioned validations have passed, file is processed asynchronously.

During asynchronous processing these steps will be executed:

 file structure will be validated;

Additional validation rules:

Fiscalisation Back-end Solution for ZIMRA 18 of 59

Fiscalisation Back-end Solution for ZIMRA 19 of 59

Fiscalisation Back-end Solution for ZIMRA 20 of 59

 fiscal device status is other than “Active”;

Fiscalisation Back-end Solution for ZIMRA 21 of 59

This API endpoint does not require certificate for authentication.

Fiscalisation Back-end Solution for ZIMRA 22 of 59

Fiscalisation Back-end Solution for ZIMRA 23 of 59

Fiscalisation Back-end Solution for ZIMRA 24 of 59

Fiscalisation Back-end Solution for ZIMRA 25 of 59

Fiscalisation Back-end Solution for ZIMRA 26 of 59

BalanceByMoneyType +paymentAmount +paymentAmount* +paymentAmount

* - for credit note salesAmountWithTax, taxAmount, paymentAmount counters will be

Fiscalisation Back-end Solution for ZIMRA 27 of 59

6.2. Environment addresses

6.3. Authentication and authorization

Note: endpoints 3.1 verifyTaxpayerInformation, 3.2 registerDevice, 3.11 getServerCertificate

6.4. Timeout Settings

Fiscalisation Back-end Solution for ZIMRA 28 of 59

7.1. Http statuses

Http status Description