 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 according to sequence field is
saved, later received value is ignored.

Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID.
file File in multipart/form- Yes File containing invoices and other information related to fiscal day. Base64
data encoded.

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 4.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 Mandator Description
y
deviceID Int Yes Device ID
fiscalDayOpene DateTim Yes Date and
d e time when
fiscal day
was opened
on a device.
Time is
provided in
local time
without

Copyright © ZIMRA 21 of 77
 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

operationID String Yes Operation ID

(60) assigned by FDMS.

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.

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 Error! Reference
source not found.closeDay 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 13.3.
Validation rules:
- fiscalDayDeviceSignature must be valid
receiptCounter Int Yes receiptCounter value of last receipt of current fiscal day.

Copyright © ZIMRA 22 of 77
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.

4.9.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
"receiptType": "FiscalInvoice",
"receiptCurrency": "USD"
},
{
//invoice No 3 data
"receiptType": "FiscalInvoice",
"receiptCurrency": "USD"

Copyright © ZIMRA 23 of 77
 }
]
},
"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"
}
}
Valid sample:
{
"header": {
"deviceId": 1111,
"fiscalDayNo": 6,
"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": "bGFiYXM=",
"signature": "bGFiYXM="
},
"receiptType": "fiscalInvoice",
"receiptCurrency": "USD"

Copyright © ZIMRA 24 of 77
 }
]
},
"footer": {
"fiscalDayCounters": [
{
"fiscalCounterType": "saleByTax",
"fiscalCounterCurrency": "USD",
"fiscalCounterTaxPercent": 15,
"fiscalCounterTaxID": 0,
"fiscalCounterMoneyType": "cash",
"fiscalCounterValue": 28.75
}
],
"fiscalDayDeviceSignature": {
"hash": "bGFiYXM=",
"signature": "bGFiYXM="
},
"receiptCounter": 1,
"fiscalDayClosed": "2023-05-30T22:38:54"
}
}

4.10. 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 8.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.

Error codes), in these cases:

 fiscal device status is other than “Active”;

 fiscal device operating mode is other than “Offline”;
 request structure is not valid.

Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID.
operationID String (60) No Unique operation identifier received in 4.9 submitFile response.
Mandatory if fiscalDayNo is not sent.
fileUploadedFrom Date Yes Date from when uploaded files are needed. Interval between from and
to can be no more than 100 days.

Copyright © ZIMRA 25 of 77
fileUploadedTill Date Yes Date till when uploaded files are needed. Interval between from and
to can be no more than 100 days.

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 4.9 submitFile request.

fileUploadDate DateTime Yes File placement date and time. Time is provided in local time
without time zone information.
deviceId Int Yes Device id.

fileName String (100) Yes File name

fileProcessingDate DateTime No Date and time when file processing is finished. Returned if
fileProcessingStatus is FileProcessingIsSuccessful or
FileProcessingWithErrors. Time is provided in local time without
time zone information.
fileProcessingStatus FileProcessingStatus Yes File processing status. Possible statuses are defined in section
5.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 5.4.11 FileProcessingError.
fiscalDayNo Int Yes Fiscal day number.
fiscalDayOpenedAt 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.
ipAddress String (100) Yes Ip address from which file is uploaded.

4.11. 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 8.2.1.
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:
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.

Copyright © ZIMRA 26 of 77
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 13.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.

Output parameters:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.

4.12. getServerCertificate
getServerCertificate endpoint is used to retrieve FDMS certificate for FDMS signature
validation.

This API endpoint does not require certificate for authentication.

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
returned. Together with the certificate, all certificate chain is
returned.

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.

Copyright © ZIMRA 27 of 77
 4.13. 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
DeviceReportingFrequencyInMinutes 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.14. Users management

FDMS has complimentary taxpayer’s user management functionality, which allows any
taxpayer and any POS solution to utilize this functionality in their solutions. User management
functionality is not mandatory to be used. This functionality is accessible only by Fiscal Device
Gateway API using device with valid certificate.

4.14.1. User registration process if user registration is finished right away:

Copyright © ZIMRA 28 of 77
Copyright © ZIMRA 29 of 77
 4.14.2. User registration process if user registration is finished after user login:

4.14.3. getUsersList
getUsersList endpoint is used to get taxpayer users saved in FDMS list.

Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID.

Output parameters:

Name Type Mandatory Description

total Int Yes Total rows returned in response.
operationID String (60) Yes Operation ID assigned by FDMS.
rows Users array No Taxpayer available users list.

Users:
Name Type Mandatory Description
userName String (100) Yes User username.
personName String (100) Yes User name.
personSurname String (100) Yes User surname.
userRole String (100) Yes User role. POS can provide any textual value. It will be
returned in users list.
email String (100) Yes User e-mail address.

Copyright © ZIMRA 30 of 77