OFS P5 EFU — API dokumentacijaAPI documentation

Poslednji put ažurirano: 18.10.2025.

Molimo Vas da sve greške koje pronađete u dokumentaciji prijavite na podrska@ofs.ba mail.

Uvod

Ovaj dokument predstavlja uputstvo za integraciju IT sistema sa OFS ESIR rešenjima za fiskalizaciju (SUF) putem API poziva.

OFS P5 EFU je fiskalni uređaj namenjen za elektronsku fiskaliaziju koji se može koristiti od strane krajnjih korisnika za izdavanje fiskalnih računa ali i od strane trećih sistema integrisanih na njega putem API poziva. Uređaj dlazi sa ugrađenim ESIR-om (elektronskim sistemom za izdavanje računa) i LPFR-om (lokalnim procesorom fiskalnih računa). Ovaj uređaj je akreditovan od strane Poreske uprave kao integrisani LPFR i ESIR.

VAŽNO: Za uspešno korišćenje i integraciju pored tehničkog znanja neophodno je i poznavanj relvenatnih propisa u domenu elektronske fiskalizacije. Detaljne tehničke informacije za SUF se mogu naći na stranicama https://poreskaupravars.org/e-fiskalizacija/ i https://tap.sandbox.suf.poreskaupravars.org/Help/view/1457235313/Увод/sr-Cyrl-BA

Last updated: 18.10.2025.

Please report any errors you find in the documentation to podrska@ofs.ba email.

Introduction

This document provides a guide for integrating IT systems with OFS ESIR fiscalization solutions (SUF) via API calls.

OFS P5 EFU is a fiscal device intended for electronic fiscalization that can be used by end users to issue fiscal receipts, as well as by third-party systems integrated with it via API calls. The device comes with a built-in ESIR (electronic invoice issuing system) and LPFR (local fiscal invoice processor). This device is accredited by the Tax Administration as an integrated LPFR and ESIR.

IMPORTANT: For successful use and integration, in addition to technical knowledge, knowledge of the relevant regulations in the field of electronic fiscalization is also required. Detailed technical information for SUF can be found at https://poreskaupravars.org/e-fiskalizacija/ and https://tap.sandbox.suf.poreskaupravars.org/Help/view/1457235313/Увод/sr-Cyrl-BA

Kako koristiti primere

How to use the examples

Svi primeri u nastavku koriste curl. Pre pokretanja zamenite vrednosti:All examples below use curl. Replace these values before running:

Oznaka u primerimaPlaceholder in examples	ZnačenjeMeaning
`http://127.0.0.1:3566`	Bazni URL OFS ESIR API-ja. Lokalno je to `http://127.0.0.1:3566` (TCP port 3566); putanje počinju sa `/api/…`.Base URL of the OFS ESIR API. Locally it is `http://127.0.0.1:3566` (TCP port 3566); paths start with `/api/…`.
`<API_KEY>`	API ključ dodeljen uređaju (`Authorization: Bearer <API_KEY>`).API key assigned to the device (`Authorization: Bearer <API_KEY>`).

Napomene:Notes:

Svaki zahtev mora sadržati zaglavlje Authorization: Bearer <API_KEY>.Every request must include the Authorization: Bearer <API_KEY> header.
Zahtevi sa telom moraju sadržati Content-Type: application/json; charset=UTF-8.Requests with a body must include Content-Type: application/json; charset=UTF-8.
Kod integracije na OFS Cloud svaki zahtev mora sadržati i zaglavlje X-Teron-SerialNumber: <serijski_broj>.When integrating with OFS Cloud, every request must also include the X-Teron-SerialNumber: <serijski_broj> header.
Uspešan odgovor ima HTTP status 200 OK ili 204 No Content (prazno telo). Status 4xx/5xx označava grešku — detalji su u telu odgovora i log fajlovima.A successful response has HTTP status 200 OK or 204 No Content (empty body). A 4xx/5xx status indicates an error — details are in the response body and log files.
U primerima odgovora su dugački base64 nizovi (npr. QR kod, potpis) i velike liste skraćeni radi preglednosti (… [skraćeno]).In the response examples, long base64 strings (e.g. QR code, signature) and large lists are truncated for readability (… [skraćeno]).

ESIR

ESIR je komponenta za izdavanje fiskalnih računa sertifikovana od strane PURS-a kao napredni ESIR. Za potrebe fiskalizacije računa ESIR je povezan na LPFR (lokalni procesor fiskalnih računa) koji uz pomoć bezbednosnog elementa izdatog od strane PURS-a i ugrađenog u OFS P5 EFU uređaju fiskalizuje račune. Takođe u posebnim situacijama ESIR može raditi i sa VPFR-om (virtuelnim procesorom fiskalnih računa) koji uz pomoć sertifikata u fajlu izdatog od strane PURS-a vrši fiskalizaciju računa. Sa tačke gledišta integracije na ESIR ne postoji razlika da li se fiskalizacija vrši uz pomoć LPFR-a ili uz pomoć VPFR-a.

Glavne elmenti ESIR rešenja su:

ESIR aplikacija (GUI) putem koga krajnji korisnici mogu unositi i izdavati sve vrste račune kao i pratiti svoje poslovanje kroz razne izveštaje. Detaljno korisničko upustvo za ESIR aplikaciju se može naći na adresi https://doc.ofs.ba .
ESIR API koji izlaže kompletnu ESIR funkcionalnost putem HTTP REST JSON API interfejsa i čije korišćenje je opisano u ovom dokumentu.

ESIR is a component for issuing fiscal invoices, certified by PURS as an advanced ESIR. For the purpose of invoice fiscalization, ESIR is connected to an LPFR (local fiscal invoice processor), which, with the help of a security element issued by PURS and built into the OFS P5 EFU device, fiscalizes the invoices. Also, in special situations, ESIR can work with a VPFR (virtual fiscal invoice processor), which fiscalizes invoices with the help of a certificate in a file issued by PURS. From the standpoint of integration with ESIR, there is no difference whether fiscalization is performed using the LPFR or the VPFR.

The main elements of the ESIR solution are:

The ESIR application (GUI), through which end users can enter and issue all types of invoices, as well as monitor their business through various reports. A detailed user guide for the ESIR application can be found at https://doc.ofs.ba .
The ESIR API, which exposes the complete ESIR functionality via an HTTP REST JSON API interface and whose use is described in this document.

API

Integracija na ESIR se realizuje pozivanjem odgovarajućih operacija izloženih preko HTTP REST JSON API endpoint-a.

ESIR prihvata HTTP zahteve na TCP portu 3566.

Svaki HTTP zahtev treba da pored standardnih polja sadrži i polje za autorizaciju u zaglavlju:

Authorization: Bearer XXX (XXX treba zameniti sa API ključem)

Ukoliko zahtev sadrži i telo neophodno je navesti i format podataka dodavanjem sledećeg polja u HTTP zahtev:

Content-type: application/json; charset=UTF-8

Ukoliko je operacija uspešna svaki odgovor će imati HTTP status kod 200 (OK) ili 204 (No Content) u slučaju da je odgovor prazan. U slučajevima gde je HTTP status kod 4xx ili 5xx došlo je do greške i u većini slučajeva telo odgovora će sadržati dodatne informacije.

API dokumentacija u nastavku je organizovana tako da su prvo opisani najčešći slučajevi korišćenja API-ja u praksi kao i pozivi koji se koriste prilikom integracije dok se na kraju nalazi kompletan opis svih API poziva.

Tipovi podataka

U nastavku dokumentacije na svakom mestu gde se opisuje model podataka za svako polje se navodi i tip podatka koji može biti jedan od sledećih:

string - tekstualno polje
int - celobrojna vrednost
boolean - logičko polje (true ili false)
money - decimalni broj sa dve decimale (maloprodajna lokacija) ili četiri decimale (veleprodajna lokacija)
quantity - decimalni broj sa tri decimale
percent - decimalni broj sa dve decimale
timestamp - datum i vreme u ISO 8601 formatu sa vremenskom zonom (primer: 2023-11-15T13:31:50.000+01:00)
uuid - UUID v4
object - JSON objekat koji sadrži niz atribute i vrednosti
list(x) - JSON niz koji sadrži niz elemenata tipa x (gde X može biti bilo koji od navedenih tipova)

Važne preporuke

Prilikom fiskalizacije odgovor sadrži polje sa izgledom računa u zahtevanom formatu (npr. png) i ovo je jedini ispravan izgled računa koji se sme štampati. Štampanje sadržaja iz polja journal nije dozvoljeno odnosno izgled računa u pojedinim situacijama neće biti ispravan.
Prilikom fiskalizacije je obavezno popuniti i polje gtin za svaku stavku računa, ovo polje mora biti dužine nizmeđu 8 i 14 znakova.

Integration with the ESIR is achieved by calling the appropriate operations exposed via the HTTP REST JSON API endpoints.

The ESIR accepts HTTP requests on TCP port 3566.

In addition to the standard fields, every HTTP request must include an authorization field in the header:

Authorization: Bearer XXX (XXX should be replaced with the API key)

If the request also contains a body, you must specify the data format by adding the following field to the HTTP request:

Content-type: application/json; charset=UTF-8

If the operation is successful, every response will have HTTP status code 200 (OK), or 204 (No Content) if the response is empty. In cases where the HTTP status code is 4xx or 5xx, an error has occurred, and in most cases the response body will contain additional information.

The API documentation below is organized so that the most common practical API use cases and the calls used during integration are described first, while a complete description of all API calls is provided at the end.

Data types

Throughout the documentation below, wherever the data model is described, the data type is specified for each field, which can be one of the following:

string - text field
int - integer value
boolean - logical field (true or false)
money - decimal number with two decimals (retail location) or four decimals (wholesale location)
quantity - decimal number with three decimals
percent - decimal number with two decimals
timestamp - date and time in ISO 8601 format with time zone (example: 2023-11-15T13:31:50.000+01:00)
uuid - UUID v4
object - JSON object containing a set of attributes and values
list(x) - JSON array containing a set of elements of type x (where X can be any of the listed types)

Important recommendations

During fiscalization, the response contains a field with the invoice layout in the requested format (e.g. png), and this is the only correct invoice layout that may be printed. Printing the contents of the journal field is not allowed, i.e. the invoice layout will not be correct in certain situations.
During fiscalization, the gtin field must also be filled in for every invoice item; this field must be between 8 and 14 characters long.

Konfiguracija

Configuration

Pre početka korišćenja ESIR rešenja neophodno podesiti parametre rada. ESIR poseduje veliki broj različitih opcija koje se mogu podesiti ali većina njih odgovara standardnom načinu rada. U okviru ove sekcije se nalaze opisi podešavanja parametara za koje može postojati potreba za dodatnim podešavanjem na konkretnom uređaju.

Before starting to use the ESIR solution, it is necessary to configure the operating parameters. ESIR has a large number of different options that can be configured, but most of them correspond to the standard mode of operation. This section contains descriptions of the parameter settings for which there may be a need for additional configuration on a specific device.

GET/api/attention#

Provera dostupnosti

Availability check

Pre početka korišćenja ESIR-a neophodno je proveriti da li je isti dostupan (startovan) a u isto vreme se proverava i da li je dobro podešen API KEY za pristup. Ukoliko se koristi LPFR za fiskalizaciju ovaj poziv će proveriti i da li je LPFR dostupan. Ovaj poziv vraća HTTP 200 OK ukoliko je sve u redu.

Before starting to use ESIR, it is necessary to check whether it is available (started), and at the same time it is verified whether the API KEY for access is properly configured. If an LPFR is used for fiscalization, this call will also check whether the LPFR is available. This call returns HTTP 200 OK if everything is in order.

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/attention' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

Prazno telo odgovora.Empty response body.

GET/api/settings#

Očitavanje trenutne konfiguracije

Read current configuration

Namena ovog poziva je da se pročitaju vrednosti parametara trenutne konfiguracije. Neki od parametara su read-only (ne mogu se menjati) dok su neki skriveni radi sigurnosti (sadržaj sertifikata, šifra za sertifikat i sl.) ili su šifrovani (npr. API KEY). U nastavku su navedeni glavni parametri koji su bitni za produkciono korišećenje. Ukoliko neki od parametara nije opisan u nastavku treba smatrati da je on za internu upotrebu i ne treba ga menjati.

The purpose of this call is to read the values of the current configuration parameters. Some of the parameters are read-only (cannot be changed), while some are hidden for security reasons (certificate contents, certificate password, etc.) or are encrypted (e.g. API KEY). Below are the main parameters that are relevant for production use. If a parameter is not described below, it should be considered for internal use and should not be changed.

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/settings' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "allowedPaymentTypes": [
    0,
    1,
    2,
    3,
    4,
    5
  ],
  "apiKey": "****",
  "applicationLanguage": "sr-Cyrl-RS",
  "authorizeLocalClients": false,
  "authorizeRemoteClients": false,
  "availableDisplayDevices": [],
  "availableEftPosDevices": [
    "Internal"
  ],
  "availableEftPosProtocols": [
    "ASoftPos"
  ],
  "availablePrinterTypes": [
    "EscPos"
  ],
  "availablePrinters": [
    "Internal"
  ],
  "availableScaleDevices": [],
  "availableScaleProtocols": [
    "Aclas PS6X D0",
    "Apollo",
    "Birotehna OB1/OP1",
    "Dialog 06",
    "Dollar",
    "Ecr-Posnet"
  ],
  "customTabName": null,
  "customTabUrl": null,
  "displayDeviceName": null,
  "displayDeviceRs232BaudRate": null,
  "displayDeviceRs232DataBits": null,
  "displayDeviceRs232HardwareFlowControl": null,
  "displayDeviceRs232Parity": null,
  "displayDeviceRs232StopBits": null,
  "displayEnabled": false,
  "displayHandler": null,
  "displayProtocol": null,
  "displayTextCodePage": null,
  "displayTextCols": null,
  "displayTextRows": null,
  "eFakturaApiKey": null,
  "eFakturaCompanyAddress": null,
  "eFakturaCompanyBankAccount": null,
  "eFakturaCompanyCity": null,
  "eFakturaCompanyEMail": null,
  "eFakturaCompanyName": null,
  "eFakturaCompanyPhone": null,
  "eFakturaCompanyRegistrationId": null,
  "eFakturaCompanyTaxId": null,
  "eFakturaTest": true,
  "eftPosCredentials": null,
  "eftPosDeviceName": "Test",
  "eftPosDeviceRs232BaudRate": null,
  "eftPosDeviceRs232DataBits": null,
  "eftPosDeviceRs232HardwareFlowControl": null,
  "eftPosDeviceRs232Parity": null,
  "eftPosDeviceRs232StopBits": null,
  "eftPosProtocol": "Test",
  "issueCopyOnRefund": false,
  "language": "sr-Cyrl-RS",
  "languages": [
    "sr-RS",
    "sr-Cyrl-RS",
    "en-US"
  ],
  "lpfr": {
    "apiKey": "****",
    "authorizeLocalClients": false,
    "authorizeRemoteClients": false,
    "availableSmartCardReaders": [
      "PSAM"
    ],
    "canHaveMultipleSmartCardReaders": false,
    "externalStorageFolder": null,
    "languages": [
      "sr-RS",
      "sr-Cyrl-RS",
      "en-US"
    ],
    "password": "*****",
    "smartCardReaderName": null,
    "username": "admin"
  },
  "lpfrUrl": "http://127.0.0.1:3565/api/v3",
  "paperHeight": null,
  "paperMargin": null,
  "paperWidth": null,
  "posName": null,
  "printerDpi": null,
  "printerName": null,
  "printerType": "EscPos",
  "qrCodeSize": null,
  "receiptCustomCommandBegin": null,
  "receiptCustomCommandEnd": null,
  "receiptCutPaper": "CutPaper",
  "receiptDiscountText": null,
  "receiptFeedLinesBegin": 0,
  "receiptFeedLinesEnd": 3,
  "receiptFontSizeLarge": 24,
  "receiptFontSizeNormal": 19,
  "receiptFooterImage": null,
  "receiptFooterTextLines": null,
  "receiptHeaderImage": null,
  "receiptHeaderTextLines": null,
  "receiptLayout": "Slip",
  "receiptLetterSpacingCondensed": -0.05,
  "receiptLetterSpacingNormal": 0,
  "receiptOpenCashDrawer": "None",
  "receiptSplitMaxHeight": null,
  "receiptWidth": 386,
  "receiptsDelay": 5,
  "runUi": true,
  "scaleDeviceName": null,
  "scaleDeviceRs232BaudRate": 9600,
  "scaleDeviceRs232DataBits": 8,
  "scaleDeviceRs232HardwareFlowControl": 0,
  "scaleDeviceRs232Parity": 0,
  "scaleDeviceRs232StopBits": 1,
  "scaleProtocol": null,
  "syncReceipts": true,
  "vpfrCertificateAddress": null,
  "vpfrCertificateBusinessName": null,
  "vpfrCertificateCity": null,
  "vpfrCertificateCountry": null,
  "vpfrCertificateSerialNumber": null,
  "vpfrCertificateShopName": null,
  "vpfrClientCertificateBase64": null,
  "vpfrEnabled": false,
  "vpfrPac": null
}

POST/api/settings#

Podešavanje sigurnosnih parametara

Security parameters configuration

Pre korišćenja ESIR rešenja u produkciji preporučuje se provera i dodatno pojačaju sigurnosna podešavanja preko sledećih parametara:

authorizeLocalClients (boolean) - vrednost true ako je potrebno da lokalni klijenti (aplikacije koje se izvršavaju na istom uređaju kao i ESIR) šalju API KEY uz svaki zahtev odnosno false u suprotnom. Preporuka je da se ovaj parametar podesi na true.
authorizeRemoteClients (boolean) - vrednost true ako je potrebno da udaljeni klijenti (aplikacije koje se izvršavaju na drugim računarima/uređajima i pristupaju ESIR API-u preko mreže/interneta) šalju API KEY uz svaki zahtev odnosno false u suprotnom. Nikako nije preporučljivo ovaj parametar staviti na false osim ukoliko ste sigurni da ste na drugi način obezbedili kontrolu pristupa Teron ESIR API-ju.
apiKey (string) - nova vrednost API KEY-a. Preporučuje se da promenite API KEY kako bi ste vi bili jedini koji ga znate.
webserverAddress (string) - IP adresa i port na kojoj se nalazi API. Ukoliko je dovoljan samo pristup lokalnim klijentima (aplikacijama na samom uređaju) preporuka je da se IP adresa promeni na 127.0.0.1 umesto 0.0.0.0 što će dodatno onemogućiti pristup API-u spolja. Dodatno ovaj poziv se može iskoristiti da se promeni i port na kojem se nalazi API ukoliko je to potrebno. Nakon promene ovog parametra neophodno je restartovati Teron ESIR kako bi se novi parametri primenili.

Before using the ESIR solution in production, it is recommended to check and further strengthen the security settings through the following parameters:

authorizeLocalClients (boolean) - value true if local clients (applications running on the same device as ESIR) are required to send the API KEY with every request, or false otherwise. It is recommended to set this parameter to true.
authorizeRemoteClients (boolean) - value true if remote clients (applications running on other computers/devices and accessing the ESIR API over the network/internet) are required to send the API KEY with every request, or false otherwise. It is strongly not recommended to set this parameter to false unless you are certain that you have secured access control to the Teron ESIR API by other means.
apiKey (string) - the new value of the API KEY. It is recommended to change the API KEY so that you are the only one who knows it.
webserverAddress (string) - the IP address and port on which the API is located. If access only for local clients (applications on the device itself) is sufficient, it is recommended to change the IP address to 127.0.0.1 instead of 0.0.0.0, which will additionally prevent external access to the API. Additionally, this call can be used to change the port on which the API is located if needed. After changing this parameter, it is necessary to restart Teron ESIR in order for the new parameters to take effect.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/settings' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "authorizeLocalClients": false,
    "authorizeRemoteClients": true,
    "apiKey": "c0521663642496c82f79a55725302eba",
    "webserverAddress": "http://0.0.0.0:3566/"
}'

Primer odgovoraResponse example 200 OK

Prazno telo odgovora.Empty response body.

POST/api/settings#

Podešavanje konfiguracije štampača

Printer configuration settings

U zavisnosti od tipa štampača potrebno je podesiti neke od narednih parametara:

printerName (string) - naziv jednog od dostupnih štampača iz availablePrinters niza koji se dobija očitavanje trenutne konfiguracije (prethodni API poziv).
printerType (string) - vrednost EscPos (za ESC/POS kompatibilne štampače), Cpcl (za CPCL kompatibilne štampače) ili System (za korišćenje sistemskog drivera za štampanje). Termalni štampači su u većini slučajeva EscPos, dok ukoliko se štampa na A4 štampač (Laser, InkJet) treba koristiti tip System. receiptLayout (string) - podrazumevani format štampe, Slip za fiskalni isečak (termalni štampači) odnosno Invoice za račun u A4 formatu (Laser/InkJet štampači).
receiptWidth (int) - samo za EscPos i Cpcl štampače, širina štampe u pixelima (najčešće 384 za 58mm štampače odnosno 576 za 80mm štampače.
receiptFontSizeNormal (int) - samo za EscPos i Cpcl štampače, veličina standardnog fonta (najčešće 21 za 58mm štampače, odnosno 26 za 80mm štampače).
receiptFontSizeLarge (int) - samo za EscPos i Cpcl štampače, veličina većeg fonta (najčešće 24 za 58mm štampače, odnosno 32 za 80mm štampače).
receiptHeaderTextLines (list(string)) - niz tekstova koji se štampaju na vrhu računa.
receiptHeaderImage (string) - base64 kodirana GIF slika koja se štampa na vrhu računa.
receiptFooterTextLines (list(string)) - niz tekstova koji se štampaju na kraju računa.
receiptFooterImage (string) - base64 kodirana GIF slika koja se štampa na kraju računa.
qrCodeSize (int) - veličina QR koda za proveru fiskalnog računa u pikselima.
receiptFeedLinesBegin (int) - samo za EscPos i Cpcl štampače, koliko praznih linija se odštampa na početku računa, koristi se po potrebi da bi se papir adekvatno pozicionirao za početak štampe.
receiptFeedLinesEnd (int) - samo za EscPos i Cpcl štampače, koliko praznih linija se odštampa na kraju računa, koristi se po potrebi da bi se papir adekvatno pozicionirao za sečenje.
receiptCutPaper (string) - samo za EscPos i Cpcl štampače, da li se šalje komanda za sečenje i/ili izvlačenje papira na kraju štampe i može imati jednu od sledećih vrednosti: FeedAndCutPaper (izvlači se papir i preseca), CutPaper (preseca se papir), None (ne šalje se dodatna komanda na kraju štampe).
receiptOpenCashDrawer (string) - samo za EscPos i Cpcl štampače, da li se šalje komanda za otvaranje fioke koja je priključena na štampač i u zavisnosti od vrste štampača treba postaviti jednu od sledećih vrednosti: Epson_1 (najčešće), Epson_2, M80_1, M80_2 ili None da se ne šalje komanda za otvaranje fioke.
receiptPrintGtin (boolean) - podešavanje da li se na računu štampa GTIN (barkod) artikla

Depending on the printer type, some of the following parameters need to be configured:

printerName (string) - the name of one of the available printers from the availablePrinters array obtained by reading the current configuration (the previous API call).
printerType (string) - the value EscPos (for ESC/POS compatible printers), Cpcl (for CPCL compatible printers), or System (to use the system printing driver). Thermal printers are in most cases EscPos, whereas if printing to an A4 printer (Laser, InkJet) the type System should be used. receiptLayout (string) - the default print format, Slip for a fiscal slip (thermal printers) or Invoice for an invoice in A4 format (Laser/InkJet printers).
receiptWidth (int) - only for EscPos and Cpcl printers, the print width in pixels (most commonly 384 for 58mm printers or 576 for 80mm printers).
receiptFontSizeNormal (int) - only for EscPos and Cpcl printers, the size of the standard font (most commonly 21 for 58mm printers, or 26 for 80mm printers).
receiptFontSizeLarge (int) - only for EscPos and Cpcl printers, the size of the larger font (most commonly 24 for 58mm printers, or 32 for 80mm printers).
receiptHeaderTextLines (list(string)) - an array of texts printed at the top of the invoice.
receiptHeaderImage (string) - a base64-encoded GIF image printed at the top of the invoice.
receiptFooterTextLines (list(string)) - an array of texts printed at the bottom of the invoice.
receiptFooterImage (string) - a base64-encoded GIF image printed at the bottom of the invoice.
qrCodeSize (int) - the size of the QR code for fiscal receipt verification in pixels.
receiptFeedLinesBegin (int) - only for EscPos and Cpcl printers, how many blank lines are printed at the beginning of the invoice, used as needed to properly position the paper for the start of printing.
receiptFeedLinesEnd (int) - only for EscPos and Cpcl printers, how many blank lines are printed at the end of the invoice, used as needed to properly position the paper for cutting.
receiptCutPaper (string) - only for EscPos and Cpcl printers, whether a command to cut and/or feed the paper is sent at the end of printing, and it can have one of the following values: FeedAndCutPaper (the paper is fed and cut), CutPaper (the paper is cut), None (no additional command is sent at the end of printing).
receiptOpenCashDrawer (string) - only for EscPos and Cpcl printers, whether a command to open the cash drawer connected to the printer is sent, and depending on the printer type one of the following values should be set: Epson_1 (most common), Epson_2, M80_1, M80_2, or None to not send a command to open the cash drawer.
receiptPrintGtin (boolean) - the setting for whether the article's GTIN (barcode) is printed on the invoice

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/settings' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "printerName": "S85",
    "printerType": "EscPos",
    "receiptWidth": 384,
    "receiptLayout": "Slip",
    "receiptFontSizeNormal": 21,
    "receiptFontSizeLarge": 24,
    "receiptHeaderTextLines": [],
    "receiptHeaderImage": null,
    "receiptFooterTextLines": [],
    "receiptFooterImage": null,
    "receiptFeedLinesBegin": 0,
    "receiptFeedLinesEnd": 3,
    "receiptCutPaper": "FeedAndCutPaper",
    "receiptOpenCashDrawer": "Epson_1",
    "qrCodeSize": 386
 }'

Primer odgovoraResponse example 200 OK

Prazno telo odgovora.Empty response body.

Fiskalizacija

Fiscalization

Inicijalizacija

Initialization

Pre fiskalizacije računa neophodno je proveriti status PFR-a (LPFR ili VPFR u zavisnosti od podešavanja).

Na narednoj slici je predstavljen uobičajni niz koraka koji se obavljaju pre fiskalizacije računa:

Dijagram toka inicijalizacije — slika iz originalne dokumentacije (koraci su detaljno opisani u nastavku).

Proveriti da li su ESIR i PFR dostupni pozivom /api/attention (opisan u "Provera dostupnosti"). Ukoliko je odgovor negativan treba prikazati odgovarajuću poruku korisniku i posle par sekundi pokušati ponovo. Nastaviti ovu proveru bez ograničenja dok ESIR ne postane dostupan.
Samo ako se koristi LPFR: proveriti da li je bezbednosni element prisutan pozivom /api/status (opisan u "Provera statusa") i proverom da li se u spisku statusa u polju gsc nalazi kod 1300. Ukoliko se ovaj kod nalazi onda treba prikazati adekvatnu poruku korisniku da bezbednosni element nije prisutan i nastaviti ovu proveru sve dok se ne izgubi kod 1300.
Samo ako se koristi LPFR: proveriti dali je neophodan unos PIN-a pozivom /api/status i proverom da li se u spisku statusa u polju gsc nalazi kod 1500. Ukoliko se ovaj kod nalazi onda treba prikazati adekvatnan ekran korisniku za unos PIN-a i slanjem istog na /api/pin poziv za proveru (opsian u "Unos PIN-a bezbednosnog elementa"). Nakon uspešno unetog PIN-a se može nastaviti dalje sa radom.
Obaviti standardni unos svih elemenata računa i poslati na fiskalizaciju i štampu pozivom /api/invoices(opisan u "Fiskalizacija računa"). Ukoliko je vraćena greška da bezbednosni element nije prisutan (npr. korisnik je izvukao karticu u međuvremenu) onda se vratiti na korak 2. Ukoliko je vraćena greška da je neophodan unos PIN-a (npr. korisnik je izvukao i vratio istu ili drugu karticu) onda se vratiti na korak 3. U suprotnom ovaj API će vratiti grešku ukoliko postoji problem u sadržaju računa (koji treba prikazati korisniku adekvatno na ekranu) ili odgovor da je fiskalizacija i štampa uspešno obavljena u kom slučaju se može pristupiti unosom novog računa od koraka 2. U slučaju da je vraćena greška ona može biti geška pre fiskalizacije ili greška nakon fiskalizacije ali pre štampanja računa. U slučaju da je fiskalizacija obavljena ali je greška nastala prilikom štampe računa odgovor će pored informacija o grešci sadržati i polje invoiceResponse u kom slučaju je potrebno ispraviti grešku sa štampačem (npr. ukoliko nema papira) a potom ponoviti isti poziv ali uključiti i invoiceResponse polje što je signal Teron ESIR API-u da ne radi ponovo fiskalizaciju već samo da pokuša štampu ponovo.

Before fiscalizing an invoice, it is necessary to check the status of the PFR (LPFR or VPFR depending on the configuration).

The following image presents the usual sequence of steps performed before invoice fiscalization:

Initialization flow diagram — image from the original documentation (the steps are described in detail below).

Check whether the ESIR and PFR are available by calling /api/attention (described in "Availability check"). If the response is negative, an appropriate message should be displayed to the user and a retry should be attempted after a few seconds. Continue this check indefinitely until the ESIR becomes available.
Only if LPFR is used: check whether the security element is present by calling /api/status (described in "Status check") and checking whether the code 1300 is present in the status list in the gsc field. If this code is present, an appropriate message should be displayed to the user indicating that the security element is not present, and this check should continue until the code 1300 disappears.
Only if LPFR is used: check whether PIN entry is required by calling /api/status and checking whether the code 1500 is present in the status list in the gsc field. If this code is present, an appropriate screen should be displayed to the user for PIN entry, and the PIN should be sent to the /api/pin call for verification (described in "Security element PIN entry"). After the PIN has been successfully entered, work can continue.
Perform the standard entry of all invoice elements and send them for fiscalization and printing by calling /api/invoices (described in "Invoice fiscalization"). If an error is returned indicating that the security element is not present (e.g., the user removed the card in the meantime), return to step 2. If an error is returned indicating that PIN entry is required (e.g., the user removed and reinserted the same or a different card), return to step 3. Otherwise, this API will return an error if there is a problem with the invoice content (which should be displayed to the user appropriately on the screen) or a response indicating that fiscalization and printing have been successfully completed, in which case entry of a new invoice can begin from step 2. In case an error is returned, it may be an error before fiscalization or an error after fiscalization but before invoice printing. In case fiscalization was performed but the error occurred during invoice printing, the response will, in addition to the error information, also contain the invoiceResponse field, in which case the printer error needs to be corrected (e.g., if there is no paper) and then the same call repeated, but this time including the invoiceResponse field, which is a signal to the Teron ESIR API not to perform fiscalization again but only to attempt printing once more.

GET/api/status#

Provera status

Status check

Ovaj poziv vraća status sistema za fiskalizaciju (LPFR ili VPFR u zavisnosti od podešavanja). Glavna polja u odgovoru od interesa za integraciju sa ESIR-om su:

sdcDateTime (timestamp) - trenutno vreme na PFR-u
gsc: (list of string) - niz status LPFR-a. Za spisak svih statusa konsultovati PURS dokumentaciju za LPFR, glavni statusi su opisani i prethodnoj sekciji u okviru opisa niza koraka prilikom fiskalizacije računa. Ovo polje ne postoji u slučaju korišćenja VPFR-a
uid (string) - UID bezbednosnog elementa (LPFR, ukoliko je ubačen) odnosno sertifikata (VPFR)

This call returns the status of the fiscalization system (LPFR or VPFR depending on the configuration). The main fields in the response of interest for integration with ESIR are:

sdcDateTime (timestamp) - the current time on the PFR
gsc: (list of string) - an array of LPFR statuses. For a list of all statuses, consult the PURS documentation for LPFR; the main statuses are also described in the previous section within the description of the sequence of steps during invoice fiscalization. This field does not exist when using VPFR
uid (string) - the UID of the security element (LPFR, if inserted) or of the certificate (VPFR)

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/status' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "allTaxRates": [
    {
      "groupId": 1,
      "taxCategories": [
        {
          "categoryType": 0,
          "name": "Без ПДВ",
          "orderId": 4,
          "taxRates": [
            {
              "label": "Г",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "Није у ПДВ",
          "orderId": 1,
          "taxRates": [
            {
              "label": "А",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "О-ПДВ",
          "orderId": 2,
          "taxRates": [
            {
              "label": "Ђ",
              "rate": 20
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "П-ПДВ",
          "orderId": 3,
          "taxRates": [
            {
              "label": "Е",
              "rate": 10
            }
          ]
        }
      ],
      "validFrom": "2021-11-01T02:00:00.000+01:00"
    },
    {
      "groupId": 6,
      "taxCategories": [
        {
          "categoryType": 0,
          "name": "Без ПДВ",
          "orderId": 4,
          "taxRates": [
            {
              "label": "Г",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "Није у ПДВ",
          "orderId": 1,
          "taxRates": [
            {
              "label": "А",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "О-ПДВ",
          "orderId": 2,
          "taxRates": [
            {
              "label": "Ђ",
              "rate": 20
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "П-ПДВ",
          "orderId": 3,
          "taxRates": [
            {
              "label": "Е",
              "rate": 10
            }
          ]
        }
      ],
      "validFrom": "2014-01-01T00:00:00.000+01:00"
    },
    {
      "groupId": 3,
      "taxCategories": [
        {
          "categoryType": 0,
          "name": "Без ПДВ",
          "orderId": 4,
          "taxRates": [
            {
              "label": "Г",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "Није у ПДВ",
          "orderId": 1,
          "taxRates": [
            {
              "label": "А",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "О-ПДВ",
          "orderId": 2,
          "taxRates": [
            {
              "label": "Ђ",
              "rate": 20
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "П-ПДВ",
          "orderId": 3,
          "taxRates": [
            {
              "label": "Е",
              "rate": 8
            }
          ]
        }
      ],
      "validFrom": "2012-10-01T00:00:00.000+02:00"
    },
    {
      "groupId": 2,
      "taxCategories": [
        {
          "categoryType": 0,
          "name": "Без ПДВ",
          "orderId": 4,
          "taxRates": [
            {
              "label": "Г",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "Није у ПДВ",
          "orderId": 1,
          "taxRates": [
            {
              "label": "А",
              "rate": 0
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "О-ПДВ",
          "orderId": 2,
          "taxRates": [
            {
              "label": "Ђ",
              "rate": 18
            }
          ]
        },
        {
          "categoryType": 0,
          "name": "П-ПДВ",
          "orderId": 3,
          "taxRates": [
            {
              "label": "Е",
              "rate": 8
            }
          ]
        }
      ],
      "validFrom": "2005-01-01T00:00:00.000+01:00"
    }
  ],
  "currentTaxRates": {
    "groupId": 1,
    "taxCategories": [
      {
        "categoryType": 0,
        "name": "Без ПДВ",
        "orderId": 4,
        "taxRates": [
          {
            "label": "Г",
            "rate": 0
          }
        ]
      },
      {
        "categoryType": 0,
        "name": "Није у ПДВ",
        "orderId": 1,
        "taxRates": [
          {
            "label": "А",
            "rate": 0
          }
        ]
      },
      {
        "categoryType": 0,
        "name": "О-ПДВ",
        "orderId": 2,
        "taxRates": [
          {
            "label": "Ђ",
            "rate": 20
          }
        ]
      },
      {
        "categoryType": 0,
        "name": "П-ПДВ",
        "orderId": 3,
        "taxRates": [
          {
            "label": "Е",
            "rate": 10
          }
        ]
      }
    ],
    "validFrom": "2021-11-01T02:00:00.000+01:00"
  },
  "deviceSerialNumber": "01-0001-WPYB002248000772",
  "gsc": [
    "1300",
    "0210"
  ],
  "hardwareVersion": "1.0",
  "lastInvoiceNumber": "RX4F7Y5L-RX4F7Y5L-132",
  "make": "OFS",
  "model": "OFS P5 EFU LPFR",
  "mssc": [],
  "protocolVersion": "2.0",
  "sdcDateTime": "2024-03-11T23:03:24.390+01:00",
  "softwareVersion": "2.0",
  "supportedLanguages": [
    "sr-RS",
    "sr-Cyrl-RS",
    "en-US"
  ]
}

POST/api/pin#

Unos PIN-a bezbednosnog elementa

Security element PIN entry

Namena ovog poziva je da otključa bezbednosni element za potrebe fiskalizacije unosom PIN koda. PIN kod se prosleđuje u zahtevu dok odgovor sadrži status kod operacije a pored status koda ukoliko je operacija uspešna odgovor sadrži HTTP 200 OK status dok u svim ostalim slučajevima vraća status HTTP 4xx ili HTTP 5xx. Mogući numerički status kodovi u odgovoru su:

0100 - PIN je ispravno unet
1300 - Bezbednosni element nije prisutan
2400 - LPFR nije spreman
2800 - Pogrešan format PIN-a (očekivano 4 cifre)
2806 - Pogrešan format PIN-a (očekivano 4 cifre)

Napomena: zbog uniformnosti sa LPFR API-jima koje je propisao PURS, ovo je jedini API poziv koji na ulazu prihvata čist tekst (Content-type: text/plain).

The purpose of this call is to unlock the security element for fiscalization by entering the PIN code. The PIN code is passed in the request, while the response contains the operation status code. In addition to the status code, if the operation is successful the response contains an HTTP 200 OK status, while in all other cases it returns an HTTP 4xx or HTTP 5xx status. The possible numeric status codes in the response are:

0100 - PIN entered correctly
1300 - Security element is not present
2400 - LPFR is not ready
2800 - Incorrect PIN format (4 digits expected)
2806 - Incorrect PIN format (4 digits expected)

Note: for the sake of uniformity with the LPFR APIs prescribed by PURS, this is the only API call that accepts plain text as input (Content-type: text/plain).

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/pin' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '1234'

Primer odgovoraResponse example 200 OK

"0100"

Izdavanje računa

Invoice issuance

Svi računi se fiskalizuju i štampaju pozivom POST /api/invoices metode i prosleđivanjem zahteva koji detaljnije opisuje sadržaj računa.

Model podataka zahteva:

invoiceRequest (object): objekat koji sadrži detaljan opis sadržaja računa:
- invoiceType (string, obavezan podatak): tip računa, može imati vrednosti: Normal (promet), Proforma (predračun), Copy (kopija), Training (trening), Advance (avans)
- transactionType (string, obavezan podatak): tip transakcije, može imati vrednosti: Sale (prodaja), Refund (refundacija)
- payment (list(object), obavezan podatak): niz objekata koji opisuju metode plaćanja gde svaki element sadrži sledeća polja:
  - paymentType (string, obavezan podatak): tip plaćanja, može imati vrednosti: Cash (gotovina), Card (platna kartica), Check (ček), WireTransfer (prenos na račun), Voucher (vaučer), MobileMoney (instant plaćanje), Other (drugo bezgotovinsko plaćanje)
  - amount (money, obavezan podatak): iznos uplate po navedenom tipu plaćanja
- dateAndTimeOfIssue (timestamp): koristi se u slučajevima da je obveznik fiskalizacije evidentirao uplatu avansa ranije (npr. za virmanski avans dat u prethodnom danu)
- cashier (string): naziv kasira, ukoliko nije navedeno automatski će biti dodata vrednost "Prodavac 1"
- buyerId (string): identifikator kupca - ovo polje je opciono, maksimalne dužine 20 znakova (ASCII isključivo) i sadrži identifikaciju kupca (JIB firme, broj lične karte, broj pasoša). Ukoliko je u pitanju evidentiranje prometa u veleprodaji neophodno je da ovo polje počinje sa prefiksom "VP:". U slučajevima kada je uređaj registrovan za rad isključivo u veleprodaji ovaj prefiks će biti automatski dodat ukoliko nije poslat u zahtevu.
- buyerCostCenterId (string): opciono polje kupca
- referentDocumentNumber (string): broj referentnog dokumenta (broj računa na koji se referencira ovaj račun)
- referentDocumentDT (timestamp): vreme kada je izdat referentni dokument (vreme kada je fiskalizovan račun na koji se referencira ovaj račun)
- items (list(object)): stavke računa gde svaka stavka sadrži:
  - name (string, obavezan podatak): naziv artikla, ukoliko je potrebno jedinicu mere treba dodati na kraju naziva artikla (npr: "Brašno /kg")
  - gtin (string, obavezan podatak, 8-14 znakova): GTIN (barkod) artikla
  - labels (list(string), obavezan podatak): niz poreskih stopa po kojima je oporezovana stavka (trenutno je u uvek jedna poreska stopa). Obratiti pažnju da Poreska Uprava može da odluči da koristi slova iz ćiriličnog ili latiničnog alfabeta i obavezno je koristiti iste vrednosti koje je i Poreska Uprava definisala (vrednosti koje se dobijaju u odgovoru za "Proveru status" opisanom u prethodnoj sekciji)
  - unitPrice (money, obavezan podatak): jedinična cena sa PDV-om
  - quantity (quantity, obavezan podatak): količina
  - totalAmount (money, obavezan podatak): ukupna cena
  - discount (percent): iznos uračunatog popusta u procentima
  - discountAmount (money): iznos u novcu uračunatog popusta
print (boolean): da li treba štampati račun nakon fiskalizacije
email (string): email na koji treba poslati račun nakon fiskalizacije
renderReceiptImage (boolean): da li odgovor treba da sadrži Base64 kodiran izgled računa u zadatom formatu u polju invoiceImagePngBase64 odnosno invoiceImagePdfBase64 u zavisnosti od izabranog formata.
receiptImageFormat (string): Format u kome će piti renderisana slika računa (default je Png), u zavisnosti od formata računa (receiptLayout, naredno polje) moguće vrednosti su za Slip: Png, Pdf, Html a za Invoice moguće vrednosti su Pdf i Html.
receiptLayout (string): Izgled računa, moguće vrednosti su Slip (isečak) ili Invoice (račun u A4 formatu), default vrednost je Slip
receiptHeaderImage (string): Base64 kodirana slika koja se štampa na početku računa
receiptFooterImage (string): Base64 kodirana slika koja se štampa na kraju računa
receiptHeaderTextLines (list(string)): niz tekstova koji se štampaju na početku računa
receiptFooterTextLines (list(string)): niz tekstova koji se štampaju na kraju računa
advancePaid (money): iznos avansne uplate, kod automatskog izdavanja konačnog računa.
advanceTax (money): iznos poreza obračunatog na avansne uplate, kod automatskog izdavanja konačnog računa.

Svaki zahtev za fiskalizacijom opciono u HTTP zaglavlju može da uključi polje RequestId u okviru koga se navodi jedinstven identifikator zahteva koga generiše sistem koji šalje zahtev za fiskalizacijom (maksimalna dužina je 32 alfanumerička znaka). Za više detalja pogledati API poziv "Pregled sadržaja računa po broju zahteva".

U nastavku su navedeni primeri najčešćih računa koji se pojavljuju u praksi. ESIR nije ograničen samo na navedene primere već su oni tu da olakšaju razumevanje modela podataka kao i proces integracije a svakako je neophodno da zahteve koje šaljete za fiskalizacijom prilagodite vašim konkretnim potrebama uz razumevanje kompletnog modela podataka i relevantnih poreskih zakona.

Napomena: navedeni primeri računa su generisani na testnom SUF okruženju koje koristi testne poreske stop (drugačije labele i iznose poreza, npr. F=10%) dok poreske stope na produkcionom okruženju odgovaraju trenutno važećim poreskim zakonima i propisima.

All invoices are fiscalized and printed by calling the POST /api/invoices method and passing a request that describes the invoice content in more detail.

Request data model:

invoiceRequest (object): object containing a detailed description of the invoice content:
- invoiceType (string, required): invoice type, can have the values: Normal (turnover), Proforma (proforma invoice), Copy (copy), Training (training), Advance (advance)
- transactionType (string, required): transaction type, can have the values: Sale (sale), Refund (refund)
- payment (list(object), required): array of objects describing the payment methods, where each element contains the following fields:
  - paymentType (string, required): payment type, can have the values: Cash (cash), Card (payment card), Check (check), WireTransfer (wire transfer to account), Voucher (voucher), MobileMoney (instant payment), Other (other non-cash payment)
  - amount (money, required): payment amount for the specified payment type
- dateAndTimeOfIssue (timestamp): used in cases where the fiscalization obligor recorded an advance payment earlier (e.g. for a wire-transfer advance made on the previous day)
- cashier (string): cashier name; if not specified, the value "Prodavac 1" will be added automatically
- buyerId (string): buyer identifier - this field is optional, with a maximum length of 20 characters (ASCII only) and contains the buyer's identification (company JIB, ID card number, passport number). In the case of recording wholesale turnover, this field must begin with the prefix "VP:". In cases where the device is registered to operate exclusively in wholesale, this prefix will be added automatically if it is not sent in the request.
- buyerCostCenterId (string): optional buyer field
- referentDocumentNumber (string): reference document number (the number of the invoice this invoice refers to)
- referentDocumentDT (timestamp): the time the reference document was issued (the time the invoice this invoice refers to was fiscalized)
- items (list(object)): invoice items, where each item contains:
  - name (string, required): article name; if needed, the unit of measure should be added at the end of the article name (e.g.: "Brašno /kg")
  - gtin (string, required, 8-14 characters): article GTIN (barcode)
  - labels (list(string), required): array of tax rates by which the item is taxed (currently there is always a single tax rate). Note that the Tax Administration may decide to use letters from the Cyrillic or Latin alphabet, and you must use the same values that the Tax Administration has defined (the values obtained in the response for the "Status check" described in the previous section)
  - unitPrice (money, required): unit price including VAT
  - quantity (quantity, required): quantity
  - totalAmount (money, required): total price
  - discount (percent): amount of the applied discount as a percentage
  - discountAmount (money): monetary amount of the applied discount
print (boolean): whether the invoice should be printed after fiscalization
email (string): email address to which the invoice should be sent after fiscalization
renderReceiptImage (boolean): whether the response should contain a Base64-encoded rendering of the invoice in the specified format in the invoiceImagePngBase64 or invoiceImagePdfBase64 field, depending on the selected format.
receiptImageFormat (string): The format in which the invoice image will be rendered (default is Png); depending on the invoice format (receiptLayout, the next field), the possible values for Slip are: Png, Pdf, Html, and for Invoice the possible values are Pdf and Html.
receiptLayout (string): Invoice layout, possible values are Slip (receipt slip) or Invoice (invoice in A4 format), the default value is Slip
receiptHeaderImage (string): Base64-encoded image printed at the beginning of the invoice
receiptFooterImage (string): Base64-encoded image printed at the end of the invoice
receiptHeaderTextLines (list(string)): array of texts printed at the beginning of the invoice
receiptFooterTextLines (list(string)): array of texts printed at the end of the invoice
advancePaid (money): advance payment amount, when automatically issuing the final invoice.
advanceTax (money): amount of tax calculated on advance payments, when automatically issuing the final invoice.

Each fiscalization request may optionally include the RequestId field in the HTTP header, which specifies a unique request identifier generated by the system sending the fiscalization request (the maximum length is 32 alphanumeric characters). For more details, see the API call "View invoice content by request number".

The following are examples of the most common invoices that occur in practice. ESIR is not limited to only the listed examples; they are provided to facilitate understanding of the data model as well as the integration process, and you must of course adapt the fiscalization requests you send to your specific needs while understanding the complete data model and the relevant tax laws.

Note: the listed invoice examples were generated in a test SUF environment that uses test tax rates (different labels and tax amounts, e.g. F=10%), while the tax rates in the production environment correspond to the currently applicable tax laws and regulations.

POST/api/invoices#

Gotovinski račun

Cash invoice

Gotovinski račun sa jednim artiklom i jednim načinom plaćanja (gotovina). Ovaj račun će nakon fiskalizacije biti odštampan na štampaču.

A cash invoice with one article and one payment method (cash). After fiscalization, this invoice will be printed on the printer.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Normal",
        "transactionType": "Sale",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "Cash"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 50.00,
                "quantity": 2.000
            }
        ],
        "cashier": "Radnik 1"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "Vvwq4nVn/wIQ...",
  "invoiceCounter": "100/138ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-138",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n----------- ПРОМЕТ ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00       2,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nГотовина:                       100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:47:09\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-138\r\nБројач рачуна:               100/138ПП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:47:09.548+01:00",
  "signature": "Mw+IB0vgnaMjYrwA7m7zhtRseRIZ...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 138,
  "transactionTypeCounter": 100,
  "verificationQRCode": "R0lGODlhhAGEAf...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0....="
}

POST/api/invoices#

Gotovinski račun sa identifikacijom kupca

Cash invoice with buyer identification

Gotovinski račun sa identifikacijom kupca sadrži iste elemente kao i prethodni račun uz dodata polja i invoiceRequest objektu:

buyerId (string) - identifikator kupca
buyerCostCenterId (string) - opciono polje kupca

A cash invoice with buyer identification contains the same elements as the previous invoice, with additional fields added to the invoiceRequest object:

buyerId (string) - buyer identifier
buyerCostCenterId (string) - optional buyer field

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Normal",
        "transactionType": "Sale",
        "buyerId": "111758195",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "Cash"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 50.00,
                "quantity": 2.000
            }
        ],
        "cashier": "Radnik 1"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "Z1O1FZjxn23+BEdS...",
  "invoiceCounter": "101/139ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-139",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nИД купца:                 111758195\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n----------- ПРОМЕТ ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00       2,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nГотовина:                       100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:47:38\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-139\r\nБројач рачуна:               101/139ПП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:47:38.530+01:00",
  "signature": "PIB3Tr2V+01aimBSfOoR...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 139,
  "transactionTypeCounter": 101,
  "verificationQRCode": "R0lGODlhhAGEAfA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg..."
}

POST/api/invoices#

Gotovinski račun sa više stavki i više načina plaćanja uz slanje na email

Cash invoice with multiple items and multiple payment methods, sent via email

Gotovinski račun sa više artikala i više načina plaćanja (gotovina i kartica), bez štampe na štampač i sa slanjem na email dodavanjem novih polja u zahtev:

print (boolena) - vrednost false da se ne štampa račun
email (string) - email adresa na koju će biti poslat račun

Cash invoice with multiple articles and multiple payment methods (cash and card), without printing on the printer and with sending to email by adding new fields to the request:

print (boolean) - value false so that the invoice is not printed
email (string) - email address to which the invoice will be sent

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "print": false,
    "email": "test@ofs.ba",
    "invoiceRequest": {
        "invoiceType": "Normal",
        "transactionType": "Sale",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "Cash"
            },
            {
                "amount": 200.00,
                "paymentType": "Card"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 50.00,
                "quantity": 2.000
            },
            {
                "name": "Artikl 2",
                "gtin": "12345679",
                "labels": [
                    "F"
                ],
                "totalAmount": 200.00,
                "unitPrice": 200.00,
                "quantity": 1.000
            }
        ],
        "cashier": "Radnik 1"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "T32whYKOrTGdKW...",
  "invoiceCounter": "102/140ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-140",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n----------- ПРОМЕТ ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00       2,000         100,00\r\nArtikl 2 (F)                          \r\n     200,00       1,000         200,00\r\n--------------------------------------\r\nУкупан износ:                   300,00\r\nГотовина:                       100,00\r\nПлатна картица:                 200,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         29,73\r\n--------------------------------------\r\nУкупан износ пореза:             29,73\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:48:47\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-140\r\nБројач рачуна:               102/140ПП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:48:47.626+01:00",
  "signature": "IDwlpJMGu00vBFeCWWIkjgXm....",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 29.7297,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 300,
  "totalCounter": 140,
  "transactionTypeCounter": 102,
  "verificationQRCode": "R0lGODlhhAGEAfA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0...="
}

POST/api/invoices#

Kopija računa

Invoice copy

Kopija računa ima isti sadržaj kao i originalni račun sa postavljenim poljem invoiceRequest.invoiceType na Copy i uz dodata dva polja u invoiceRequest objektu koja se referišu na prvi račun:

referentDocumentNumber (string) - broj originalnog računa
referentDocumentDT (timestamp) - vreme originalnog računa

An invoice copy has the same content as the original invoice with the invoiceRequest.invoiceType field set to Copy and with two additional fields in the invoiceRequest object that reference the first invoice:

referentDocumentNumber (string) - number of the original invoice
referentDocumentDT (timestamp) - time of the original invoice

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Copy",
        "transactionType": "Sale",
        "referentDocumentNumber": "RX4F7Y5L-RX4F7Y5L-140",
        "referentDocumentDT": "2024-03-12T07:48:47.626+01:00",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "Cash"
            },
            {
                "amount": 200.00,
                "paymentType": "Card"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 50.00,
                "quantity": 2.000
            },
            {
                "name": "Artikl 2",
                "gtin": "12345679",
                "labels": [
                    "F"
                ],
                "totalAmount": 200.00,
                "unitPrice": 200.00,
                "quantity": 1.000
            }
        ],
        "cashier": "Radnik 1"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "DyCdfR/iSM9miXAK3h0YU89roRF4wRjYl1mYfz....",
  "invoiceCounter": "6/141КП",
  "invoiceCounterExtension": "КП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-141",
  "journal": "======= ОВО НИЈЕ ФИСКАЛНИ РАЧУН ======\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-140\r\nРеф. вријеме:     12.03.2024. 07:48:47\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n----------- КОПИЈА ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00       2,000         100,00\r\nArtikl 2 (F)                          \r\n     200,00       1,000         200,00\r\n--------------------------------------\r\nУкупан износ:                   300,00\r\nГотовина:                       100,00\r\nПлатна картица:                 200,00\r\n======================================\r\n======= ОВО НИЈЕ ФИСКАЛНИ РАЧУН ======\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         29,73\r\n--------------------------------------\r\nУкупан износ пореза:             29,73\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:49:43\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-141\r\nБројач рачуна:                 6/141КП\r\n======================================\r\n======= ОВО НИЈЕ ФИСКАЛНИ РАЧУН ======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:49:43.171+01:00",
  "signature": "Zfeew71z6wpGGTXK2w....",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 29.7297,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 300,
  "totalCounter": 141,
  "transactionTypeCounter": 6,
  "verificationQRCode": "R0lGODlhhAG....",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTV...="
}

POST/api/invoices#

Refundacija računa

Invoice refund

Refundacija računa ima isti sadržaj kao i originalni račun sa postavljenim poljem invoiceRequest.transactionType na Refund i uz dodata dva polja u invoiceRequest objektu koja se referišu na prvi račun:

referentDocumentNumber (string) - broj originalnog računa
referentDocumentDT (timestamp) - vreme originalnog računa

Ukoliko se račun na koji se referencira nalazi na istom uređaju uradiće se dodatne provere:

provera da li je referencirani račun već refundiran u punom iznosu i ukoliko je to slučaj refundacija neće biti moguća.
provera da li je referencirani račun tipa Prodaja (Normal) a ne tipa Refundacija (Refund)

Napomena: u zavisnosti od načina kako se realizuje refundacije može postojati potreba i da se načini plaćanja promene u odnosu na originalni račun.

An invoice refund has the same content as the original invoice with the invoiceRequest.transactionType field set to Refund and with two additional fields in the invoiceRequest object that reference the first invoice:

referentDocumentNumber (string) - number of the original invoice
referentDocumentDT (timestamp) - time of the original invoice

If the referenced invoice is located on the same device, additional checks will be performed:

a check of whether the referenced invoice has already been refunded in full and, if so, the refund will not be possible.
a check of whether the referenced invoice is of type Sale (Normal) and not of type Refund

Note: depending on the way the refund is carried out, there may be a need for the payment methods to be changed relative to the original invoice.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'X-Teron-SerialNumber: <serijski_broj>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Normal",
        "transactionType": "Refund",
        "referentDocumentNumber": "RX4F7Y5L-RX4F7Y5L-140",
        "referentDocumentDT": "2024-03-12T07:48:47.626+01:00",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "Cash"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 50.00,
                "quantity": 2.000
            }
        ],
        "cashier": "Radnik 1"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "Lf2RL7t6S/W7z8Ms0....",
  "invoiceCounter": "9/142ПР",
  "invoiceCounterExtension": "ПР",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-142",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-140\r\nРеф. вријеме:     12.03.2024. 07:48:47\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n--------- ПРОМЕТ РЕФУНДАЦИЈА ---------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00       2,000        -100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nГотовина:                       100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:50:19\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-142\r\nБројач рачуна:                 9/142ПР\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:50:19.735+01:00",
  "signature": "YDmrYAEu07Ra3G9XgFkP11A0dU4...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 142,
  "transactionTypeCounter": 9,
  "verificationQRCode": "R0lGODlhhAGE....",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0Rj..."
}

POST/api/invoices#

Avansni račun

Advance invoice

Avansni račun se izdajte na sličan način kao i regularan gotovinski račun osim što ste invoiceRequest.invoiceType postavlja na Advance i dodaje se dodatlno polje koje opisuje iznos koji je uplaćen avansno:

advancePayment (list(object)): niz koji opisuje avansne uplate po poreskim stopama
- amount (money): iznos avansne uplate
- label (string): oznaka poreske stope po kojoj se obračunava porez na ovu uplatu

Pre fiskalizacije ESIR će konvertovati ovaj račun prema PURS propisima tako da su stavke računa odgovaraju navedenim avansnim uplatama po poreskim stopama dok će prave stavke računa biti odštampane na dnu računa van fiskalnog dela računa.

An advance invoice is issued in a similar way to a regular cash invoice, except that invoiceRequest.invoiceType is set to Advance and an additional field is added that describes the amount paid in advance:

advancePayment (list(object)): array describing the advance payments by tax rates
- amount (money): amount of the advance payment
- label (string): label of the tax rate by which tax on this payment is calculated

Before fiscalization, the ESIR will convert this invoice according to PURS regulations so that the invoice items correspond to the stated advance payments by tax rates, while the actual invoice items will be printed at the bottom of the invoice outside the fiscal part of the invoice.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Advance",
        "transactionType": "Sale",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "WireTransfer"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 600.00,
                "unitPrice": 50.00,
                "quantity": 12
            },
            {
                "name": "Artikl 2",
                "gtin": "12345679",
                "labels": [
                    "F"
                ],
                "totalAmount": 400.00,
                "unitPrice": 200.00,
                "quantity": 2
            }
        ],
        "cashier": "Radnik 1"
    },
    "advancePayment": [
        {
            "label": "F",
            "amount": 100.00
        }
    ]
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "sGuINJ6LbHoU7ga...",
  "invoiceCounter": "13/143АП",
  "invoiceCounterExtension": "АП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-143",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n------------ АВАНС ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     100,00       1,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nПренос на рачун:                100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:51:53\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-143\r\nБројач рачуна:                13/143АП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:51:53.207+01:00",
  "signature": "OTwFKf73jhOr9jPsIS/94nSlMCESYPna5Wjs0ztSK...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 143,
  "transactionTypeCounter": 13,
  "verificationQRCode": "R0lGODlhhAGEAf....",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZ..."
}

POST/api/invoices#

Naredni avansni račun

Subsequent advance invoice

Naredni avansni račun se izdaje kao i pravi avansni račun uz referenciranje na prethodni avansni račun dodavanjem sledećih polja u invoiceRequest objektu:

referentDocumentNumber (string) - broj prethodnog avansnog računa
referentDocumentDT (timestamp) - vreme prethodnog avansnog računa

Napomena: izdavanje narednog avansnog računa na ovaj način je moguće samo ukoliko su svi prethodni avansni računi izdati kroz isti ESIR i postoje u internoj bazi računa.

A subsequent advance invoice is issued just like a regular advance invoice, with a reference to the previous advance invoice by adding the following fields to the invoiceRequest object:

referentDocumentNumber (string) - number of the previous advance invoice
referentDocumentDT (timestamp) - time of the previous advance invoice

Note: issuing a subsequent advance invoice in this way is only possible if all previous advance invoices were issued through the same ESIR and exist in the internal invoice database.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Advance",
        "transactionType": "Sale",
        "referentDocumentNumber": "RX4F7Y5L-RX4F7Y5L-143",
        "referentDocumentDT": "2024-03-12T07:51:53.207+01:00",
        "payment": [
            {
                "amount": 400.00,
                "paymentType": "WireTransfer"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 600.00,
                "unitPrice": 50.00,
                "quantity": 12
            },
            {
                "name": "Artikl 2",
                "gtin": "12345679",
                "labels": [
                    "F"
                ],
                "totalAmount": 400.00,
                "unitPrice": 200.00,
                "quantity": 2
            }
        ],
        "cashier": "Radnik 1"
    },
    "advancePayment": [
        {
            "label": "F",
            "amount": 400.00
        }
    ]
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "ICT9i8bdRBjSy...",
  "invoiceCounter": "14/144АП",
  "invoiceCounterExtension": "АП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-144",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-143\r\nРеф. вријеме:     12.03.2024. 07:51:53\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n------------ АВАНС ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     400,00       1,000         400,00\r\n--------------------------------------\r\nУкупан износ:                   400,00\r\nПренос на рачун:                400,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         39,64\r\n--------------------------------------\r\nУкупан износ пореза:             39,64\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:53:26\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-144\r\nБројач рачуна:                14/144АП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:53:26.177+01:00",
  "signature": "CazwAmJHwtDiJ4...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 39.6396,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 400,
  "totalCounter": 144,
  "transactionTypeCounter": 14,
  "verificationQRCode": "R0lGODlhhAGEAfA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNUyQ...="
}

POST/api/invoices/final#

Konačni račun

Final invoice

Izadavanje konačnog računa se vrši slanjem sledećeg zahteva na /api/invoices/final endpoint:

advanceLastInvoiceNumber (string) - broj poslednjeg avansnog računa
payment (list(object)): niz koji opisuje avansne uplate
- paymentType (string): tip plaćanja
- amount (money): iznos avansne uplate

Pored ovih polja u zahetvu se mogu opciono navesti i sledeća polja:

print (boolean) - da li se računi štampaju
email (string) - email na koji će biti poslati računi
printerName (string) - naziv štampača na koji se štampa u suprotnom se koristi štampač koji je podešen
printerType (string) - tip štampača na koji se štampa u suprotnom se koristi tip štampača koji je podešen
receiptHeaderImage (string) - Base64 kodirana slika koja se štampa na početku računa
receiptFooterImage (string) - Base64 kodirana slika koja se štampa na kraju računa
receiptHeaderTextLines (list(string)) - niz tekstova koji se štampaju na početku računa
receiptFooterTextLines (list(string)) - niz tekstova koji se štampaju na kraju računa

Prilikom izdavanja konačnog računa ESIR će automatski izdati "Promet/Refundacija" u iznosu svih prethodnih avansnih uplata, a potom "Promet/Prodaja" račun na ukupan iznos računa.

Napomena: izdavanje konačnog računa na ovaj način je moguće samo ukoliko su svi prethodni avansni računi izdati kroz isti ESIR i postoje u internoj bazi računa.

A final invoice is issued by sending the following request to the /api/invoices/final endpoint:

advanceLastInvoiceNumber (string) - number of the last advance invoice
payment (list(object)): array describing the advance payments
- paymentType (string): payment type
- amount (money): advance payment amount

In addition to these fields, the following fields may optionally be specified in the request:

print (boolean) - whether the invoices are printed
email (string) - email address to which the invoices will be sent
printerName (string) - name of the printer to print on, otherwise the configured printer is used
printerType (string) - type of printer to print on, otherwise the configured printer type is used
receiptHeaderImage (string) - Base64-encoded image printed at the beginning of the invoice
receiptFooterImage (string) - Base64-encoded image printed at the end of the invoice
receiptHeaderTextLines (list(string)) - array of texts printed at the beginning of the invoice
receiptFooterTextLines (list(string)) - array of texts printed at the end of the invoice

When issuing a final invoice, ESIR will automatically issue a "Sale/Refund" in the amount of all previous advance payments, and then a "Sale/Normal" invoice for the total amount of the invoice.

Note: issuing a final invoice in this way is only possible if all previous advance invoices were issued through the same ESIR and exist in the internal invoice database.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices/final' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "advanceLastInvoiceNumber": "RX4F7Y5L-RX4F7Y5L-144",
    "payment": [
        {
            "paymentType": "Cash",
            "amount": 500.00
        }
    ]
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "cEk65gB7aXMxU...",
  "invoiceCounter": "103/146ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-146",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-145\r\nРеф. вријеме:     12.03.2024. 07:55:07\r\nЕСИР број:                      13/2.0\r\n----------- ПРОМЕТ ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00      12,000         600,00\r\nArtikl 2 (F)                          \r\n     200,00       2,000         400,00\r\n--------------------------------------\r\nУкупан износ:                 1.000,00\r\nГотовина:                       500,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         99,10\r\n--------------------------------------\r\nУкупан износ пореза:             99,10\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:55:09\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-146\r\nБројач рачуна:               103/146ПП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:55:09.365+01:00",
  "signature": "V7iQh06boDiTfnxagWJc...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 99.0991,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 1000,
  "totalCounter": 146,
  "transactionTypeCounter": 103,
  "verificationQRCode": "R0lGODlhhAGEA...=",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZN..."
}

POST/api/invoices#

Avansni račun (bez automatizma)

Advance invoice (without automation)

U slučaju da prethodni avansni račun nije evidentiran kroz istu ESIR aplikaciju ili postoji neki drugi razlog zbog koga nije moguće koristiti automatizovan način izdavanja avansnih računa opisanog u prethodnim koracima, Avansni račun se izdaje tako što se formiraju ručno prema tehničkoj specifikaciji PURS-a:

Stavke računa (invoiceRequest.items) sadrže razbijenu uplatu po poreskim stopama, gde naziv artikla treba da bude Аванс, količinom 1, jediničnom cenom i ukupnim iznosom koji odgovaraju iznosu koji je uplaćen po toj poreskoj stopi.
Dodaje se polje:
- originalItems (list(object)) - niz pravih stavki računa u istom formatu kao što bi se našle na računu u okviru invoiceRequest.items polja. Ovi podaci će biti odštampani na kraju računa.

In case the previous advance invoice was not recorded through the same ESIR application, or there is some other reason why it is not possible to use the automated method of issuing advance invoices described in the previous steps, the advance invoice is issued by composing it manually according to the PURS technical specification:

The invoice items (invoiceRequest.items) contain the payment broken down by tax rates, where the article name should be Аванс, with quantity 1, and a unit price and total amount corresponding to the amount paid for that tax rate.
The following field is added:
- originalItems (list(object)) - array of the actual invoice items in the same format as they would appear on the invoice within the invoiceRequest.items field. This data will be printed at the end of the invoice.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Advance",
        "transactionType": "Sale",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "WireTransfer"
            }
        ],
        "items": [
            {
                "name": "Аванс",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 100.00,
                "quantity": 1
            }
        ],
        "cashier": "Radnik 1"
    },
    "originalItems": [
        {
            "name": "Artikl 1",
            "gtin": "12345678",
            "labels": [
                "F"
            ],
            "totalAmount": 600.00,
            "unitPrice": 50.00,
            "quantity": 12
        },
        {
            "name": "Artikl 2",
            "gtin": "12345679",
            "labels": [
                "F"
            ],
            "totalAmount": 400.00,
            "unitPrice": 200.00,
            "quantity": 2
        }
    ]
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "wiiZceyCszVa0IJ6...",
  "invoiceCounter": "15/147АП",
  "invoiceCounterExtension": "АП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-147",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n------------ АВАНС ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     100,00       1,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nПренос на рачун:                100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:56:07\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-147\r\nБројач рачуна:                15/147АП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:56:07.043+01:00",
  "signature": "K6weEPCWIj15s8/9YK5...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 147,
  "transactionTypeCounter": 15,
  "verificationQRCode": "R0lGODlhhAGEAfAA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNUyTA..."
}

POST/api/invoices#

Naredni avansni račun (bez automatizma)

Subsequent advance invoice (without automation)

Naredni avansni račun se izdaje kao i pravi avansni račun uz referenciranje na prethodni avansni račun dodavanjem sledećih polja u invoiceRequest objektu:

referentDocumentNumber (string) - broj prethodnog avansnog računa
referentDocumentDT (timestamp) - vreme prethodnog avansnog računa

A subsequent advance invoice is issued the same way as a regular advance invoice, with a reference to the previous advance invoice by adding the following fields to the invoiceRequest object:

referentDocumentNumber (string) - number of the previous advance invoice
referentDocumentDT (timestamp) - time of the previous advance invoice

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Advance",
        "transactionType": "Sale",
        "referentDocumentNumber": "RX4F7Y5L-RX4F7Y5L-147",
        "referentDocumentDT": "2024-03-12T07:56:07.043+01:00",
        "payment": [
            {
                "amount": 400.00,
                "paymentType": "WireTransfer"
            }
        ],
        "items": [
            {
                "name": "Аванс",
                "labels": [
                    "F"
                ],
                "totalAmount": 400.00,
                "unitPrice": 400.00,
                "quantity": 1
            }
        ],
        "cashier": "Radnik 1"
    },
    "originalItems": [
        {
            "name": "Artikl 1",
            "gtin": "12345678",
            "labels": [
                "F"
            ],
            "totalAmount": 600.00,
            "unitPrice": 50.00,
            "quantity": 12
        },
        {
            "name": "Artikl 2",
            "gtin": "12345679",
            "labels": [
                "F"
            ],
            "totalAmount": 400.00,
            "unitPrice": 200.00,
            "quantity": 2
        }
    ]
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "IIgwhqX6UoIOWq/...",
  "invoiceCounter": "16/148АП",
  "invoiceCounterExtension": "АП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-148",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-147\r\nРеф. вријеме:     12.03.2024. 07:56:07\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n------------ АВАНС ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     400,00       1,000         400,00\r\n--------------------------------------\r\nУкупан износ:                   400,00\r\nПренос на рачун:                400,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         39,64\r\n--------------------------------------\r\nУкупан износ пореза:             39,64\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:57:16\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-148\r\nБројач рачуна:                16/148АП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:57:16.884+01:00",
  "signature": "UJEym4NOUEVL2pPCAqK...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 39.6396,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 400,
  "totalCounter": 148,
  "transactionTypeCounter": 16,
  "verificationQRCode": "R0lGODlhhAGEAfAAAA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNUyU..."
}

POST/api/invoices#

Refundacija prethodno izdatih avansnih računa (bez automatizma)

Refund of previously issued advance invoices (without automation)

Pre izdavanja konačnog računa neophodno je refundirati prethodno izdate avansne račune tako što se sumiraju sve prethodno izdate avansne uplate po poreskim stopama u jedan Avans/Refundacija račun koji se referencira na poslednji avansni račun u nizu, sa dodatnim parametrom:

advanceFinal (boolean) - parametar treba da ima vrednost "true" kako bi se adekvatno proknjižio dnevni promet

Before issuing a final invoice, it is necessary to refund the previously issued advance invoices by summing all previously issued advance payments by tax rates into a single Advance/Refund invoice that references the last advance invoice in the sequence, with the additional parameter:

advanceFinal (boolean) - this parameter should have the value "true" so that the daily turnover is properly recorded

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Advance",
        "transactionType": "Refund",
        "referentDocumentNumber": "RX4F7Y5L-RX4F7Y5L-148",
        "referentDocumentDT": "2024-03-12T07:57:16.884+01:00",
        "payment": [
            {
                "amount": 500.00,
                "paymentType": "WireTransfer"
            }
        ],
        "items": [
            {
                "name": "Аванс",
                "labels": [
                    "F"
                ],
                "totalAmount": 500.00,
                "unitPrice": 500.00,
                "quantity": 1
            }
        ],
        "cashier": "Radnik 1"
    },
    "advanceFinal": true
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "NmB+uqF+8Vgzli+q4yek922J9jEz...",
  "invoiceCounter": "4/149АР",
  "invoiceCounterExtension": "АР",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-149",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-148\r\nРеф. вријеме:     12.03.2024. 07:57:16\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n---------- АВАНС РЕФУНДАЦИЈА ---------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     500,00       1,000        -500,00\r\n--------------------------------------\r\nУкупан износ:                   500,00\r\nПренос на рачун:                500,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         49,55\r\n--------------------------------------\r\nУкупан износ пореза:             49,55\r\n======================================\r\nПФР вријеме:      12.03.2024. 07:59:21\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-149\r\nБројач рачуна:                 4/149АР\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T07:59:21.414+01:00",
  "signature": "U8qz5TV2hJCdYm...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 49.5496,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 500,
  "totalCounter": 149,
  "transactionTypeCounter": 4,
  "verificationQRCode": "R0lGODlhhAGEAfAAAA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNUyVAAAABAAAAEBLT..."
}

POST/api/invoices#

Konačni račun (bez automatizma)

Final invoice (without automation)

Na kraju se izdaje konačni račun koji sadrži iznos preostale uplate odnosno iznos uplate koja se vrši u momentu izdavanja konačnog računa, sadrži prave stavke računa, referencira se na prethodno izdat Avans/Refundacija račun i uključuje dodatne informacije:

advanceFinal (boolean) - parametar treba da ima vrednost "true" kako bi se adekvatno proknjižio dnevni promet
advancePaid (money) - iznos koliko je uplaćeno avansno
advanceTax (money) - iznos poreza koji je obračunat na avansne uplate
advanceLastInvoiceNumber (string) - broj poslednje izdatog avansnog računa
advanceLastInvoiceDateTime (timestamp) - vreme izdavanja poslednjeg avansnog računa

At the end, a final invoice is issued, containing the amount of the remaining payment, i.e. the amount of the payment made at the moment the final invoice is issued; it contains the actual invoice items, references the previously issued Advance/Refund invoice, and includes additional information:

advanceFinal (boolean) - the parameter should have the value "true" so that the daily turnover is properly recorded
advancePaid (money) - the amount paid in advance
advanceTax (money) - the amount of tax calculated on the advance payments
advanceLastInvoiceNumber (string) - the number of the last issued advance invoice
advanceLastInvoiceDateTime (timestamp) - the time the last advance invoice was issued

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Normal",
        "transactionType": "Sale",
        "referentDocumentNumber": "RX4F7Y5L-RX4F7Y5L-149",
        "referentDocumentDT": "2024-03-12T07:59:21.414+01:00",
        "payment": [
            {
                "amount": 500.00,
                "paymentType": "Cash"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 600.00,
                "unitPrice": 50.00,
                "quantity": 12
            },
            {
                "name": "Artikl 2",
                "gtin": "12345679",
                "labels": [
                    "F"
                ],
                "totalAmount": 400.00,
                "unitPrice": 200.00,
                "quantity": 2
            }
        ],
        "cashier": "Radnik 1"
    },
    "advanceFinal": true,
    "advancePaid": 500.00,
    "advanceTax": 49.5496,
    "advanceLastInvoiceNumber": "RX4F7Y5L-RX4F7Y5L-148",
    "advanceLastInvoiceDateTime": "2024-03-12T07:57:16.884+01:00"
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "wHfV70g0Xn...",
  "invoiceCounter": "104/150ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-150",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nРеф. број:       RX4F7Y5L-RX4F7Y5L-149\r\nРеф. вријеме:     12.03.2024. 07:59:21\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n----------- ПРОМЕТ ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00      12,000         600,00\r\nArtikl 2 (F)                          \r\n     200,00       2,000         400,00\r\n--------------------------------------\r\nУкупан износ:                 1.000,00\r\nГотовина:                       500,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%         99,10\r\n--------------------------------------\r\nУкупан износ пореза:             99,10\r\n======================================\r\nПФР вријеме:      12.03.2024. 08:03:39\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-150\r\nБројач рачуна:               104/150ПП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T08:03:39.781+01:00",
  "signature": "OKgHMXMUJF4bL9tj0...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 99.0991,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 1000,
  "totalCounter": 150,
  "transactionTypeCounter": 104,
  "verificationQRCode": "R0lGODlhhAGEAf...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNUyWAAAAaAAA..."
}

POST/api/invoices#

Avansni račun za virmanski avans u prethodnom danu

Advance invoice for a wire-transfer advance from the previous day

U slučaju da je avansna uplata evidentirana pre nego što je bilo moguće izdati fiskalni račun neophodno je iskoristiti naredno polje prilikom fiskalizacije takvog avansnog računa:

dateAndTimeOfIssue (timestamp): datum i vreme kada je evidentirana avansna uplata

In case the advance payment was recorded before it was possible to issue a fiscal invoice, the following field must be used when fiscalizing such an advance invoice:

dateAndTimeOfIssue (timestamp): the date and time when the advance payment was recorded

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "invoiceType": "Advance",
        "transactionType": "Sale",
        "dateAndTimeOfIssue": "2024-03-11T15:10:00.000+01:00",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "WireTransfer"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 600.00,
                "unitPrice": 50.00,
                "quantity": 12
            },
            {
                "name": "Artikl 2",
                "gtin": "12345679",
                "labels": [
                    "F"
                ],
                "totalAmount": 400.00,
                "unitPrice": 200.00,
                "quantity": 2
            }
        ],
        "cashier": "Radnik 1"
    },
    "advancePayment": [
        {
            "label": "F",
            "amount": 100.00
        }
    ]
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "Q6p+yZpwsrP0J...",
  "invoiceCounter": "17/151АП",
  "invoiceCounterExtension": "АП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-151",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nЕСИР вријеме:     11.03.2024. 15:10:00\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n------------ АВАНС ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     100,00       1,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nПренос на рачун:                100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 08:05:12\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-151\r\nБројач рачуна:                17/151АП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T08:05:12.753+01:00",
  "signature": "L8WBiaz7HOGrKjm...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 151,
  "transactionTypeCounter": 17,
  "verificationQRCode": "R0lGODlhhA...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNU..."
}

POST/api/invoices#

Izdavanje računa koji će biti odštampan na drugom štampaču

Issuing an invoice that will be printed on another printer

U slučaju da je potrebno račun odštampati na drugom štampaču umesto na OFS P5 EFU integrisanom štampaču potrebno je u zahtevu za izdavanje računa dodati sledeće parametre:

print (boolean) - postaviti na vrednost false - ovaj parametar označava da nije potrebno raditi štampu na internom štampaču
renderReceiptImage (boolean) - postaviti na vrednost true - ovaj parametar označava da je potrebno u rezultatu vretiti izgled računa
receiptLayout (string) - izgled računa u formatu isečka (vrednost Slip) odnosno u A4 formatu (vrednost Invoice)
receiptImageFormat (string) - format slike računa koji će biti generisan, moguće vrednosti: Png i Pdf
receiptSlipWidth (number) - ukoliko je račun u formatu isečka (Slip) onda ovaj parametar označava kolika je širina papira u pikselima (386 za 58mm odnosno 576 za 80mm)
receiptSlipFontSizeNormal (number) - ukoliko je račun u formatu isečka (Slip) onda ovaj parametar označava veličinu slova standardnog teksta na računu (preporučene vrednost 23 za 58mm papir, odnosno 25 za 80mm papir)
receiptSlipFontSizeLarge (number) - ukoliko je račun u formatu isečka (Slip) ond ovaj parametar označava veličinu slova velikog teksta na računu (preporučene vrednost 27 za 58mm papir, odnosno 30 za 80mm papir)

Ukoliko je račun uspešno izdat u rezultatu će se nalaziti sadržaj računa u zahtevanom formatu u polju:

invoiceImagePngBase64 (base64) - base64 kodiran izgled računa u Png formatu
invoiceImagePdfBase64 (base64) - base64 kodiran izgled računa u Pdf formatu

Napomena: način na koji će slika računa biti odštampana zavisi od konkretnog okruženja korisnika i vrste štampača i nije predmet ove dokumentacije.

In case the invoice needs to be printed on a different printer instead of the OFS P5 EFU integrated printer, the following parameters must be added to the invoice issuance request:

print (boolean) - set to the value false - this parameter indicates that printing on the internal printer is not required
renderReceiptImage (boolean) - set to the value true - this parameter indicates that the invoice layout must be returned in the result
receiptLayout (string) - invoice layout in slip format (value Slip) or in A4 format (value Invoice)
receiptImageFormat (string) - the format of the invoice image that will be generated, possible values: Png and Pdf
receiptSlipWidth (number) - if the invoice is in slip format (Slip), then this parameter indicates the paper width in pixels (386 for 58mm or 576 for 80mm)
receiptSlipFontSizeNormal (number) - if the invoice is in slip format (Slip), then this parameter indicates the font size of the standard text on the invoice (recommended value 23 for 58mm paper, or 25 for 80mm paper)
receiptSlipFontSizeLarge (number) - if the invoice is in slip format (Slip), then this parameter indicates the font size of the large text on the invoice (recommended value 27 for 58mm paper, or 30 for 80mm paper)

If the invoice is successfully issued, the result will contain the invoice content in the requested format in the field:

invoiceImagePngBase64 (base64) - base64-encoded invoice layout in Png format
invoiceImagePdfBase64 (base64) - base64-encoded invoice layout in Pdf format

Note: the manner in which the invoice image will be printed depends on the user's specific environment and the type of printer, and is not the subject of this documentation.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'RequestId: 12345' \
  -H 'Content-Type: application/json' \
  -d '{
    "print": false,
    "renderReceiptImage": true,
    "receiptImageFormat": "Png",
    "receiptSlipWidth": 576,
    "receiptSlipFontSizeNormal": 24,
    "receiptSlipFontSizeLarge": 30,
    "invoiceRequest": {
        "invoiceType": "Normal",
        "transactionType": "Sale",
        "payment": [
            {
                "amount": 100.00,
                "paymentType": "Cash"
            }
        ],
        "items": [
            {
                "name": "Artikl 1",
                "gtin": "12345678",
                "labels": [
                    "F"
                ],
                "totalAmount": 100.00,
                "unitPrice": 50.00,
                "quantity": 2.000
            }
        ],
        "cashier": "Radnik 1"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "I3XKC...",
  "invoiceCounter": "222/331ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": "iVBORw0...",
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-331",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n----------- ПРОМЕТ ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nArtikl 1 (F)                          \r\n      50,00       2,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nГотовина:                       100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      14.04.2024. 20:07:16\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-331\r\nБројач рачуна:               222/331ПП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-04-14T20:07:16.184+02:00",
  "signature": "d1JIwH....",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 331,
  "transactionTypeCounter": 222,
  "verificationQRCode": "R0lGODl...",
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0RjdZNUxLAQ..."
}

Pregled računa

Invoice overview

U ovoj sekciji su opisane razne operacije za pregled i pretragu prethodno izdatih računa.

This section describes various operations for viewing and searching previously issued invoices.

GET/api/invoices/:invoiceNumber?receiptLayout=Slip&imageFormat=Png&includeHeaderAndFooter=true#

Pregled sadržaja računa

View invoice content

Namena ovog API poziva je da se preuzme kompletan sadržaj računa uključujući i sliku računa u zadatom formatu.

The purpose of this API call is to retrieve the complete content of an invoice, including the invoice image in the specified format.

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`invoiceNumber`	`RX4F7Y5L-RX4F7Y5L-138`	Fiskalni broj računaFiscal invoice number

Query parametriQuery parameters

ParametarParameter	PrimerExample	OpisDescription
`receiptLayout`	`Slip`	Izgled računa (Slip - fiskalni isečak, Invoice - A4 format), opcioni parametar ukoliko nije naveden koristi se vrednost iz podešavanjaInvoice layout (Slip - fiscal receipt, Invoice - A4 format); optional parameter, if not specified the value from the settings is used
`imageFormat`	`Png`	Slika računa u Png ili Pdf formatu, opcioni parametar ukoliko nije naveden koristi se vrednost iz podešavanjaInvoice image in Png or Pdf format; optional parameter, if not specified the value from the settings is used
`includeHeaderAndFooter`	`true`	Da li slika računa uključuje tekst/sliku u zaglavlju i podnožju računa, opcioni parametar ukoliko nije naveden vrednost je falseWhether the invoice image includes the text/image in the invoice header and footer; optional parameter, if not specified the value is false

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/invoices/RX4F7Y5L-RX4F7Y5L-138?receiptLayout=Slip&imageFormat=Png&includeHeaderAndFooter=true' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "autoGenerated": false,
  "invoiceRequest": {
    "buyerCostCenterId": null,
    "buyerId": null,
    "cashier": "Radnik 1",
    "dateAndTimeOfIssue": null,
    "invoiceNumber": "13/2.0",
    "invoiceType": "Normal",
    "items": [
      {
        "articleUuid": null,
        "discount": null,
        "discountAmount": null,
        "gtin": null,
        "labels": [
          "F"
        ],
        "name": "Artikl 1",
        "plu": null,
        "quantity": 2,
        "totalAmount": 100,
        "unitPrice": 50
      }
    ],
    "options": {
      "omitQRCodeGen": 1,
      "omitTextualRepresentation": null
    },
    "payment": [
      {
        "amount": 100,
        "paymentType": "Cash"
      }
    ],
    "referentDocumentDT": null,
    "referentDocumentNumber": null,
    "transactionType": "Sale"
  },
  "invoiceResponse": {
    "address": "Dunavska 1c",
    "businessName": "Aero Centar Krila  d.o.o.",
    "district": "Banja Luka",
    "encryptedInternalData": null,
    "invoiceCounter": "100/138ПП",
    "invoiceCounterExtension": "ПП",
    "invoiceImageHtml": null,
    "invoiceImagePdfBase64": null,
    "invoiceImagePngBase64": null,
    "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-138",
    "journal": null,
    "locationName": "Aero Centar Krila  d.o.o.",
    "messages": "Успешно",
    "mrc": "01-0001-WPYB002248000772",
    "requestedBy": "RX4F7Y5L",
    "sdcDateTime": "2024-03-12T07:47:09.548+01:00",
    "signature": null,
    "signedBy": "RX4F7Y5L",
    "taxGroupRevision": 2,
    "taxItems": [
      {
        "amount": 9.9099,
        "categoryName": "ECAL",
        "categoryType": 0,
        "label": "F",
        "rate": 11
      }
    ],
    "tin": "4401686560006",
    "totalAmount": 100,
    "totalCounter": 138,
    "transactionTypeCounter": 100,
    "verificationQRCode": "R0lGODlhh...",
    "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WTVMUlg0R..."
  },
  "issueCopy": false,
  "print": true,
  "receiptImageBase64": "iVBORw0KGgoAAAAN...",
  "receiptImageFormat": "Png",
  "receiptLayout": "Slip",
  "renderReceiptImage": false,
  "skipEftPos": false,
  "skipEftPosPrint": false
}

GET/api/invoices/last?receiptLayout=Slip&imageFormat=Png&includeHeaderAndFooter=true#

Pregled sadržaja poslednjeg računa

View content of the last invoice

Namena ovog API poziva je da se preuzme kompletan sadržaj poslednjeg fiskalizovanog računa.

The purpose of this API call is to retrieve the complete content of the last fiscalized invoice.

Query parametriQuery parameters

ParametarParameter	PrimerExample	OpisDescription
`receiptLayout`	`Slip`	Izgled računa (Slip - fiskalni isečak, Invoice - A4 format), opcioni parametar ukoliko nije naveden koristi se vrednost iz podešavanjaInvoice layout (Slip - fiscal receipt, Invoice - A4 format); optional parameter, if not specified the value from the settings is used
`imageFormat`	`Png`	Slika računa u Png ili Pdf formatu, opcioni parametar ukoliko nije naveden koristi se vrednost iz podešavanjaInvoice image in Png or Pdf format; optional parameter, if not specified the value from the settings is used
`includeHeaderAndFooter`	`true`	Da li slika računa uključuje tekst/sliku u zaglavlju i podnožju računa, opcioni parametar ukoliko nije naveden vrednost je falseWhether the invoice image includes the text/image in the invoice header and footer; optional parameter, if not specified the value is false

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/invoices/last?receiptLayout=Slip&imageFormat=Png&includeHeaderAndFooter=true' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "advancePaidByTax": [
    {
      "amount": 100,
      "label": "F"
    }
  ],
  "advancePaidTotalAmount": 100,
  "advancePayment": [
    {
      "amount": 100,
      "label": "F"
    }
  ],
  "advanceRemainingAmount": 900,
  "advanceRemainingByTax": [
    {
      "amount": 900,
      "label": "F"
    }
  ],
  "advanceTaxTotalAmount": 9.9099,
  "autoGenerated": false,
  "invoiceRequest": {
    "buyerCostCenterId": null,
    "buyerId": null,
    "cashier": "Radnik 1",
    "dateAndTimeOfIssue": "2024-03-11T15:10:00.000+01:00",
    "invoiceNumber": "13/2.0",
    "invoiceType": "Advance",
    "items": [
      {
        "articleUuid": null,
        "discount": null,
        "discountAmount": null,
        "gtin": null,
        "labels": [
          "F"
        ],
        "name": "Аванс",
        "plu": null,
        "quantity": 1,
        "totalAmount": 100,
        "unitPrice": 100
      }
    ],
    "options": {
      "omitQRCodeGen": 1,
      "omitTextualRepresentation": null
    },
    "payment": [
      {
        "amount": 100,
        "paymentType": "WireTransfer"
      }
    ],
    "referentDocumentDT": null,
    "referentDocumentNumber": null,
    "transactionType": "Sale"
  },
  "invoiceResponse": {
    "address": "Dunavska 1c",
    "businessName": "Aero Centar Krila  d.o.o.",
    "district": "Banja Luka",
    "encryptedInternalData": null,
    "invoiceCounter": "17/151АП",
    "invoiceCounterExtension": "АП",
    "invoiceImageHtml": null,
    "invoiceImagePdfBase64": null,
    "invoiceImagePngBase64": null,
    "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-151",
    "journal": null,
    "locationName": "Aero Centar Krila  d.o.o.",
    "messages": "Успешно",
    "mrc": "01-0001-WPYB002248000772",
    "requestedBy": "RX4F7Y5L",
    "sdcDateTime": "2024-03-12T08:05:12.753+01:00",
    "signature": null,
    "signedBy": "RX4F7Y5L",
    "taxGroupRevision": 2,
    "taxItems": [
      {
        "amount": 9.9099,
        "categoryName": "ECAL",
        "categoryType": 0,
        "label": "F",
        "rate": 11
      }
    ],
    "tin": "4401686560006",
    "totalAmount": 100,
    "totalCounter": 151,
    "transactionTypeCounter": 17,
    "verificationQRCode": "R0lGODl...",
    "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WT..."
  },
  "issueCopy": false,
  "originalItems": [
    {
      "articleUuid": null,
      "discount": null,
      "discountAmount": null,
      "gtin": null,
      "labels": [
        "F"
      ],
      "name": "Artikl 1",
      "plu": null,
      "quantity": 12,
      "totalAmount": 600,
      "unitPrice": 50
    },
    {
      "articleUuid": null,
      "discount": null,
      "discountAmount": null,
      "gtin": null,
      "labels": [
        "F"
      ],
      "name": "Artikl 2",
      "plu": null,
      "quantity": 2,
      "totalAmount": 400,
      "unitPrice": 200
    }
  ],
  "print": true,
  "receiptImageBase64": "iVBORw0KGgoAAAAN...",
  "receiptImageFormat": "Png",
  "receiptLayout": "Slip",
  "renderReceiptImage": false,
  "skipEftPos": false,
  "skipEftPosPrint": false
}

GET/api/invoices/request/:requestId#

Pregled sadržaja računa po broju zahteva

View invoice content by request number

U situacijama kada se desilo da je poslat zahtev za fiskalizacijom računa ali zbog mrežnih problema ili drugih neočekivanih problema nije dobijen odgovor od ESIR-a neophodno je proveriti da li se desila fiskalizacija ili ne kako bi se izbegle situacija sa dvostrukom fiskalizacijom istog računa.

Prilikom slanja zahteva za fiskalizaciju u HTTP header polju RequestId se može navesti proizvljan jedinstven zahteva na osnovu koga preko ovog poziva se može dobiti odgovor. U slučaju da je fiskalizacija uspela ovaj poziv će vratiti kompletan sadržaj računa, a ako se fiskalizacija nije desila ovaj poziv će vratiti prazan odgovor.

Napomena: Korišćenjem ovog poziva je moguće proveriti poslednjih 100 zahteva.

In situations where a request for invoice fiscalization was sent but, due to network problems or other unexpected issues, no response was received from the ESIR, it is necessary to check whether the fiscalization occurred or not in order to avoid situations involving double fiscalization of the same invoice.

When sending a fiscalization request, an arbitrary unique request identifier can be specified in the RequestId HTTP header field, based on which a response can be obtained through this call. If the fiscalization succeeded, this call will return the complete invoice content, and if the fiscalization did not occur, this call will return an empty response.

Note: Using this call, it is possible to check the last 100 requests.

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`requestId`	`12345`	Broj zahteva iz HTTP polja RequestId prilikom fiskalizacijeRequest number from the RequestId HTTP field during fiscalization

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/invoices/request/12345' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "businessName": "Aero Centar Krila  d.o.o.",
  "district": "Banja Luka",
  "encryptedInternalData": "Q6p+yZpwsr...",
  "invoiceCounter": "17/151АП",
  "invoiceCounterExtension": "АП",
  "invoiceImageHtml": null,
  "invoiceImagePdfBase64": null,
  "invoiceImagePngBase64": null,
  "invoiceNumber": "RX4F7Y5L-RX4F7Y5L-151",
  "journal": "=========== ФИСКАЛНИ РАЧУН ===========\r\n             4401686560006            \r\n       Aero Centar Krila  d.o.o.      \r\n       Aero Centar Krila  d.o.o.      \r\n            Dunavska 1c               \r\n              Banja Luka              \r\nЕСИР вријеме:     11.03.2024. 15:10:00\r\nКасир:                        Radnik 1\r\nЕСИР број:                      13/2.0\r\n------------ АВАНС ПРОДАЈА -----------\r\nАртикли                               \r\n======================================\r\nНазив  Цена        Кол.         Укупно\r\nАванс (F)                             \r\n     100,00       1,000         100,00\r\n--------------------------------------\r\nУкупан износ:                   100,00\r\nПренос на рачун:                100,00\r\n======================================\r\nОзнака    Назив    Стопа         Порез\r\nF          ECAL      11%          9,91\r\n--------------------------------------\r\nУкупан износ пореза:              9,91\r\n======================================\r\nПФР вријеме:      12.03.2024. 08:05:12\r\nПФР бр.рач:      RX4F7Y5L-RX4F7Y5L-151\r\nБројач рачуна:                17/151АП\r\n======================================\r\n======== КРАЈ ФИСКАЛНОГ РАЧУНА =======\r\n",
  "locationName": "Aero Centar Krila  d.o.o.",
  "messages": "Успешно",
  "mrc": "01-0001-WPYB002248000772",
  "requestedBy": "RX4F7Y5L",
  "sdcDateTime": "2024-03-12T08:05:12.753+01:00",
  "signature": "L8WBiaz7HOGrKjmNyjQ/...",
  "signedBy": "RX4F7Y5L",
  "taxGroupRevision": 2,
  "taxItems": [
    {
      "amount": 9.9099,
      "categoryName": "ECAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11
    }
  ],
  "tin": "4401686560006",
  "totalAmount": 100,
  "totalCounter": 151,
  "transactionTypeCounter": 17,
  "verificationQRCode": null,
  "verificationUrl": "https://sandbox.suf.poreskaupravars.org/v/?vl=A1JYNEY3WT..."
}

POST/api/invoices/search#

Pretraga računa

Invoice search

Ovaj API poziv omogućava pretragu baze izdatih računa po raznim kriterijumima koji se mogu kombinovati:

fromDate (date): računi koji su izdati na ovaj dan ili kasnije
toDate (date): računi koji su izdati na ovaj dan ili ranije
amountFrom (money): računi sa ukupnim iznosom istim ili većim od navedenog iznosa
amountTo (money): računi sa ukupnim iznosom istim ili manjim od navedenog iznosa
invoiceTypes (list(string)): računi čiji se tip računa nalazi u zadatom nizu
transactionTypes (list(string)): računi čiji se tip transakcije nalazi u zadatom nizu
paymentTypes (list(string)): računi koji sadrže bar jedan od navedenih tipova plaćanja
referentDocumentNumber (string): računi koji se referenciraju na zadati broj računa
buyerId (string): računi sa navedenim brojem kupca
buyerCostCenterId (string): računi sa navedenim opcionim poljem kupca

Sadržaj je u CSV formatu gde svaki red označava po jedan račun i sadrži sledeće kolone:

invoiceNumber (string): broj računa
invoiceType (string): tip računa
transactionType (string): tip transakcije
sdcDateTime (timestamp): vreme fiskalizacije
totalAmount (money): ukupan iznos računa

This API call allows searching the database of issued invoices by various criteria that can be combined:

fromDate (date): invoices issued on this day or later
toDate (date): invoices issued on this day or earlier
amountFrom (money): invoices with a total amount equal to or greater than the specified amount
amountTo (money): invoices with a total amount equal to or less than the specified amount
invoiceTypes (list(string)): invoices whose invoice type is in the given array
transactionTypes (list(string)): invoices whose transaction type is in the given array
paymentTypes (list(string)): invoices that contain at least one of the specified payment types
referentDocumentNumber (string): invoices that reference the given invoice number
buyerId (string): invoices with the specified buyer ID
buyerCostCenterId (string): invoices with the specified optional buyer field

The content is in CSV format where each row represents one invoice and contains the following columns:

invoiceNumber (string): invoice number
invoiceType (string): invoice type
transactionType (string): transaction type
sdcDateTime (timestamp): fiscalization time
totalAmount (money): total invoice amount

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/invoices/search' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fromDate": "2024-03-01",
    "toDate": "2024-03-31",
    "amountFrom": 10.00,
    "amountTo": 10000.00,
    "invoiceTypes": ["Normal","Advance"],
    "transactionTypes": ["Sale","Refund"],
    "paymentTypes": ["Cash","WireTransfer"]
}'

Primer odgovoraResponse example 200 OK

RX4F7Y5L-RX4F7Y5L-1,Normal,Sale,2024-03-06T17:33:12.582+01:00,10.0000
RX4F7Y5L-RX4F7Y5L-131,Normal,Sale,2024-03-11T20:29:05.329+01:00,10.0000
RX4F7Y5L-RX4F7Y5L-132,Normal,Sale,2024-03-11T20:29:25.422+01:00,15.0000
RX4F7Y5L-RX4F7Y5L-133,Normal,Sale,2024-03-11T23:05:53.608+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-134,Normal,Sale,2024-03-11T23:13:55.829+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-135,Normal,Sale,2024-03-11T23:16:03.098+01:00,300.0000
RX4F7Y5L-RX4F7Y5L-137,Normal,Refund,2024-03-11T23:19:54.853+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-138,Normal,Sale,2024-03-12T07:47:09.548+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-139,Normal,Sale,2024-03-12T07:47:38.530+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-140,Normal,Sale,2024-03-12T07:48:47.626+01:00,300.0000
RX4F7Y5L-RX4F7Y5L-142,Normal,Refund,2024-03-12T07:50:19.735+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-143,Advance,Sale,2024-03-12T07:51:53.207+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-144,Advance,Sale,2024-03-12T07:53:26.177+01:00,400.0000
RX4F7Y5L-RX4F7Y5L-145,Advance,Refund,2024-03-12T07:55:07.582+01:00,500.0000
RX4F7Y5L-RX4F7Y5L-146,Normal,Sale,2024-03-12T07:55:09.365+01:00,1000.0000
RX4F7Y5L-RX4F7Y5L-147,Advance,Sale,2024-03-12T07:56:07.043+01:00,100.0000
RX4F7Y5L-RX4F7Y5L-148,Advance,Sale,2024-03-12T07:57:16.884+01:00,400.0000
RX4F7Y5L-RX4F7Y5L-149,Advance,Refund,2024-03-12T07:59:21.414+01:00,500.0000
RX4F7Y5L-RX4F7Y5L-150,Normal,Sale,2024-03-12T08:03:39.781+01:00,1000.0000
RX4F7Y5L-RX4F7Y5L-151,Advance,Sale,2024-03-12T08:05:12.753+01:00,100.0000

Ostale operacije

Other operations

POST/api/device/print#

Direktna štampa

Direct print

Ovaj API poziv omogućava direktan pristup štampaču. U okviru zahteva se mogu navesti sledeći podaci koji će biti odštampani:

textLines (list(string)): niz tekstova koji će biti odštampani svaki u posebnoj liniji
imagePngBase64 (string): Base64 kodirana PNG slika koja će biti odštampana na štampaču
rawBase64 (string): Base64 kodirane komande koje će biti direktno poslate na štampač (najčešće ESC/POS komande)

This API call allows direct access to the printer. The following data can be specified in the request and will be printed:

textLines (list(string)): an array of texts, each of which will be printed on a separate line
imagePngBase64 (string): a Base64-encoded PNG image that will be printed on the printer
rawBase64 (string): Base64-encoded commands that will be sent directly to the printer (most commonly ESC/POS commands)

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:3566/api/device/print' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "textLines": [
        "Line 1",
        "Line 2",
        "Line 3",
        "Line 4"
    ],
    "imagePngBase64": "iVBORw0KGgoAAAA...",
    "rawBase64": "iVBORw0KGgoAAAA..."
}'

Primer odgovoraResponse example 204 No Content

Prazno telo odgovora.Empty response body.

GET/api/certificate#

Podaci o vlasniku sertifikata

Certificate owner data

Ovaj API poziv će vratiti podatke o vlasniku bezbednosnog elementa (u slučaju kada se koristi LPFR) odnosno sertifikata u fajlu (kada se koristi VPFR).

This API call will return data about the owner of the security element (when using LPFR) or the certificate in a file (when using VPFR).

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:3566/api/certificate' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "address": "Dunavska 1c",
  "city": "Banja Luka",
  "country": "BA",
  "location": "Aero Centar Krila  d.o.o.",
  "name": "Aero Centar Krila  d.o.o.",
  "serialNumber": "RX4F7Y5L",
  "taxCoreApiBaseUri": "https://api.sandbox.suf.poreskaupravars.org",
  "tin": "4401686560006"
}

Spisak izmena po verzijama

Change log by version

U nastavku su pobrojane izmene koje donosi nova verzija. Verziju software-a možete proveriti u samoj aplikaciji na "Info" stranici u sekciji "ESIR".

Verzija 4.0 (25051001-Rel002)

Dodat parametar "advanceFinal" prilikom fiskalizacije konačnog računa bez automatizma (refundacija avansa i izdavanje konačnog računa) kako bi se ispravno proknjižio dnevni promet.

Verzija 4.0 (25041101-Rel002)

Podrška za fiskalizaciju veleprodaji
Opciono polje kupca se uvek prikazuje na računu ukoliko je uneto

Verzija 4.0 (25013001-Rel002)

Mogućnost podešavanja štampanja GTIN-a na računu (opcija "receiptPrintGtin" u /api/settings pozivu)

Verzija 4.0 (24123101-Rel002)

Mogućnost konfigurisanja više različitih štampača
Mogućnost štampe računa sa izgledom prilagođenim A4 formatu (pogledati API / Izdavanje rečuna)
Mogućnost generisanja izgleda računa u Png, Pdf ili Html formatu (pogledati API / Izdavanje računa)
Naziv kasira (polje cashier) je obavezno prilikom fiskalizacije
GTIN artikla (polje gtin) je obavezno prilikom fiskalizacije i mora biti dužine između 8 i 14 znakova
Ukoliko je račun koji se refundira izdat na istom uređaju uradiće se dodatne provere i neće biti dozvoljno da se refundira veći iznos od iznosa računa niti da se refundira račun Refundacije (pogledati API / Izdavanje računa / Refundacija računa)
Usklađeni izveštaji prema zahtevima Poreske Uprave:
- Dnevni i periodični izveštaji sadrže i vreme zadatog perioda
- Promet po artiklima sadrži i avansne prodaje u glavnoj tabeli
Ispravljen defekt zbog koga je bilo neophodno slati dodatni podatak advancePayments prilikom refundacije avansnog računa
Unapređena stabilnost

Below is a list of changes introduced by the new version. You can check the software version in the application itself on the "Info" page in the "ESIR" section.

Version 4.0 (25051001-Rel002)

Added the "advanceFinal" parameter when fiscalizing a final invoice without automation (advance refund and final invoice issuance) so that the daily turnover is booked correctly.

Version 4.0 (25041101-Rel002)

Support for wholesale fiscalization
The optional buyer field is always shown on the invoice if it has been entered

Version 4.0 (25013001-Rel002)

Ability to configure printing the GTIN on the invoice (the "receiptPrintGtin" option in the /api/settings call)

Version 4.0 (24123101-Rel002)

Ability to configure multiple different printers
Ability to print invoices with a layout adapted to A4 format (see API / Invoice issuance)
Ability to generate the invoice layout in Png, Pdf or Html format (see API / Invoice issuance)
The cashier name (field cashier) is mandatory during fiscalization
The article GTIN (field gtin) is mandatory during fiscalization and must be between 8 and 14 characters long
If the invoice being refunded was issued on the same device, additional checks are performed and it will not be allowed to refund an amount greater than the invoice amount, nor to refund a Refund invoice (see API / Invoice issuance / Invoice refund)
Reports aligned with the requirements of the Tax Administration:
- Daily and periodic reports also include the time of the specified period
- Turnover by articles also includes advance sales in the main table
Fixed a defect that made it necessary to send an additional parameter advancePayments when refunding an advance invoice
Improved stability