Device Gateway API v7.2
Device Gateway API v7.2
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 X X Total tax amount by tax and by currency from credit notes during
fiscal day.
DebitNoteByTax Total debit notes amount by tax and by currency during fiscal day
X X including tax.
DebitNoteTaxByTax X X Total tax amount by tax and by currency from debit notes during
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
Copyright © ZIMRA 41 of 77
7. INTEGRATION SETUP REQUIREMENTS
7.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.
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.
Copyright © ZIMRA 42 of 77
8. 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:
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.
Copyright © ZIMRA 43 of 77
confirmUserContactChange
updateUser
changeUserPassword
resetUserPasswordBegin
resetUserPasswordConfirm
DEV09 Security code is not valid createUserConfirm
resetUserPasswordConfirm
confirmUserContactChange
DEV10 Password is not valid changeUserPassword
createUserConfirm
resetUserPasswordConfirm
DEV11 User credentials are incorrect login
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
FISC04 Closing day is not allowed. Fiscal day not opened closeDay
FILE02 File structure invalid or field requirements not satisfied (e.g not sent submitFile
mandatory fields) getFileStatus
FILE03 Device operating mode is not Offline submitFile
getFileStatus
FILE04 File sent for already closed day or closing in progress submitFile
FILE05 Device id in input parameters and file header are different submitFile
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.
Copyright © ZIMRA 44 of 77
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 for Invoice
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
Copyright © ZIMRA 45 of 77
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
RCPT043 Red No Mandatory buyer data fields are not provided
RCPT048 Red No HS code length must be 4 or 8 digits if taxpayer is not VAT payer, 4
or 8 digits if taxpayer is VAT payer and applied tax percent is bigger
than 0, 8 digits if taxpayer is VAT payer and applied tax percent is
equal to 0 or is empty
Copyright © ZIMRA 46 of 77
9. 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.
Copyright © ZIMRA 47 of 77
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 6. 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 closed 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 devices must be able to export file with invoices if user
requests it for manual upload to FDMS Self-service.
22. User must not uninstall application from device if there are unsent
invoices.
Copyright © ZIMRA 48 of 77
10. STANDARD FISCAL RECEIPT, INVOICE AND REPORT VIEWS
10.1. Receipt48 view
Receipt48 view is used for tax inclusive invoice printed on receipt paper, which can
print 48 characters of text per line.
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: 1987012311 [13] Buyer's TIN
VAT: 198701211
12 Southgate Hwange [14] Buyer's address
[email protected] [15] Buyer's e-mail
(081) 20875 [16] Buyer's phone
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
I n v o i c e N o : 1 5 / 4 5 1 F i s c a l d a y N o : 4 5 [17], [18], [19] Invoice No (receiptCounter, receiptGlobalNo), Fiscal day number
C u s t o m e r r e f e r e n c e N o : C I S N - 0 0 0 0 4 0 3 2 1 [20] Customer reference 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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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
I t e m 4 n a m e 2 4 0 0 . 0 0 E X
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 . 5 5 5 [39] number of items
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Net Amount 1 2 0 0 . 0 0 Tax table
VAT (Exempt) 0 . 0 0
Gross Amount 1 2 0 0 . 0 0 [40], [41], [42], [43], [44] tax code, tax percent, amount without tax, tax
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - amount, total amount inclusive tax
Net Amount 6 0 0 . 0 0
VAT (0%) 0 . 0 0
Gross Amount 6 0 0 . 0 0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Net Amount 2 4 5 2 1 . 7 4
VAT (15%) 3 6 7 8 . 2 6
Gross Amount 2 8 2 0 0 . 0 0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[46] QR code
V e r i f i 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
Copyright © ZIMRA 49 of 77
Credit note template:
Receipt field name
[1] Taxpayer logo
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
VAT: 19870123 [51] Buyer's VAT
12 Southgate Hwange [14] Buyer's address
[email protected] [15] Buyer's e-mail
(081) 20875 [16] Buyer's phone
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
I n v o i c e N o : 1 5 / 4 5 1 F i s c a l d a y N o : 4 5 [17], [18], [19] Invoice No (receiptCounter, receiptGlobalNo), Fiscal day number
C u s t o m e r r e f e r e n c e N o : C I S N - 0 0 0 0 4 0 3 2 1 [20] Customer reference no
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
I n v o i c e N o : 4 5 0 D a t e : 0 3 / 0 7 / 2 3 1 8 : 4 8 [26], [27] Credited/debited invoice No (receiptGlobalNo) and date
C u s t o m e r r e f e r e n c e N o : C I S N - 0 0 0 0 4 0 3 2 0 [28] Credited/debited invoice customer reference 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
I t e m 4 n a m e 2 4 0 0 . 0 0 E X
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 . 5 5 5 [39] number of items
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Net Amount 1 2 0 0 . 0 0 Tax table
VAT (Exempt) 0 . 0 0
Gross Amount 1 2 0 0 . 0 0 [40], [41], [42], [43], [44] tax code, tax percent, amount without tax, tax
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - amount, total amount inclusive tax
Net Amount 6 0 0 . 0 0
VAT (0%) 0 . 0 0
Gross Amount 6 0 0 . 0 0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Net Amount 2 4 5 2 1 . 7 4
VAT (15%) 3 6 7 8 . 2 6
Gross Amount 2 8 2 0 0 . 0 0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[46] QR code
V e r i f i 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
Copyright © ZIMRA 50 of 77