Fiscal Device Gateway API v4.2 - Clients-Dual-Translated
Fiscal Device Gateway API v4.2 - Clients-Dual-Translated
Fiscal Device Gateway API v4.2 - Clients-Dual-Translated
SPECIFICATION
Online
Offline
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.
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.
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.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:
Name Type Mandatory Description
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).
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.
Case insensitive 8 symbols key.
certificateRequest String Yes Certificate signing request (CSR) for which certificate will be
generated (in PEM format).
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:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
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:
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:
Name Type Mandatory Description
deviceID Int Yes Device ID
Output parameters:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
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:
Name Type Mandatory Description
deviceID Int Yes Device ID
Output parameters:
Name Type Mandatory Description
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.
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.
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:
Name Type Mandatory Description
deviceID Int Yes Device ID
Output parameters:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
fiscalDayStatus FiscalDayStatus Yes Device Fiscal day status.
FiscalDayDocumentQuantity:
Name Type Mandatory Description
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:
Name Type Mandatory Description
deviceID Int Yes Device ID
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:
Name Type Mandatory Description
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:
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:
Name Type Mandatory Description
deviceID Int Yes Device ID
receipt Receipt Yes Receipt data
Receipt:
Name Type Mandatory Description
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:
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.
Buyer:
Name Type Mandatory Description
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.
CreditDebitNote:
ReceiptLine:
Name Type Mandatory Description
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:
Payment:
Name Type Mandatory Description
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:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
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.
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:
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:
Name Type Mandatory Description
deviceID Int Yes Device ID.
File:
Name Type Mandatory Description
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:
Name Type Mandatory Description
deviceID Int Yes Device ID.
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:
Name Type Mandatory Description
receipts Receipt array Yes List of receipts in file. Receipt type description is
provided in 3.7 submitReceipt endpoint description.
FileFooter:
Name Type Mandatory Description
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:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
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:
Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID.
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:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
fileStatus FileStatus array Yes List of files statuses.
FileStatus:
Name Type Mandatory Description
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”.
Request can’t be sent if DeviceOperatingMode is Offline. If DeviceOperatingMode is
Offline error DEV01 is received.
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
Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID
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:
Name Type Mandatory Description
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:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
3.11. getServerCertificate
getServerCertificate endpoint is used to retrieve FDMS certificate for FDMS signature
validation.
Input parameters:
Name Type Mandatory Description
thumbprint Binary (20) No Thumbprint of FDMS signing certificate which should be returned. If
field is not provided, currently active FDMS signing certificate is
Output parameters:
Name Type Mandatory Description
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:
Name Type Mandatory Description
deviceID Int Yes Device ID
Output parameters:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
reportingFrequency int Yes Reporting frequency in minutes.
4.2. Contacts
Contacts object is used to define Taxpayers and device contact information.
Name Type Mandatory Description
phoneNo String (20) No* Phone number
email String (100) No* E-mail address
* at least one of field is mandatory.
4.3. SignatureData
SignatureData:
Name Type Mandatory Description
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:
Name Type Mandatory Description
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:
Enum value Enum order
FiscalDayClosed 0
4.4.3. FiscalDayReconciliationMode
Defines how fiscal day was closed, possible values:
Enum value Enum order
Auto 0
Manual 1
4.4.4. FiscalCounterType
Fiscal counter type, possible values:
Enum value Enum order
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:
Enum value Enum order
Cash 0
Card 1
MobileWallet 2
Coupon 3
Credit 4
BankTransfer 5
Other 6
4.4.6. ReceiptType
Type of receipt. Possible values:
Enum value Enum order
FiscalInvoice 0
CreditNote 1
DebitNote 2
4.4.7. ReceiptLineType
Type of receipt line. Possible values:
Enum value Enum order
Sale 0
Discount 1
4.4.9. FiscalDayProcessingError
Messages which are shown in case of error during fiscal day closure. Validations are
performed in this sequence. Possible values:
Enum value Enum order Description
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:
Enum value Enum order
FileProcessingInProgress 0
FileProcessingIsSuccessful 1
FileProcessingWithErrors 2
4.4.11. FileProcessingError
Messages which are shown in case of error during submitted file processing. Possible
values:
Enum value Enum order Description
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.
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
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.
ProblemDetails:
Name Type Mandatory Description
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
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.
FISC04 Closing day is not allowed. Fiscal day not opened. closeDay
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.
RCPT014 Yellow No Receipt date is earlier than fiscal day opening date
RCPT019 Red No Invoice total amount is not equal to sum of all invoice lines
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
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
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
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
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
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
Verification code
4C8B-E276-6333-0417 [46]
You can verify this receipt manually at
https://receipt.zimra.org/ [48]
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
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
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.
------------------------------------------------
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
========================================= == = = = = =
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.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-----
keyid:AD:51:5C:79:B5:A6:5B:DA:8A:7B:6A:95:66:97:0E:CD:57:DC:B5:FE
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
keyid:AD:51:5C:79:B5:A6:5B:DA:8A:7B:6A:95:66:97:0E:CD:57:DC:B5:FE
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.
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.
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
receiptTaxes Tax lines:
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
previousReceiptHash hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Result used for hash 07000.000100014.50535 hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
generation
Generated receipt hash in 2zInR7ciOQ9PbtQlKaU5XoktQ/4/y1XShfzEEoSVO7s=
base64 representation
CreditNote Examples
Name Example No 1
Name Example No 2
deviceID 322
receiptType CREDITNOTE
receiptCurrency USD
receiptGlobalNo 85
receiptDate 2020-09-19T09:23:07
receiptTotal -40,35
receiptTaxes Tax lines:
taxID taxPercent taxAmount salesAmountWithTax
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
previousReceiptHash hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
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=
base64 representation
DebitNote Examples
Name Example No 1
deviceID 321
receiptType DEBITNOTE
receiptCurrency ZWL
receiptGlobalNo 432
receiptDate 2020-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 C 15 300,00 2300,00
Result:
A0250000B0.000350000C15.0015000115000D15.0030000230000
previousReceiptHash hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Name Example No 2
deviceID 322
receiptType DEBITNOTE
receiptCurrency USD
receiptGlobalNo 85
receiptDate 2020-09-19T09:23:07
receiptTotal 40,35
receiptTaxes Tax lines:
taxID taxPercent taxAmount salesAmountWithTax
1 0,00 7,00
2 0 0,00 10,00
3 14,5 3,00 23,00
Result:
07000.000100014.503002300
previousReceiptHash hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Result used for hash 322DEBITNOTEUSD852020-09-19T09:23:
generation 07403507000.000100014.503002300hNVJXP/ACOiE8McD3pKsDlqBXpuaUqQOfPnMyfZWI9k=
Generated receipt hash in YOLYzYhCaaLN2yxrM574B83WUhxSkg52uc1hrM4g8Dw=
base64 representation
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):
Order Field name Description
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
represented in 24 hours format, local time).
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
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
SaleByTax ZWL 15 12,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
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):
Order Field name Description
1 deviceID Device ID
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
represented in 24 hours format, local time).
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 ZWL 0 12000,00
SaleByTax USD 15 25,00
SaleByTax ZWL 15 12,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