Configuration guide

Otkucaj · version 1.3.6 · otkucaj.com · User manual · Installation guide

Everything this document says about the regulations is our understanding, not legal or tax advice; check with your accountant or the Tax Administration before you act.

Contents

• 1.Who configures, and what they see
• 2.The order of configuration
• 3.Test and production
• 4.The PFR mode
• 5.Authentication between the ESIR and the PFR
• 6.The security element
• 7.The ESIR number and the software version
• 8.Taxpayer and point-of-sale details
• 9.Tax labels and rates
• 10.Rounding of amounts and tax
• 11.Printing
• 12.Payment methods
• 13.Users and roles
• 14.API keys
• 15.Notifications
• 16.The activity log
• 17.Going into production
• 18.Configuration checklist

1.Who configures, and what they see

Configuration is done by an administrator. Only they see the Settings item in the sidebar and only they can change anything in this document. A cashier does not see that item, cannot open its addresses, and cannot change the environment, the PFR mode, the certificate, the tax rates, the taxpayer details, the receipt width or the payment methods. A cashier works the till, sees receipts and items, issues copies and refunds, and that is all. The split is not cosmetic: it is checked on the server, on every request.

The Settings screen is divided into nine sections, in the order things are actually set up. Each section has its own address, so it can be linked to directly.

2.The order of configuration

The steps below go in this order and none of them is skipped. Each has a condition by which you can see that it is genuinely finished, not merely that somebody typed something in. Steps 1 to 8 are carried out in the test environment; production is not touched until step 9.

1. Sign in with the administrator account. Done when the sidebar has a Settings item and you have changed the password issued during installation.
2. Enter the taxpayer details (chapter 8). Done when the TIN, business name, point-of-sale name and address match, word for word, the business-premises details you reported to the Tax Administration.
3. Set up printing (chapter 11). Done when a test receipt comes out whole, no line falls off the edge of the paper, and the QR code measures 40 to 50 mm with a ruler.
4. Choose the payment mode (chapter 12). Done when the till offers exactly the payment methods that taxpayer is allowed to use, and not one more.
5. Set the PFR mode for test (chapters 4 and 5). Done when the connection status on Environment and PFR reports the PFR as reachable, rather than an error.
6. Install the test security element, if a V-PFR is in use (chapter 6). Done when the panel beside the certificate states who it was issued to, how long it is valid and its fingerprint.
7. Enter the ESIR number and version (chapter 7). Done when the readiness check for that environment no longer reports a missing ESIR number.
8. Fetch the tax rates from the PFR (chapter 9). Done when the button reports how many rates were fetched and the date they are valid from, and the table fields are locked.
9. Issue rehearsal receipts in test. Done when Normal Sale, Normal Refund, Copy, Pro-forma, Training and Advance have all been through the PFR and each of them appears in the receipt register.

Only then comes production, chapter 17. What happens there is not a repeat of these steps but filling them in with real data, in the other environment, guarded by a readiness check that will not let a half-finished installation be declared live.

3.Test and production

Every company in Otkucaj has two completely separate environments and exactly one of them is active at any moment. They are not two accounts and they do not have to be created: they exist from installation onwards, and a freshly installed copy runs in test.

The data of the two environments never mixes. Every receipt records which environment produced it at the moment it is issued, as part of the record rather than as a setting that can be changed afterwards. The receipt list, the dashboard and every report show only what belongs to the active environment, so a rehearsal receipt cannot enter real turnover by accident, or later, or in the report handed to the accountant.

What is shared by both environments, because it does not depend on which Tax Administration system is being spoken to: the taxpayer details, paper and receipt width, the advertising text, the payment mode, users, API keys and notifications. What is per environment: the PFR mode, the L-PFR and V-PFR addresses, the PAC, the ESIR number and version, and the security element certificate.

3.1 The readiness check

On the Environment and PFR section both environments stand side by side: which one is active, what mode it is in, which ESIR number it has and whether it has a certificate. Under each is a readiness check, in the form of a list of what is still missing. It is the same list the application uses when it refuses to issue a receipt, so the message on screen and the actual behaviour cannot drift apart.

An environment counts as ready once it meets every condition below:

1. the mode is L-PFR or V-PFR, never demo; demo does not issue fiscal receipts, so in production it contradicts itself;
2. the ESIR number is a number, that is, the registration number assigned by the Tax Administration, not text;
3. for a V-PFR: a certificate is installed;
4. for a V-PFR: a PAC is entered, because without one the V-PFR refuses the request;
5. for a V-PFR: the address belongs to that environment, the test address in test and the production one in production;
6. the certificate in that environment is different from the certificate in the other one.

While any of that is unmet, the Switch to this button is disabled and the reason is written underneath it. If the installation is already running in an environment that does not meet the conditions, issuing stops and the reasons are printed above the basket at the till, before the cashier rings anything up.

3.2 Two mistakes the application will not allow

The same certificate in both environments. Test and production must hold different security elements. On installation the certificate is fingerprinted (SHA-256) and the fingerprint is remembered, so the same certificate cannot be installed in both: the second attempt is refused with a message. If the same fingerprint is found in both anyway, issuing stops until it is corrected. It is the one configuration mistake that produces receipts nobody can repair, which is why it is checked twice.

Cross-wired addresses. If you enter the Tax Administration's test address into production, the receipts would look real and would not be fiscal. If you enter the production address into test, rehearsal receipts would go into the real records. Both entries are refused when saving, with an explanation that names the address.

On top of that, a V-PFR address must start with https://. An entry with plain HTTP is refused when saving: the client certificate is sent only over a secure connection, so over HTTP the app would be talking to the Tax Administration with no security element at all.

4.The PFR mode

Each environment has its own mode of operation, chosen on the Environment and PFR section and changed without reinstalling anything.

The L-PFR's port comes from its supplier and is not guessed. If the L-PFR runs on another computer on the shop network, the address of that computer replaces localhost, and the network between them has to pass that port.

Below the fields is the connection status, read live every time the home page and Settings are opened. Whatever the PFR answers is shown as it arrived, because that is the only part that helps: "card not inserted" and "invalid PAC" are solved in two completely different places.

Changing the mode does not touch a single receipt already issued. Every receipt remembers the mode it was issued in, so even after moving from demo to a real PFR the register still shows plainly which receipts were demo ones.

5.Authentication between the ESIR and the PFR

The ESIR and the PFR recognise each other before any receipt data changes hands, and not once at connection time but on every call.

V-PFR. The connection runs over HTTPS. Otkucaj presents a client certificate, which is the security element in file form, and sends a header carrying the PAC with every request. In the same handshake it checks the V-PFR's certificate as well, its issuer and its host name; that check is on and there is no setting that turns it off. If no certificate is installed, if the password does not open the file, or if the PAC is not accepted, the V-PFR refuses the request, no receipt is issued, and the message is shown to the cashier.

L-PFR. The connection runs over HTTP on the local network and no client certificate is sent on it, because that connection has no place for one. It is the L-PFR itself that authenticates against the security element, through the smart card reader and the PIN. Otkucaj does not access the card.

When the check happens, and what happens when it fails. When the home page and Settings are opened, when tax rates are fetched, and on every receipt issued. A failure is not turned into half a receipt: the Issue receipt button is disabled before the cashier rings up a whole basket, and the reason stands above the basket. If the connection drops at the very moment of issuing, the receipt goes into the local queue and is not issued until it has been through the PFR. As we understand art. 6 para. 1 of the Law on Fiscalization, while a receipt is waiting the sale is not completed.

6.The security element

The Security element section holds two separate boxes, one for test and one for production. Each takes its own certificate (.pfx or .p12) and its own password. The file is written outside the directory the web server serves, with permissions 0600, and is never served to visitors; the password is stored encrypted (AES-256-GCM) with the key of that installation, so a copy of the database on its own reveals nothing.

An upload is accepted only if the file genuinely opens with the password given. A wrong password cannot be saved and then discovered on the first real receipt: it is refused immediately. Files up to 512 kB are accepted, which is many times the size of a certificate. If you are changing only the password, leave the file field empty; if you are changing only the file, leave the password field empty and the previous one stays in force.

Beside every installed certificate the screen states who it was issued to, how long it is valid and the first sixteen characters of its fingerprint. The box changes colour and warns thirty days before expiry, and again once it has expired. The fingerprint also proves that test and production do not share one element (chapter 3.2), so it is worth writing down with the installation's paperwork.

The Windows store. If Otkucaj is installed locally on a Windows machine, instead of uploading the file you can use a certificate already installed on that machine: choose the store (Current User or Local Machine) and enter the certificate's thumbprint, without spaces. There is then no file and no password for the application to keep. The option is shown only where it actually works; on otkucaj.com it does not exist and cannot exist, because a server cannot see the certificate store on your computer, so uploading the file is the only route there.

7.The ESIR number and the software version

The ESIR number is the registration number under which the ESIR is entered in the register of approved elements of electronic fiscalization. The Tax Administration assigns it on approval and it must not carry any other value. It is entered on the Environment and PFR section, separately per environment, and from that moment it is printed on every receipt type and every transaction type.

On the receipt it stands joined to the software version by a slash: ЕСИР број: 123/1.0. The Version field holds that second half. The test environment also accepts the reserved value 000, which served before approval, and the readiness check will not allow a move to production while the ESIR number there is not a number. If 000 is left in production, receipts are simply not issued, which is better than receipts with a wrong number: a mismatch between the printed number and the assigned registration number is a known reason for a rejected application.

The serial number of the installation is a different thing and is not to be confused with the ESIR number. It has the form OTK-XXXXXXXXXXXX, is assigned automatically at installation, is unique to that copy of the program, and does not change across upgrades or after a backup is restored. Together with the maker and the software version it stands in the About panel, on the Taxpayer details section; quote it when reporting a problem and during an inspection.

8.Taxpayer and point-of-sale details

The TIN, business name, point-of-sale name, address and town are entered on the Taxpayer details section and are the same in both environments. They must match, word for word, the business-premises details you reported to the Tax Administration. A freshly installed copy has them empty on purpose: this is a transferable product and the first receipt must not name a company that does not exist.

These details are not what gets printed in the header of a fiscal receipt. The PFR assembles the header during fiscalization and returns it to the ESIR, and Otkucaj prints it as it received it. If what you entered differs from what the PFR prints, the difference is a sign that the registration at the Tax Administration is not what you think it is, and it is resolved there, not by editing text in the application.

9.Tax labels and rates

The Taxes section holds a table of the labels and rates in force. The PFR is the authority, not that table. While an L-PFR or V-PFR is connected the fields cannot be edited by hand: they are locked, and the Fetch rates from the PFR button refreshes them from the source and reports how many rates were fetched and the date they are valid from. That way the application cannot calculate tax at a rate somebody typed in. In demo mode there is no PFR to fetch from, so the rates stay editable and the default Serbian ones apply.

Fetching replaces the whole local table with the one the PFR returned, label by label, including the name of the tax category beside each. The set of labels is therefore not built into the program: if the Tax Administration introduces a new label, changes a rate or withdraws an existing one, it appears at the next fetch and prints on the receipt straight away, with no change to the application and no new version. The number of labels is not limited to four; the Tax Administration's test system, for example, has nine.

10.Rounding of amounts and tax

Rounding is not a setting and there is no field that changes it; it is described here because a configuration document has to state it. Every monetary amount is kept and shown to two decimals, and quantities to three. Rounding works the usual way: the second decimal goes up if the next digit is 5 or more, and stays as it is if that digit is below 5, so 1.005 becomes 1.01 and 1.004 becomes 1.00. That is how the line amount (quantity times unit price, with the discount if there is one), the total of the receipt, the amount of each payment and the change are produced. Quantities go to three decimals because goods are also sold by weight and measure, so 0.375 kg stays 0.375; trailing zeros are not printed on the receipt.

The application does not calculate tax amounts. The PFR calculates them at the rates in force at that moment and returns them in its answer, to two decimals, and Otkucaj shows and prints them exactly as it received them, with no rounding of its own. For the same reason the tax per label and the total tax on the receipt both come from the PFR.

11.Printing

Four things are set on the Printing and payment section: the paper width, the receipt width in characters, the default advertising text, and the payment mode (chapter 12).

The paper width is chosen between A4, an 80 mm roll and a 58 mm roll, and must match the paper actually in the printer. It sets the page size when printing; without it the browser assumes A4 and its shrink-to-fit silently changes the physical size of the QR code, which must stay between 40 and 50 mm. The narrowest roll supported is 58 mm; anything under 57 mm is not supported, because the journal in the prescribed layout does not fit into fewer characters per line.

The receipt width in characters is the number of characters per line of the journal: usually 40 for an 80 mm roll and 32 for a 58 mm roll, with an allowed range of 32 to 64. The type size is derived from that number, because the printed column is fixed: 46 mm on a 58 mm roll and 68 mm on an 80 mm roll, which is the width a thermal head actually prints. If a receipt does not fit the paper, lower the character count and never the print scale: the scale changes the size of the QR code too.

The QR code prints at 41 mm on a 58 mm roll and at 45 mm on an 80 mm roll and on A4. Both are inside the prescribed 40 to 50 mm. The PFR draws the image itself and its picture is the one that prints; the application draws its own only in demo mode, where there is no PFR.

The default advertising text prints on every receipt below the КРАЈ ФИСКАЛНОГ РАЧУНА line, that is, outside the fiscal part, and is at most 500 characters long. A cashier can change or clear it per receipt at the till. What remains in the browser's print dialog is to set, once per device, margins to None, scale to 100%, and headers and footers off.

12.Payment methods

Otkucaj supports all seven payment methods set by art. 6 of the Rulebook on types of fiscal receipts, and each carries its own numeric code from the Technical Guide in the request to the PFR:

The standard mode offers all seven methods. The mode under art. 6 para. 2 of the Rulebook on types of fiscal receipts is, as we understand that article, mandatory for a device that records food and drink served for consumption on the spot or food and drink sold in a bakery: it disables the payment card, the cheque and instant payment, which the cashier then enters as cash, leaving codes 0, 1, 4 and 5. The disabled methods are not offered at the till, and a request carrying one is refused through the API as well, with an explanation; the check is on the server, not only in the look of the screen.

One installation runs in exactly one of these two modes. The administrator chooses it and it applies to every cashier and every integration. If a taxpayer has several points of sale with different modes, those are separate installations.

13.Users and roles

On the Users section accounts are opened, a role is assigned (administrator or cashier), a password is reset and a cashier who no longer works there is deactivated. A password is at least 10 characters. A user's name is displayed and printed on every receipt they issue, as the cashier identification (Technical Instruction, 16.П3). A label that identifies the cashier uniquely is enough, for example a first name or an internal staff code; a full name is not required, and for data protection we recommend the least that is enough.

This is also where accounts that arrived through the registration page are approved. Such an account is created inactive and cannot be signed in with until an administrator activates it. Deactivating an account, changing a password and the Sign me out everywhere button all end the persistent login on every device of that user, not just the current session.

14.API keys

Keys are for external programs: an online shop, an ERP, the WooCommerce plugin. They are generated and revoked on the API keys section, each gets a label so it is clear who it belongs to, and the limit is 240 requests a minute per key.

A key is shown only once, at the moment it is generated; only its hash is kept in the database, so a lost key cannot be read back, only replaced. Move it somewhere safe at once. A compromised key is revoked immediately and a new one generated; revocation takes effect at once, and the receipts already issued with that key are untouched.

15.Notifications

The Notifications section sends a message to Telegram for every receipt issued: the receipt type, the amount, the payment methods, the PFR number, the counter and the verification link. Setting it up is optional, but it is useful for shops connected through the API, where the owner otherwise does not see a receipt at the moment it is issued.

1. Bot token: in Telegram open @BotFather, create a bot with /newbot and copy the token.
2. Chat ID: the number of the conversation, most easily through the @userinfobot bot. It can be a group ID if more than one person should see the notifications; add your bot to the group in that case.
3. Turn on the switches for receipts issued through the API and/or at the till, depending on what you want to follow.
4. Click Send a test message. Done when the message actually arrives in Telegram; if it does not, nothing else is configured either.

A notification of every new account registration awaiting approval arrives at the same address (chapter 13).

16.The activity log

The log records who issued a receipt and when, who changed items, settings, users and API keys, including changes of environment and installation of certificates, each with the time and the IP address. It writes itself, cannot be turned off by a setting, and cannot be edited through the application.

The Activity log section shows the last 200 actions. Older ones stay in the database and leave it with a backup (chapter 6 of the Installation guide), which is also where they belong during an inspection: the log helps establish who did what, it is not a substitute for the receipt register.

17.Going into production

Production is filled in only once the taxpayer has a security element, or a PAC, and the ESIR has a registration number from the Tax Administration. Until then there is nothing to enter and an attempt to switch is refused, which is correct.

1. On the Environment and PFR section choose the production box and fill it in with real data: L-PFR or V-PFR mode, the production address, the PAC and the registered ESIR number.
2. On the Security element section install the real certificate in the production box. It must differ from the test certificate; the same one is refused.
3. Check that the readiness check for production reports nothing.
4. Press Switch to this and confirm the question. From that moment every Normal or Advance receipt is a fiscal receipt; Copy, Pro-forma and Training are not.
5. Fetch the tax rates again (chapter 9) and go through the item catalogue, because the production system may carry a different set of labels from the test one.
6. Issue one Training receipt and print it: it goes through the whole flow like a real one but does not count as turnover. Check the header, the ESIR number, the QR code and the printing.
7. Only then issue the first real receipt.

18.Configuration checklist

Configuration is finished once every row is confirmed. Rows 1 to 8 apply to the environment being worked in; row 9 onwards only to the move into production.