VG eFiskal — API dokumentacijaAPI documentation

Poslednji put ažurirano: 21.10.2025.

Uvod

Ovaj dokument predstavlja uputstvo za integraciju IT sistema sa VG eFiskal rešenjem putem HTTP REST JSON API interfejsa. Dokument je organizovan tako što su opisane najčešće situacija i pozivi koji se koriste prilikom integracije.

VAŽNO: Za uspešno korišćenje i integraciju pored tehničkog znanja neophodno je i poznavanj relvenatnih propisa u domenu elektronske fiskalizacije.

Instalacija

VG eFiskal API se može instalirati na nekoliko načina:

kao deo standardne VG eFiskal aplikacije (Windows, Linux, Android)
podešavanje VG eFiskal Middleware komponente (Windows, Linux)

U oba slučaja API je identičan i u nastavku su opisani tehnički detalji obe varijante.

Instalacija 1: standardna VG eFiskal aplikacija

Instalacija se obavlja tako što se prvo instalira osnovna VG Start aplikacija, unese serijski broj uređaja i preuzme poslednja verzija VG eFiskal aplikacije nakon čega treba ručno pokrenuti VG eFiskal aplikaciju. Kada se pokrene VG eFiskal aplikacija u pozadini će se takođe pokrenuti i VG eFiskal API. Prednost ovog načina instalacije je što olakšava preuzimanje novih verzija VG eFiskal aplikacije.

U zavisnosti od operativnog sistema folder gde se smeštaju podaci kao i osnovna konfiguracija je:

Windows:
- VG Start aplikacija se pokreće startovanjem C\Program Files\VG Start\bin\vg-start.bat
- VG Start konfiguracioni fajl se nalazi u C\Program Files\VG Start\conf\vg-start.conf.bat
- Folder gde se smeštaju svi podaci: %APPDATA%\VG Start (%APPDATA% je environment varijabla, najčešće pokazuje na folder C:\Users\ImeKorisnika\AppData\Local ili C:\Users\ImeKorisnika\AppData\Roaming). Ovaj folder u nastavku će se zvati DATA folder
- VG eFiskal podaci su smešteni u DATA\data\VG eFiskal folder
- VG eFiskal logovi su smešteni u DATA\log\VG eFiskal folder
Linux:
- Osnovni folder je folder gde je raspakovana VG Start instalacija. Ovaj folder u nastavku će se zvati DATA folder.
- VG Start aplikacija se pokreće startovanje DATA/bin/vg-start.sh
- VG Start konfiguracioni fajl se nalazi u DATA/conf/vg-start.conf
- VG eFiskal podaci su smešteni u DATA/data/vg-efiskal folder
- VG eFiskal logovi su smešteni u DATA/log/vg-efiskal folder
Android:
- VG Start i VG eFiskal aplikacije se instaliraju kao APK i nije moguće direktno pristupati podacima aplikacija osim kroz funkcije same aplikacije.

Rezervna kopija podataka

Rezervna kopija svih podataka se obavlja tako što se zaustave VG eFiskal i VG Start aplikacije (kroz systray ikonice, opcija "Kraj rada") a potom arhivira DATA folder.

Vraćanje podataka se obavlja tako što se prvo instalira VG Start, proveri da nije pokrenut, proveri da DATA folder postoji ali da je prazan a potom backup napravljen na prethodni način se raspakuje u prazan DATA folder (podaci se vrate na isto mesto) nakon čega može da se pokrene VG Start i VG eFiskal.

Napomena: VG eFiskal aplikacija kroz GUI pruža mogućnost za pravljenje rezervne kopije podataka kao i vraćanje podataka iz rezervne kopije na svim platformama (Windows, Linux, Android) i ukoliko je GUI dostupan ovo je poželjan način za pravljenje rezervnih kopija podataka.

Automatsko pokretanje

Automatsko pokretanje VG eFiskal aplikacije prilikom startovanja računara sa Windows operativnom sistemom se može postići tako što ste u Windows-u podesi da se VG Start automatski pokrene (pogledati standardna uputstva za Windows kako se ovo realizuje) a da bi VG Start onda odmah pokrenula VG eFiskal potrebno je u VG Start konfiguracionom (najčešće C\Program Files\VG Start\conf\vg-start.conf.bat)fajlu dodati na kraj red: set TERON_OPTS=-auto-start -start-minimized. Nakon ovoga kada se VG Start pokrene isti će ostati minimizovan (u systray-u) a automatski će startovati VG eFiskal aplikaciju.

Automatsko pokretanje VG eFiskal aplikacije prilikom startovanja računara sa Linux operativnim sistemom se može postići tako što se na Linuxu podesi da se VG Start automatski porekene (pogledati uputstvo za konkretnu Linux distribuciju kako se ovo realizuja) a da bi VG Start onda odmah pokrenula VG eFiskal potrebno je u VG Start konfiguracionom fajlu dodati na kraj red: TERON_OPTS="-auto-start -start-minimized". Nakon ovoga kada se VG Start pokrene isti će ostati minimizovan (u systray-u) a automatski će startovati VG eFiskal aplikaciju.

Automatsko pokretanje VG eFiskal aplikacije na Android uređajima je nakon prve instalacije automatski podešeno tako da vi kao korisnik ne treba ništa dodatno da radite.

Instalacija 2: VG eFiskal Middleware

Na Windows i Linux operativnim sistemima VG eFiskal API se može pokrenuti tako što se instalira samo VG eFiskal Middleware komponenta. Da bi se ovo postiglo neophodno je uraditi sledeće:

Obezbediti da je Java JRE 1.8 instalirana na sistemu
Preuzeti poslednju verziju VG eFiskal Middleware - Java jar bundle (naziv fajla je u formatu vg-efiskal-GGMMDDNN-bundled.jar gde je GG godina, MM mesec, DD dan, NN redni broj)
VG eFiskal Middleware se pokreće sa sledećom komandom: java -Dfile.encoding=UTF-8 -DESIR_SN="12345678" -DESIR_ROOT="root" -DESIR_DATA="data" -DESIR_LOGS="logs" -DESIR_TEMP="temp" -jar vg-efiskal-GGMMDDNN-bundled.jar gde parametre treba podesiti adekvatno:
1. -DESIR_ROOT treba da pokazuje na osnovni folder gde želite da se podaci snimaju
2. -DESIR_DATA treba da pokazuje na folder gde će biti smeštani aplikativni podaci
3. -DESIR_LOGS treba da pokazuje na folder gde će biti smeštani logovi
4. -DESIR_TEMP treba da pokazuje na folder gde će biti smešteni privremeni fajlovi
5. Dodatno proverite da Java koja se pokreće je Java JRE 1.8
6. Dodatno proverite da je vg-efiska-GGMMDDNN-bundled.jar dostupan, najbolje navedite punu putanju do JAR fajla u gornjoj komandi
Podesiti na sistemu automatsko pokretanje VG eFiskal Middleware (izvršenje komande navedene u prethodnom koraku, pogledati uputstvo za operativni sistem kao se ovo radi kao i okruženje u koje integrišete VG eFiskal)

Ažuriranje verzije VG eFiskal Middleware-a

U slučaju da ste odabrali ovu vrstu instalacije neophodno je da sami obezbedite način za ažuriranje VG eFiskal Middleware komponente sa novom verzijom. Postpuak za ažuriranje je sledeći:

Preuzeti novu verziju VG eFiskal Middleware JAR bundle fajla (vg-efiskal-GGMMDDNN-bundled.jar)
Zaustaviti rad VG eFiskal Middleware
Kopirati novi JAR file preko starog
Pokrenuti VG eFiskal Middleware

Rezervna kopija podataka

Rezervna kopija podataka se obavlja tako što se svi podaci iz gore navedenih foldera sačuvaju (osim foldera sa privremenim fajlovima) i vrate na isto mesto po potrebi. Pre pravljenja rezervne kopije podataka neophodno je zaustaviti VG eFiskal Middleware

API

VG eFiskal API se nalazi na adresi: http://hostname:4566/api gde hostname predstavlja DNS ime ili IP adresu uređaja na kome se nalazi VG eFiskal aplikacija. U nastavku dokumentacije u svim primerima hostname je 127.0.0.1 i TCP port je 4566.

HTTP Zahtev

Da bi VG eFiskal obavio autorizaciju i kontrolu pristupa neophodno je da vaš client u zaglavlju svakog zahteva obavezano šalje API-KEY koji Vam je dostavljen za konkretan uređaj (32 znaka, hex string). API-KEY se šalje u okviru HTTP zaglavlja (eng. "HTTP header") u okviru Authorization polja u sledećem formatu:

Authorization: Bearer API-KEY

Pored ovog polja, drugo obavezno polje u slučaju zahteva koji sadrže JSON objekat u telu zahteva (većina POST i PUT zahteva) neophodno je navesti i tip sadržaja dodavanjem u zaglavlje HTTP zahteva:

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

U slučaju integracije na VG eFiskal Cloud svaki HTTP zahtev treba da sadrži i serijski broj uređaja u zaglavlju (HTTP header-u):

X-Teron-SerialNumber: YYY (YYY treba zameniti sa dodeljenim serijski brojem)

HTTP Odgovor

U slučaju uspešno obređanog zahteva odgovor će imati HTTP status kod:

HTTP 200 OK - uspešno obrađen zahtev, u telu odgovora su dodatne informacije u JSON formatu (Content-type: application/json; charset=UTF-8)
HTTP 204 No Content - uspešno obrađen zahtev, nema dodatnih podataka u telu odgovora (prazno telo odgovora)

U slučaju greške odgovor će imati HTTP 4xx ili HTTP 5xx status kod dok će telo poruke sadržati detalje greške u JSON objektu u poljima:

statusCode - kod greške
message - tekstualna reprezentacija greške
details - dodatne informacije o grešci

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
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)
tax-rate - oznaka poreske stope:
- VAT_21, VAT_7, VAT_0 - standardno oporezivanje
- VAT_NO - prodavac nije u PDV-u
- VAT_CL17, VAT_CL20, VAT_CL26, VAT_CL27, VAT_CL28, VAT_CL29, VAT_CL30, VAT_CL44 - oslobođeno oporezivanja

Last updated: 21.10.2025.

Introduction

This document is a guide for integrating IT systems with the VG eFiskal solution via the HTTP REST JSON API interface. The document is organized by describing the most common situations and calls used during integration.

IMPORTANT: For successful use and integration, in addition to technical knowledge, familiarity with the relevant regulations in the area of electronic fiscalization is also required.

Installation

The VG eFiskal API can be installed in several ways:

as part of the standard VG eFiskal application (Windows, Linux, Android)
by configuring the VG eFiskal Middleware component (Windows, Linux)

In both cases the API is identical, and the technical details of both variants are described below.

Installation 1: standard VG eFiskal application

Installation is carried out by first installing the base VG Start application, entering the device serial number, and downloading the latest version of the VG eFiskal application, after which the VG eFiskal application must be started manually. When the VG eFiskal application is started, the VG eFiskal API will also be started in the background. The advantage of this installation method is that it simplifies downloading new versions of the VG eFiskal application.

Depending on the operating system, the folder where data is stored as well as the basic configuration is:

Windows:
- The VG Start application is started by running C\Program Files\VG Start\bin\vg-start.bat
- The VG Start configuration file is located at C\Program Files\VG Start\conf\vg-start.conf.bat
- The folder where all data is stored: %APPDATA%\VG Start (%APPDATA% is an environment variable, most often pointing to the folder C:\Users\UserName\AppData\Local or C:\Users\UserName\AppData\Roaming). This folder will be referred to below as the DATA folder
- VG eFiskal data is stored in the DATA\data\VG eFiskal folder
- VG eFiskal logs are stored in the DATA\log\VG eFiskal folder
Linux:
- The base folder is the folder where the VG Start installation was extracted. This folder will be referred to below as the DATA folder.
- The VG Start application is started by running DATA/bin/vg-start.sh
- The VG Start configuration file is located at DATA/conf/vg-start.conf
- VG eFiskal data is stored in the DATA/data/vg-efiskal folder
- VG eFiskal logs are stored in the DATA/log/vg-efiskal folder
Android:
- The VG Start and VG eFiskal applications are installed as APKs, and it is not possible to access the application data directly except through the functions of the application itself.

Data backup

A backup of all data is performed by stopping the VG eFiskal and VG Start applications (through the systray icons, the "End work" option) and then archiving the DATA folder.

Data restoration is performed by first installing VG Start, verifying that it is not running, verifying that the DATA folder exists but is empty, and then extracting the backup made in the previous way into the empty DATA folder (the data is restored to the same location), after which VG Start and VG eFiskal can be started.

Note: The VG eFiskal application provides, through its GUI, the ability to create a data backup as well as restore data from a backup on all platforms (Windows, Linux, Android), and if the GUI is available this is the preferred way to create data backups.

Automatic startup

Automatic startup of the VG eFiskal application when a computer with a Windows operating system boots can be achieved by configuring Windows to start VG Start automatically (see the standard Windows instructions on how this is done), and so that VG Start then immediately starts VG eFiskal, you need to add the following line at the end of the VG Start configuration file (most often C\Program Files\VG Start\conf\vg-start.conf.bat): set TERON_OPTS=-auto-start -start-minimized. After this, when VG Start is started it will remain minimized (in the systray) and will automatically start the VG eFiskal application.

Automatic startup of the VG eFiskal application when a computer with a Linux operating system boots can be achieved by configuring Linux to start VG Start automatically (see the instructions for the specific Linux distribution on how this is done), and so that VG Start then immediately starts VG eFiskal, you need to add the following line at the end of the VG Start configuration file: TERON_OPTS="-auto-start -start-minimized". After this, when VG Start is started it will remain minimized (in the systray) and will automatically start the VG eFiskal application.

Automatic startup of the VG eFiskal application on Android devices is configured automatically after the first installation, so you as a user do not need to do anything additional.

Installation 2: VG eFiskal Middleware

On Windows and Linux operating systems, the VG eFiskal API can be run by installing only the VG eFiskal Middleware component. To achieve this, you need to do the following:

Ensure that Java JRE 1.8 is installed on the system
Download the latest version of the VG eFiskal Middleware - Java jar bundle (the file name is in the format vg-efiskal-GGMMDDNN-bundled.jar where GG is the year, MM the month, DD the day, NN the sequence number)
VG eFiskal Middleware is started with the following command: java -Dfile.encoding=UTF-8 -DESIR_SN="12345678" -DESIR_ROOT="root" -DESIR_DATA="data" -DESIR_LOGS="logs" -DESIR_TEMP="temp" -jar vg-efiskal-GGMMDDNN-bundled.jar where the parameters should be set appropriately:
1. -DESIR_ROOT should point to the base folder where you want the data to be saved
2. -DESIR_DATA should point to the folder where the application data will be stored
3. -DESIR_LOGS should point to the folder where the logs will be stored
4. -DESIR_TEMP should point to the folder where temporary files will be stored
5. Additionally, verify that the Java being run is Java JRE 1.8
6. Additionally, verify that vg-efiska-GGMMDDNN-bundled.jar is available; it is best to specify the full path to the JAR file in the command above
Configure the system to start VG eFiskal Middleware automatically (execution of the command specified in the previous step; see the instructions for your operating system on how this is done, as well as the environment into which you are integrating VG eFiskal)

Updating the VG eFiskal Middleware version

If you have chosen this type of installation, you must provide your own way of updating the VG eFiskal Middleware component with a new version. The update procedure is as follows:

Download the new version of the VG eFiskal Middleware JAR bundle file (vg-efiskal-GGMMDDNN-bundled.jar)
Stop the VG eFiskal Middleware
Copy the new JAR file over the old one
Start the VG eFiskal Middleware

Data backup

A data backup is performed by saving all the data from the folders listed above (except the folder with temporary files) and restoring it to the same location as needed. Before creating a data backup, you must stop the VG eFiskal Middleware

API

The VG eFiskal API is located at: http://hostname:4566/api where hostname is the DNS name or IP address of the device on which the VG eFiskal application is located. In the rest of the documentation, in all examples, the hostname is 127.0.0.1 and the TCP port is 4566.

HTTP Request

For VG eFiskal to perform authorization and access control, your client must, in the header of every request, mandatorily send the API-KEY that was provided to you for the specific device (32 characters, hex string). The API-KEY is sent within the HTTP header in the Authorization field in the following format:

Authorization: Bearer API-KEY

In addition to this field, the other mandatory field in the case of requests that contain a JSON object in the request body (most POST and PUT requests) is the content type, which must be specified by adding it to the HTTP request header:

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

In the case of integration with the VG eFiskal Cloud, every HTTP request must also contain the device serial number in the header (HTTP header):

X-Teron-SerialNumber: YYY (YYY should be replaced with the assigned serial number)

HTTP Response

In the case of a successfully processed request, the response will have the HTTP status code:

HTTP 200 OK - the request was processed successfully; the response body contains additional information in JSON format (Content-type: application/json; charset=UTF-8)
HTTP 204 No Content - the request was processed successfully; there is no additional data in the response body (empty response body)

In the case of an error, the response will have an HTTP 4xx or HTTP 5xx status code, while the message body will contain the error details in a JSON object in the fields:

statusCode - error code
message - textual representation of the error
details - additional information about the error

Data types

In the rest of the documentation, everywhere 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 decimal places
quantity - decimal number with three decimal places
percent - decimal number with two decimal places
timestamp - date and time in ISO 8601 format with time zone (example: 2023-11-15T13:31:50.000+01:00)
uuid - UUID v4
object - a JSON object containing a set of attributes and values
list(x) - a JSON array containing a set of elements of type x (where X can be any of the listed types)
tax-rate - tax-rate code:
- VAT_21, VAT_7, VAT_0 - standard taxation
- VAT_NO - the seller is not VAT-registered
- VAT_CL17, VAT_CL20, VAT_CL26, VAT_CL27, VAT_CL28, VAT_CL29, VAT_CL30, VAT_CL44 - exempt from taxation

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:4566`	Bazni URL VG eFiskal API-ja. Lokalno je to `http://127.0.0.1:4566` (TCP port 4566); putanje počinju sa `/api/…`.Base URL of the VG eFiskal API. Locally it is `http://127.0.0.1:4566` (TCP port 4566); 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 VG eFiskal Cloud svaki zahtev mora sadržati i zaglavlje X-Teron-SerialNumber: <serijski_broj>.When integrating with VG eFiskal 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]).

Instalacija

Installation

VG eFiskal (Windows)

Instalacija kompletnog VG eFiskal rešenja u okviru jedne aplikacije se obavlja tako što se prvo preuzme i instalira VG Start instalacioni fajl vg-start-YYMMDDNN-win-x64.exe.

Pokretanje

VG Start se može pokrenitu startovanjem C:\Program Files\VG Start\bin\vg-start.batili preko VG Start prečice koja je kreirana tokom instalacije. Automatsko pokretanje VG Start-a zavisi od konkretnog okruženja i potreba korisnika i nije predmet ove dokumentacije, konsultujte dokumentaciju za operativni sistem koji koristite.

Prvi put nakon pokretanja VG Start-a biće neophodno da unesete vaš serijski broj nakon čega se možete automatski preuzeti i instalirati poslednju VG eFiskal klikom na jedno dugme a potom ga i pokrenuti.

NAPOMENA: korišćenje istog serijskog broja na dva ili više uređaja nije dozvoljeno i dovodi do toga da VG eFiskal prestane da radi.

Ažuriranje

Ažuriranje VG eFiskal aplikacije se obavlja startovanjem VG Start aplikacije i ukoliko je nova verzija dostupna pojaviće se dugme za preuzimanje i instalaciju iste. Neophodno je prvo zaustaviti VG eFiskal a potom klikom na dugme pokrenuti ažuriranje nakon čega se može ponovo pokrenuti VG eFiskal.

Ažuriranje VG Start aplikacije

Ažuriranje VG Start aplikacije sa novom verzijom se obavlja tako što se preuzme instalacioni fajl sa novom verzijom, zaustavi VG Start i VG eFiskal, obavi standardna instalacija pokretanjem instalacionog fajla i ponovo pokrene VG Start. U većini slučajeva neće biti potrebno ažurirati VG Start aplikaciju nakon inicijalne instalacije.

Rezervna kopija podataka

Pravljenje rezervne kopije podataka (backup) se obavlja tako što se prvo zaustavi VG eFiskal, a potom kompletan sadržaj foldera %APPDATA%\VG Start\data\VG eFiskalse kopira/arhivira i ponovo pokrene VG eFiskal. Vraćanje podataka iz rezervne kopije (restore) se obavlja tako što se prvo instalira VG Start na računaru na koji želite da presente podatke, potom vratite arhivirane podatke u %APPDATA%\VG Start\data\VG eFiskal folder (ukoliko postoji ovaj folder na novom računaru neophodno ga je prvo očistiti a potom vratiti podatke iz arhive), preuzmite i instalirajte VG eFiskal preko VG Start aplikacije i pokrenete.

Log datoteke

Log datoteke sa detaljnijim informacijama o radu aplikacije se nalaze u %APPDATA%\VG Start\log\VG eFiskal folderu. Naziv svake datoteke sadrži nivo informacija (debug, info ili error) kao i datum u formatu YYMMDDi ekstenziju log. Log fajlovi error sadrže samo greške u radu, info log fajlovi sadrže greške i glavne informacije dok debug log fajlovi sadrže error, info kao i sve ostale informacije. U slučaju problema u radu neophodno je konsultovati log fajlove za više informacija koje najčešće mogu pomoći u otklanjanju problema. Log fajlovi se automatski brišu (debug nakon 7 dana, info nakon 15 dana, error nakon 30 dana). U slučaju da je potrebno osloboditi prostor na disku log fajlovi se mogu obrisati ručno što ne utiče na rad sistema i nije neophodno zaustavljati rad aplikacije tokom brisanja.

Privremene datoteke

Privremene datoteke se nalaze u %APPDATA%\VG Start\temp folderu. Većina privremenih datoteka će biti automatski uklonjena kad više nisu potrebne. U posebnim situacijama se može desiti da privremene datoteke ne budu uklonjene što ne utiče na rad sistema. U slučaju da je potrebno osloboditi prostor na disku privremene datoteke starije od 1h se mogu obrisati ručno što ne utiče na rad sistema i nije neophodno zaustavljati rad aplikacije tokom brisanja.

Deinstalacija

Deinstalacija VG eFiskal i VG Start aplikcija se vrši tako što se prvo zaustavi VG eFiskal i VG Start a potom pokrene C:\Program Files\VG Start\VG Start Deinstalacija.exefajl a potom obriše %APPDATA%\VG Start\apps\rs.teron.esir.android. Nakon završene deinstalacije ukoliko nisu potrebni podaci može se obrisati i kompletan %APPDATA%\VG Start folder. Ova akcija će obrisati i sve VG eFiskal podatke, napravite rezervnu kopiju pre deinstalacije ukoliko je potrebno.

Installation of the complete VG eFiskal solution within a single application is performed by first downloading and installing the VG Start installation file vg-start-YYMMDDNN-win-x64.exe.

Startup

VG Start can be started by launching C:\Program Files\VG Start\bin\vg-start.bat or via the VG Start shortcut created during installation. Automatic startup of VG Start depends on the specific environment and the user's needs and is not covered by this documentation; consult the documentation for the operating system you are using.

The first time after starting VG Start, you will need to enter your serial number, after which you can automatically download and install the latest VG eFiskal with a single click of a button and then start it.

NOTE: using the same serial number on two or more devices is not allowed and causes VG eFiskal to stop working.

Update

Updating the VG eFiskal application is performed by launching the VG Start application, and if a new version is available, a button to download and install it will appear. You must first stop VG eFiskal and then start the update by clicking the button, after which you can start VG eFiskal again.

Updating the VG Start application

Updating the VG Start application to a new version is performed by downloading the installation file with the new version, stopping VG Start and VG eFiskal, performing a standard installation by running the installation file, and starting VG Start again. In most cases, it will not be necessary to update the VG Start application after the initial installation.

Data backup

Creating a data backup is performed by first stopping VG eFiskal, then copying/archiving the entire contents of the %APPDATA%\VG Start\data\VG eFiskal folder, and starting VG eFiskal again. Restoring data from a backup (restore) is performed by first installing VG Start on the computer to which you want to transfer the data, then restoring the archived data to the %APPDATA%\VG Start\data\VG eFiskal folder (if this folder exists on the new computer, it must first be cleared and then the data restored from the archive), downloading and installing VG eFiskal via the VG Start application, and starting it.

Log files

Log files with more detailed information about the application's operation are located in the %APPDATA%\VG Start\log\VG eFiskal folder. The name of each file contains the information level (debug, info, or error), as well as the date in YYMMDD format and the log extension. error log files contain only operating errors, info log files contain errors and main information, while debug log files contain error, info, and all other information. In case of operating problems, it is necessary to consult the log files for more information, which can most often help in resolving the problem. Log files are automatically deleted (debug after 7 days, info after 15 days, error after 30 days). If it is necessary to free up disk space, log files can be deleted manually, which does not affect the operation of the system, and it is not necessary to stop the application during deletion.

Temporary files

Temporary files are located in the %APPDATA%\VG Start\temp folder. Most temporary files will be automatically removed when they are no longer needed. In special situations, it may happen that temporary files are not removed, which does not affect the operation of the system. If it is necessary to free up disk space, temporary files older than 1h can be deleted manually, which does not affect the operation of the system, and it is not necessary to stop the application during deletion.

Uninstallation

Uninstallation of the VG eFiskal and VG Start applications is performed by first stopping VG eFiskal and VG Start, then running the C:\Program Files\VG Start\VG Start Deinstalacija.exe file, and then deleting %APPDATA%\VG Start\apps\rs.teron.esir.android. After the uninstallation is complete, if the data is not needed, the entire %APPDATA%\VG Start folder can also be deleted. This action will also delete all VG eFiskal data; make a backup before uninstallation if necessary.

VG eFiskal (Linux)

Instalacija kompletnog VG eFiskal rešenja u okviru jedne aplikacije se obavlja tako što se prvo preuzme i raspakuje na željeno mesto VG Start fajl vg-start-YYMMDDNN-linux-x64.tar.gz, u nastavku ćemo koristiti prepostavku da je fajl raspakovan u /usr/local folder.

Pokretanje

VG Start se može pokrenitu startovanjem /usr/local/bin/vg-start-1.0/bin/vg-start.sh. Automatsko pokretanje VG Start-a zavisi od konkretnog okruženja i potreba korisnika i nije predmet ove dokumentacije, konsultujte dokumentaciju za operativni sistem koji koristite.

Prvi put nakon pokretanja VG Start-a biće neophodno da unesete vaš serijski broj nakon čega se možete automatski preuzeti i instalirati poslednju verziju VG eFiskal klikom na jedno dugme a potom ga i pokrenuti.

NAPOMENA: korišćenje istog serijskog broja na dva ili više uređaja nije dozvoljeno i dovodi do toga da VG eFiskal prestane da radi.

Ažuriranje

Ažuriranje VG Start aplikacije

Ažuriranje VG Start aplikacije sa novom verzijom se obavlja tako što se preuzme instalacioni fajl sa novom verzijom, zaustavi VG Start i VG eFiskal, obavi raspakivanje arhive na isto mesto kao što je opisano a početku a potom ponovo pokrene VG Start. U većini slučajeva neće biti potrebno ažurirati VG Start aplikaciju nakon inicijalne instalacije.

Rezervna kopija podataka

Pravljenje rezervne kopije podataka (backup) se obavlja tako što se prvo zaustavi VG eFiskal, a potom kompletan sadržaj foldera /usr/local/vg-start-1.0/data/vg-efiskalse kopira/arhivira i ponovo pokrene VG eFiskal. Vraćanje podataka iz rezervne kopije (restore) se obavlja tako što se prvo instalira VG Start na računaru na koji želite da presente podatke, potom vratite arhivirane podatke u /usr/local/vg-start-1.0/data/vg-efiskal folder (ukoliko postoji ovaj folder na novom računaru neophodno ga je prvo očistiti a potom vratiti podatke iz arhive), preuzmite i instalirajte VG eFiskal preko VG Start aplikacije i pokrenete.

Log datoteke

Log datoteke sa detaljnijim informacijama o radu aplikacije se nalaze u /usr/local/vg-start-1.0/log/vg-efiskal folderu. Naziv svake datoteke sadrži nivo informacija (debug, info ili error) kao i datum u formatu YYMMDDi ekstenziju log. Log fajlovi error sadrže samo greške u radu, info log fajlovi sadrže greške i glavne informacije dok debug log fajlovi sadrže error, info kao i sve ostale informacije. U slučaju problema u radu neophodno je konsultovati log fajlove za više informacija koje najčešće mogu pomoći u otklanjanju problema. Log fajlovi se automatski brišu (debug nakon 7 dana, info nakon 15 dana, error nakon 30 dana). U slučaju da je potrebno osloboditi prostor na disku log fajlovi se mogu obrisati ručno što ne utiče na rad sistema i nije neophodno zaustavljati rad aplikacije tokom brisanja.

Privremene datoteke

Privremene datoteke se nalaze u /usr/local/vg-start-1.0/temp folderu. Većina privremenih datoteka će biti automatski uklonjena kad više nisu potrebne. U posebnim situacijama se može desiti da privremene datoteke ne budu uklonjene što ne utiče na rad sistema. U slučaju da je potrebno osloboditi prostor na disku privremene datoteke starije od 1h se mogu obrisati ručno što ne utiče na rad sistema i nije neophodno zaustavljati rad aplikacije tokom brisanja.

Deinstalacija

Deinstalacija VG eFiskal i VG Start aplikcija se vrši tako što se prvo zaustavi VG eFiskal i VG Start a potom a potom obriše /usr/local/vg-start-1.0/apps/rs.teron.esir.android. Nakon završene deinstalacije ukoliko nisu potrebni podaci može se obrisati i kompletan /usr/local/vg-start-1.0 folder. Ova akcija će obrisati i sve VG eFiskal podatke, napravite rezervnu kopiju pre deinstalacije ukoliko je potrebno.

Installation of the complete VG eFiskal solution within a single application is performed by first downloading and extracting the VG Start file vg-start-YYMMDDNN-linux-x64.tar.gz to the desired location. In the following, we will assume that the file has been extracted into the /usr/local folder.

Startup

VG Start can be started by running /usr/local/bin/vg-start-1.0/bin/vg-start.sh. Automatic startup of VG Start depends on the specific environment and the user's needs and is not covered by this documentation; consult the documentation for the operating system you are using.

The first time after starting VG Start, you will need to enter your serial number, after which you can automatically download and install the latest version of VG eFiskal with a single button click and then run it.

NOTE: using the same serial number on two or more devices is not allowed and will cause VG eFiskal to stop working.

Update

Updating the VG eFiskal application is performed by starting the VG Start application, and if a new version is available, a button to download and install it will appear. You must first stop VG eFiskal and then start the update by clicking the button, after which VG eFiskal can be started again.

Updating the VG Start application

Updating the VG Start application to a new version is performed by downloading the installation file with the new version, stopping VG Start and VG eFiskal, extracting the archive to the same location as described at the beginning, and then starting VG Start again. In most cases, it will not be necessary to update the VG Start application after the initial installation.

Data backup

Creating a data backup is performed by first stopping VG eFiskal, then copying/archiving the entire contents of the /usr/local/vg-start-1.0/data/vg-efiskal folder, and starting VG eFiskal again. Restoring data from a backup is performed by first installing VG Start on the computer to which you want to transfer the data, then restoring the archived data into the /usr/local/vg-start-1.0/data/vg-efiskal folder (if this folder exists on the new computer, you must first clear it and then restore the data from the archive), downloading and installing VG eFiskal via the VG Start application, and starting it.

Log files

Log files with more detailed information about the application's operation are located in the /usr/local/vg-start-1.0/log/vg-efiskal folder. The name of each file contains the information level (debug, info, or error), as well as the date in the format YYMMDD and the log extension. The error log files contain only operational errors, the info log files contain errors and main information, while the debug log files contain error, info, and all other information. In case of operational problems, you should consult the log files for more information, which can most often help in resolving the problem. Log files are automatically deleted (debug after 7 days, info after 15 days, error after 30 days). If you need to free up disk space, the log files can be deleted manually, which does not affect the operation of the system, and it is not necessary to stop the application while deleting them.

Temporary files

Temporary files are located in the /usr/local/vg-start-1.0/temp folder. Most temporary files will be automatically removed when they are no longer needed. In special situations, it may happen that temporary files are not removed, which does not affect the operation of the system. If you need to free up disk space, temporary files older than 1h can be deleted manually, which does not affect the operation of the system, and it is not necessary to stop the application while deleting them.

Uninstallation

Uninstallation of the VG eFiskal and VG Start applications is performed by first stopping VG eFiskal and VG Start and then deleting /usr/local/vg-start-1.0/apps/rs.teron.esir.android. After the uninstallation is complete, if the data is no longer needed, the entire /usr/local/vg-start-1.0 folder can also be deleted. This action will also delete all VG eFiskal data; make a backup before uninstallation if needed.

VG eFiskal (Android)

Instalacija kompletnog VG eFiskal rešenja u okviru jedne aplikacije sa obavlja tako što se prvo preuzme i instalira VG Start APK fajl vg-start-YYMMDDNN-android-generic.apk.

Pokretanje

Pokrenite VG Start aplikacije i na ekranu će biti prikazan serijski broj uređaja koji je potrebno da bude registrovan i licenciran na VG eFiskal serveru. Kada je uređaj ispravno licenciran pojaviće se dugme za preuzimanje poslednje verzije VG eFiskal aplikacije a potom i instalacija. Prvi put nakon instalacije VG Start aplikacije će biti neophodno da dozvolite VG Start aplikaciji da instalira druge aplikacije. Po uspešno okončanom postupku instalacije možete pokrenuti VG eFiskal pritiskom na dugme, dok svaki naredni put VG eFiskal će se automatski sam pokrenuti pri startovanju uređaja što će biti indikovano odgovarajućom ikonicom u notifikacijama.

Ažuriranje

Kada postane dostupna nova verzija VG eFiskal aplikacije pokrenite ponovo VG Start aplikaciju i pojaviće se dugme za preuzimanje i instalaciju nove verzije. Na isti način se realizuje i ažuriranje same VG Start aplikacije sa novom verzijom.

Rezervna kopija podataka

Pravljenje rezervne kopije podataka se obavlja kroz samu VG eFiskal aplikaciju, u okviru sekcije "Podešavanja / Rezervna kopija podataka". Pogledajte korisničko uputstvo na doc.fiskalizacija.me za više informacija.

Deinstalacija

Deinstalacija VG eFiskal aplikacije kao i VG Start aplikacije se obavlja na isti način kao i za sve druge Android aplikacije. Deinstalacija VG eFiskal akcije će obrisati i sve VG eFiskal podatke, napravite rezervnu kopiju pre deinstalacije ukoliko je potrebno.

Installation of the complete VG eFiskal solution within a single application is performed by first downloading and installing the VG Start APK file vg-start-YYMMDDNN-android-generic.apk.

Startup

Launch the VG Start application, and the screen will display the device serial number, which must be registered and licensed on the VG eFiskal server. Once the device is correctly licensed, a button will appear to download the latest version of the VG eFiskal application, followed by its installation. The first time after installing the VG Start application, you will need to allow the VG Start application to install other applications. Once the installation process has completed successfully, you can launch VG eFiskal by pressing the button, while every subsequent time VG eFiskal will start automatically when the device boots up, which will be indicated by the corresponding icon in the notifications.

Update

When a new version of the VG eFiskal application becomes available, launch the VG Start application again and a button will appear to download and install the new version. The VG Start application itself is updated to a new version in the same manner.

Data Backup

Creating a data backup is performed through the VG eFiskal application itself, within the "Settings / Data Backup" section. See the user manual at doc.fiskalizacija.me for more information.

Uninstallation

Uninstalling the VG eFiskal application as well as the VG Start application is performed in the same way as for any other Android application. Uninstalling VG eFiskal will also delete all VG eFiskal data; create a backup before uninstalling if needed.

VG eFiskal Middleware (Java JAR bundle)

VG eFiskal Middleware Java JAR bundle je dostupan u slučajevima gde želite da dublje integrišete VG eFiskal u okviru vašeg rešenja. Preuzmite Java JAR bundle file vg-efiskal-YYMMDDNN-bundled.jar i pokrenite ga lokalno sa Java JRE 1.8 verzijom (testirano sa OpenJDK JRE 1.8.0_312-b07):

java -DESIR_ROOT="VAR_POS_ROOT" -DESIR_DATA="VAR_POS_DATA" -DESIR_LOGS="VAR_POS_LOGS" -DESIR_TEMP="VAR_POS_TEMP" -DESIR_SN="VAR_POS_SN" -jar vg-efiskal-YYMMDDNN-bundled.jar

Gde sledeće promenljive sa VAR prefiskom zamenite sa odgovarajućim vrednostima:

VAR_POS_ROOT - putanja do osnovnog VG eFiskal foldera
VAR_POS_DATA - putanja do foldera gde će biti smešteni podaci
VAR_POS_LOGS - putanja do foldera gde će biti smešteni log fajlovi
VAR_POS_TEMP - putanja do foldera gde će biti smešteni privremeni fajlovi
VAR_POS_SN - serijski broj koji vam je dodeljen za svaku instalaciju pojedinačno

U nastavku će se koristiti primeri gde navedene promenljive imaju sleće vrednosti:

VAR_POS_ROOT ima vrednost /usr/local/vg-efiskal
VAR_POS_DATA ima vrednost /usr/local/vg-efiskal/data
VAR_POS_LOGS ima vrednost /usr/local/vg-efiskal/log
VAR_POS_TEMP ima vrednost /usr/local/vg-efiskal/temp

NAPOMENA: korišćenje istog serijskog broja na dva ili više uređaja nije dozvoljeno i dovodi do toga da VG eFiskal prestane da radi.

Ažuriranje

Ažuriranje VG eFiskal Java JAR bundle-a sa novom verzijom se obavlja tako što se preuzme fajl sa novom verzijom, zaustavi VG eFiskal, preuzeti fajl se prekopira preko starog i ponovo pokrene VG eFiskal. Preporuka je da se pre ažuriranja napravi rezervna kopija podataka za sluča da je neophodno vratiti se na staru verziju.

Rezervna kopija podataka

Pravljenje rezervne kopije podataka (backup) se obavlja tako što se prvo zaustavi VG eFiskal, a potom kompletan sadržan foldera /usr/local/vg-efiskal/datase kopira/arhivira a potom se može ponovo pokrenuti VG eFiskal. Vraćanje podataka iz rezervne kopije (restore) se obavlja tako što se prvo instalira VG eFiskal na računaru na koji želite da presente podatke, potom vratite arhivirane podatke u /usr/local/vg-efiskal/data folder (ukoliko postoji ovaj folder na novom računaru neophodno ga je prvo očistiti a potom vratiti podatke iz arhive) a potom se može pokrenuti VG eFiskal.

Log datoteke

Log datoteke sa detaljnijim informacijama o radu aplikacije se nalaze u /usr/local/vg-efiskal/log folderu. Naziv svake datoteke sadrži nivo informacija (debug, info ili error) kao i datum u formatu YYMMDDi ekstenziju log. Log fajlovi error sadrže samo greške u radu, info log fajlovi sadrže greške i glavne informacije dok debug log fajlovi sadrže error, info kao i sve ostale informacije. U slučaju problema u radu neophodno je konsultovati log fajlove za više informacija koje najčešće mogu pomoći u otklanjanju problema. Log fajlovi se automatski brišu (debug nakon 7 dana, info nakon 15 dana, error nakon 30 dana). U slučaju da je potrebno osloboditi prostor na disku log fajlovi se mogu obrisati ručno što ne utiče na rad sistema i nije neophodno zaustavljati rad aplikacije tokom brisanja.

Privremene datoteke

Privremene datoteke se nalaze u /usr/local/vg-efiskal/temp folderu. Većina privremenih datoteka će biti automatski uklonjena kad više nisu potrebne. U posebnim situacijama se može desiti da privremene datoteke ne budu uklonjene što ne utiče na rad sistema. U slučaju da je potrebno osloboditi prostor na disku privremene datoteke starije od 1h se mogu obrisati ručno što ne utiče na rad sistema i nije neophodno zaustavljati rad aplikacije tokom brisanja.

Deinstalacija

Deinstalacija VG eFiskal aplikcije se vrši tako što se prvo zaustavi VG eFiskal a potom obriše /usr/local/vg-efiskal folder. Ova akcija će obrisati i sve VG eFiskal podatke, napravite rezervnu kopiju pre deinstalacije ukoliko je potrebno.

The VG eFiskal Middleware Java JAR bundle is available in cases where you want to integrate VG eFiskal more deeply within your solution. Download the Java JAR bundle file vg-efiskal-YYMMDDNN-bundled.jar and run it locally with Java JRE 1.8 (tested with OpenJDK JRE 1.8.0_312-b07):

java -DESIR_ROOT="VAR_POS_ROOT" -DESIR_DATA="VAR_POS_DATA" -DESIR_LOGS="VAR_POS_LOGS" -DESIR_TEMP="VAR_POS_TEMP" -DESIR_SN="VAR_POS_SN" -jar vg-efiskal-YYMMDDNN-bundled.jar

Where you replace the following variables with the VAR prefix with the appropriate values:

VAR_POS_ROOT - path to the base VG eFiskal folder
VAR_POS_DATA - path to the folder where data will be stored
VAR_POS_LOGS - path to the folder where log files will be stored
VAR_POS_TEMP - path to the folder where temporary files will be stored
VAR_POS_SN - the serial number assigned to you for each installation individually

The examples below use the following values for the variables mentioned:

VAR_POS_ROOT has the value /usr/local/vg-efiskal
VAR_POS_DATA has the value /usr/local/vg-efiskal/data
VAR_POS_LOGS has the value /usr/local/vg-efiskal/log
VAR_POS_TEMP has the value /usr/local/vg-efiskal/temp

NOTE: using the same serial number on two or more devices is not allowed and causes VG eFiskal to stop working.

Update

Updating the VG eFiskal Java JAR bundle to a new version is done by downloading the file with the new version, stopping VG eFiskal, copying the downloaded file over the old one, and restarting VG eFiskal. It is recommended to back up the data before updating in case it is necessary to revert to the old version.

Data backup

Creating a data backup is done by first stopping VG eFiskal, then copying/archiving the entire contents of the /usr/local/vg-efiskal/data folder, after which VG eFiskal can be restarted. Restoring data from a backup is done by first installing VG eFiskal on the computer to which you want to transfer the data, then restoring the archived data into the /usr/local/vg-efiskal/data folder (if this folder already exists on the new computer, it must first be cleared and then the data restored from the archive), after which VG eFiskal can be started.

Log files

Log files with more detailed information about the application's operation are located in the /usr/local/vg-efiskal/log folder. The name of each file contains the level of information (debug, info, or error) as well as the date in the YYMMDD format and the log extension. The error log files contain only operational errors, the info log files contain errors and main information, while the debug log files contain error, info, and all other information. In case of operational problems, it is necessary to consult the log files for more information, which can most often help resolve the problem. Log files are automatically deleted (debug after 7 days, info after 15 days, error after 30 days). If it is necessary to free up disk space, log files can be deleted manually, which does not affect the operation of the system, and it is not necessary to stop the application during deletion.

Temporary files

Temporary files are located in the /usr/local/vg-efiskal/temp folder. Most temporary files will be removed automatically when they are no longer needed. In special situations, it may happen that temporary files are not removed, which does not affect the operation of the system. If it is necessary to free up disk space, temporary files older than 1h can be deleted manually, which does not affect the operation of the system, and it is not necessary to stop the application during deletion.

Uninstallation

Uninstallation of the VG eFiskal application is done by first stopping VG eFiskal and then deleting the /usr/local/vg-efiskal folder. This action will also delete all VG eFiskal data; make a backup before uninstalling if necessary.

VG eFiskal (Cloud)

VG eFiskal Cloud se nalazi u cloud-u i VG brine o dostupnosti i ispravnosti rada sistema. Neophodno je da dobijete vaš serijski broj i API KEY i možete odmah pristupiti integraciji.

Produkcioni bazni API URL: https://pos.fiskalizacija.me/api

U slučaju korišćenja VG eFiskal Cloud-a zaglavlje (header) svakog HTTP zahteva, pored prethodno definisanih polja, treba da sadrži i serijski broj uređaja:

X-Teron-SerialNumber: YYY (YYY treba zameniti sa dodeljenim serijski brojem)

VG eFiskal Cloud resides in the cloud, and VG takes care of system availability and correct operation. You only need to obtain your serial number and API KEY, and you can immediately start the integration.

Production base API URL: https://pos.fiskalizacija.me/api

When using VG eFiskal Cloud, the header of every HTTP request must, in addition to the previously defined fields, also contain the device serial number:

X-Teron-SerialNumber: YYY (YYY should be replaced with the assigned serial number)

Konfiguracija

Configuration

Pre početka korišćenja VG eFiskal rešenja na svakom uređaju je neophodno podesiti parametre rada. VG eFiskal 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 you start using the VG eFiskal solution, you must configure the operating parameters on each device. VG eFiskal offers 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 that may require additional configuration on a specific device.

GET/api/status#

Provera spremnosti sistema

System readiness check

Nakon instalacije VG eFiskal APIj-ja kao i tokom rada sistema neophodno je vršiti povremeno provere da li je API spreman za rad. Ovaj poziv vraća sledeće informacije:

serialNumber (string) - serijski broj uređaja, proverite da li je ispravan a u slučaju korišćenja više VG eFiskal API instanci na ovaj način možete proveriti da li radite sa željenom instancom
versionCode (int) - trenutna verzija VG eFiskal API-a u formatu GGMMDDNN gde je GG godina, MM mesec, DD dan, NN redni broj
isConfigured (boolean) - true ukoliko je instanca konfigurisana na VG eFiskal serveru. Nije moguće vršiti fiskalizaciju računa i depozita ukoliko instanca nije konfigurisana.
certificateInfo (object) - podaci o sertifikatu za fiskalizaciju, proverite ispravnost kao i važenje.
efiEnvironment (string) - EFI okruženje na kojem se fiskalizuje, vrednost Production za produkciono okruženje odnosno Test za testno okruženje
requireInitialDeposit (boolean) - true ukoliko je potrebno prvo postaviti inicijalni depozita za trenutni dan pre nego što bude moguća fiskalizacija računa
allowedInitialDeposit (boolean) - true ukoliko je moguće postaviti novi inicijalni depozit što je slučaj dok se ne fiskalizuje prvi račun
efiQueueSize (int) - broj zahteva za fiskalizacijom koji još uvek nije obavljen. Ukoliko je ovaj broj veći od nule proverite Internet konekciju kao i logove aplikacije.
activeLicence (object) - trenutno aktivna licenca, može da vam posluži da pratite kada licenca ističe kako bi ste je obnovili na vreme:
- validFrom (date) - od kog dana važi licenca
- validTo (date) - do kog dana važi licenca
licences (list(object)) - niz licenci koje trenutno važe i koje dolaze u budućnosti, može da vam posluži da pratite da je sistem adekvatno pokriven licencama kako ne bi bilo prekida u radu
alerts (key-value) - key/value mapa gde je ključ tip upozorenja a vrednost nivo ozbiljnosti.
- Moguća upozorenja su:
  - StorageFull - malo slobodnog prostora na disku
  - LicenceExpired - licenca ističe
  - LicenceAuthorizationFailed - provera licence nije uspela
  - BatteryEmpty - baterija je na niskom nivou za rad
  - ApplicationUpdateAvailable - nova verzija aplikacije je dostupna
- Mogući nivoi ozbiljnosti su:
  - Information - upozorenje je informativnog karaktera i ne utiče na rad sistema
  - Warning - sistem još uvek radi ali treba reagovati na ovo upozorenje kako bi se obezbedilo da sistem radi bez prekida
  - Critical - kritičan problem, sistem trenutno nije potpuno operativan, treba odmah reagovati

Preporuka je da na svakih par minuta proverava ovaj pozivi podižete alarme ukoliko:

API ne vraća odgovor
Vrednost isConfigured je false
Postoje upozorenja Critical ili Warning nivoa
Broj nefiskalizovanih zahteva (efiQueueSize) je iznad očekivanog nivoa (zavisi od broja fiskalizacija na konkretnom uređaju)
Sertifikat za fiskalizaciju (certificateInfo) uskoro ističe

After installing the VG eFiskal API, as well as during system operation, it is necessary to periodically check whether the API is ready for use. This call returns the following information:

serialNumber (string) - serial number of the device; verify that it is correct, and in case you are using multiple VG eFiskal API instances, this is how you can check whether you are working with the intended instance
versionCode (int) - current version of the VG eFiskal API in the format GGMMDDNN, where GG is the year, MM the month, DD the day, and NN the sequential number
isConfigured (boolean) - true if the instance is configured on the VG eFiskal server. It is not possible to fiscalize invoices and deposits if the instance is not configured.
certificateInfo (object) - information about the fiscalization certificate; verify its correctness as well as its validity.
efiEnvironment (string) - the EFI environment on which fiscalization takes place; the value Production for the production environment or Test for the test environment
requireInitialDeposit (boolean) - true if it is necessary to first set the initial deposit for the current day before invoice fiscalization becomes possible
allowedInitialDeposit (boolean) - true if it is possible to set a new initial deposit, which is the case until the first invoice is fiscalized
efiQueueSize (int) - the number of fiscalization requests that have not yet been processed. If this number is greater than zero, check the Internet connection as well as the application logs.
activeLicence (object) - the currently active license; it can help you track when the license expires so that you can renew it in time:
- validFrom (date) - the day from which the license is valid
- validTo (date) - the day until which the license is valid
licences (list(object)) - an array of licenses that are currently valid and that will come into effect in the future; it can help you track that the system is adequately covered by licenses so that there are no interruptions in operation
alerts (key-value) - a key/value map where the key is the type of warning and the value is the severity level.
- The possible warnings are:
  - StorageFull - low free disk space
  - LicenceExpired - the license is expiring
  - LicenceAuthorizationFailed - license verification failed
  - BatteryEmpty - the battery is at a low level for operation
  - ApplicationUpdateAvailable - a new version of the application is available
- The possible severity levels are:
  - Information - the warning is informational in nature and does not affect system operation
  - Warning - the system is still working but you should react to this warning to ensure that the system operates without interruption
  - Critical - a critical problem; the system is currently not fully operational and you should react immediately

The recommendation is to check this call every few minutes and raise alarms if:

the API does not return a response
the value of isConfigured is false
there are warnings of Critical or Warning level
the number of unfiscalized requests (efiQueueSize) is above the expected level (depends on the number of fiscalizations on the specific device)
the fiscalization certificate (certificateInfo) is expiring soon

Primer zahtevaRequest example

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

Primer odgovoraResponse example 200 OK

{
  "serialNumber": "123456789ABCDEF",
  "versionCode": 23121701,
  "isConfigured": true,
  "certificateInfo": {
    "name": "SRĐAN GRGIĆ (Potpis/Autentifikacija)",
    "organization": "VG EFISKAL",
    "organizationUnit": null,
    "country": "ME",
    "serialNumber": "1100003084",
    "tin": "12345678",
    "validFrom": "2023-10-05T14:16:06.000+02:00",
    "validTo": "2026-10-05T14:16:06.000+02:00"
  },
  "efiEnvironment": "Test",
  "requireInitialDeposit": false,
  "allowedInitialDeposit": true,
  "efiQueueSize": 0,
  "activeLicence": {
    "validFrom": "2023-09-01",
    "validTo": "2024-08-31"
  },
  "licences": [
    {
      "validFrom": "2023-09-01",
      "validTo": "2024-08-31"
    }
  ],
  "alerts": {
    "ApplicationUpdateAvailable": "Information"
  }
}

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.

Svaki VG eFiskal uređaj preuzima osnovnu konfiguraciju sa servera, tako da je prvi korak u integraciji provera da li su dobri parametri preuzeti pozivanjem ove metode i proverom vrednosti sledećih parametara:

copmanyName - naziv kompanije
companyAddress - adresa kompanije
companyCity - grad kompanije
companyTaxId - PIB komabinje
companyVatId - PDV broj kompanije
locationName - naziv lokacije
locationAddress - adresa lokacije
locationCity - grad lokacije
locationId - interni ID (redni broj) lokacije u okviru poslovne jedinice
certificateBusinessName - naziv kompanije iz sertifikata
certificateTin - PDV broj u sertifikatu
certificateValidFrom - od kada važi sertifikat (nije moguće raditi fiskalizaciju pre ovog perioda)
certificateValidTo - do kada važi sertifikat (nije moguće raditi fiskalizaciju nakon ovog perioda)
businessUnitCode - kod poslovne jedinice
tcrCode - ENU kod
efiEnvironment - proveriti da li uređaj radi sa očekivanim EFI okruženjem za fiskalizaciju: vrednost Production za produkciono ili Test za testno okruženje

Svi gore navedeni parametri su read-only, odnosno nije ih moguće menjati direktno na uređaju već isključivo u okviru konfiguracije uređaja na VG eFiskal serveru.

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

Each VG eFiskal device downloads its basic configuration from the server, so the first step in the integration is to verify that the correct parameters have been downloaded by calling this method and checking the values of the following parameters:

copmanyName - company name
companyAddress - company address
companyCity - company city
companyTaxId - company TIN
companyVatId - company VAT number
locationName - location name
locationAddress - location address
locationCity - location city
locationId - internal ID (sequence number) of the location within the business unit
certificateBusinessName - company name from the certificate
certificateTin - VAT number in the certificate
certificateValidFrom - the date from which the certificate is valid (fiscalization cannot be performed before this period)
certificateValidTo - the date until which the certificate is valid (fiscalization cannot be performed after this period)
businessUnitCode - business unit code
tcrCode - ENU code
efiEnvironment - check whether the device is operating with the expected EFI environment for fiscalization: value Production for the production environment or Test for the test environment

All of the above parameters are read-only, meaning they cannot be changed directly on the device but only within the device configuration on the VG eFiskal server.

Primer zahtevaRequest example

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

Primer odgovoraResponse example 200 OK

{
  "languages": [
    "sr-ME",
    "sr-Cyrl-ME",
    "sr-RS",
    "sr-Cyrl-RS",
    "sq-AL",
    "tr-TR",
    "… [još 3 stavki]"
  ],
  "language": "sr-ME",
  "applicationLanguage": "sr-ME",
  "companyName": "Test Company",
  "companyAddress": "Jovana Tomaševića 9",
  "companyCity": "Bar",
  "companyTaxId": "12345678",
  "companyVatId": "123/12-000",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "locationId": "1",
  "certificateBase64": "****************",
  "certificatePassword": "****************",
  "certificateBusinessName": "SRĐAN GRGIĆ (Potpis/Autentifikacija)",
  "certificateLocation": "VG EFISKAL",
  "certificateCountry": "ME",
  "certificateSerialNumber": "1100003084",
  "certificateTin": "12345678",
  "certificateValidFrom": "2023-10-05T14:16:06.000+02:00",
  "certificateValidTo": "2026-10-05T14:16:06.000+02:00",
  "efiEnvironment": "Test",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "deviceId": "1",
  "allowedCashInvoices": true,
  "allowedNonCashInvoices": true,
  "posType": "Retail",
  "runUi": false,
  "webserverAddress": "http://0.0.0.0:4566/",
  "authorizeRemoteClients": true,
  "authorizeLocalClients": false,
  "apiKey": "/eEjXKrpPE0tJfGN6U8P9RqZigICcU7OvSs258DFTqODoW25Uk1X0hNAMBQzyJ0f5cXSSz9BvWrFPhhTXydzLw==",
  "printerName": "S80",
  "printerType": "EscPos",
  "printerDpi": null,
  "paperWidth": null,
  "paperHeight": null,
  "paperMargin": null,
  "receiptLayout": "Slip",
  "receiptHeaderImage": null,
  "receiptHeaderTextLines": [],
  "receiptFooterImage": null,
  "receiptFooterTextLines": [],
  "receiptSplitMaxHeight": null,
  "receiptWidth": 384,
  "receiptFontSizeNormal": 21,
  "receiptFontSizeLarge": 24,
  "receiptLetterSpacingNormal": 0,
  "receiptLetterSpacingCondensed": -0.05,
  "receiptFeedLinesBegin": 0,
  "receiptFeedLinesEnd": 3,
  "receiptsDelay": 0,
  "receiptCutPaper": "FeedAndCutPaper",
  "receiptOpenCashDrawer": "Epson_1",
  "receiptCustomCommandBegin": null,
  "receiptCustomCommandEnd": null,
  "qrCodeSize": 200,
  "availablePrinters": [
    "CT-S4000",
    "Cups-PDF",
    "P3",
    "S85",
    "WorkCentre-3225"
  ],
  "availablePrinterTypes": [
    "EscPos",
    "Cpcl",
    "System"
  ]
}

POST/api/settings#

Podešavanje konfiguracije štampača

Printer configuration setup

Ukoliko se VG eFiskal koristi za štampanje računa prvi korak je ispravno podešavanje štampača. 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. Napomena: ako je termalni štampač vezan na PC Windows računar u većini slučajeva nije potreban driver, odnosno driver treba da bude tipa "Raw" jer VG eFiskal radi pripremu odgovarajućih ESC/POS komandi za štampu i nije potrebna dodatna obrada štampe od strane drivera.
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.

Napomena: na Android uređajima sa integrisanim štampačem nije potrebno vršiti dodatna podešavanja niti će promena gore navedenih vrednosti imati uticaja na ponašanje.

If VG eFiskal is used for printing invoices, the first step is to correctly configure the printer. Depending on the printer type, some of the following parameters need to be set:

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, while if printing to an A4 printer (Laser, InkJet) the System type should be used. Note: if a thermal printer is connected to a PC Windows computer, in most cases no driver is needed, i.e. the driver should be of type "Raw" because VG eFiskal prepares the appropriate ESC/POS print commands and no additional print processing by the driver is required.
receiptLayout (string) - the default print format, Slip for a fiscal receipt 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 verifying the fiscal invoice, 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 is sent to cut and/or feed the paper 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 is sent to open the cash drawer connected to the printer, 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 so that no command is sent to open the cash drawer.

Note: on Android devices with an integrated printer, no additional configuration is required, nor will changing the values listed above have any effect on behavior.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/settings' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "printerName": "S80",
    "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": 200
 }'

Primer odgovoraResponse example 200 OK

Prazno telo odgovora.Empty response body.

POST/api/settings#

Podešavanje sigurnosnih parametara

Security parameter setup

Pre korišćenja VG eFiskal 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 računaru/uređaju kao i VG eFiskal) š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 VG eFiskal 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 VG eFiskal 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 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 VG eFiskal kako bi se novi parametri primenili.

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

authorizeLocalClients (boolean) - value true if local clients (applications running on the same computer/device as VG eFiskal) 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 that access the VG eFiskal API over the network/internet) are required to send the API KEY with every request, or false otherwise. It is strongly discouraged to set this parameter to false unless you are certain that you have secured access control to the VG eFiskal API in another way.
apiKey (string) - the new value of the API KEY. It is recommended that you change the API KEY so that you are the only one who knows it.
webserverAddress (string) - the IP address and port where the API is located. If access for local clients only 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 runs, if needed. After changing this parameter, you must restart VG eFiskal for the new parameters to take effect.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/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:4566/"
}'

Primer odgovoraResponse example 200 OK

Prazno telo odgovora.Empty response body.

POST/api/settings#

Podešavanje ostalih parametara

Configuring other parameters

U ovoj sekciji su navedena dodatna podešavanja koja mogu biti potrebna da se obava:

runUi (boolean) - U slučaju da je VG eFiskal API instaliran kao deo standardne VG eFiskal aplikacije (prvi slučaj instalacije sa početka dokumenta) onda se prilikom svakog startovanja pokreće i VG eFiskal GUI što u većini slučajeva gde se integriše spoljna aplikacija nije potrebno. Da bi se isključilo pokretanje GUI- neophodno je ovaj parametar postaviti na false

This section lists additional settings that may need to be configured:

runUi (boolean) - In the case where the VG eFiskal API is installed as part of the standard VG eFiskal application (the first installation case from the beginning of this document), the VG eFiskal GUI is also launched on every startup, which in most cases where an external application is integrated is not needed. To disable launching the GUI, you must set this parameter to false

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/settings' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "runUi": false
}'

Primer odgovoraResponse example 200 OK

Prazno telo odgovora.Empty response body.

Operateri

Operators

Operateri predstavljaju krajnje korisnike VG eFiskal sistema. Model podataka entita operatera sadrži sledeće bitna atribute:

UUID (uuid) - jedinstven identifikator operatera
name (string) - ime i prezime operatera
operatorCode (string) - kod operatera koji je dodeljen prilikom registracije na EFI sistemu

Napomena: model operatera može sadržati i druga polja koja se koriste od strane VG eFiskal GUI-a i nisu neophodna za integraciju spoljnih aplikacija.

Operators represent the end users of the VG eFiskal system. The data model of the operator entity contains the following important attributes:

UUID (uuid) - unique identifier of the operator
name (string) - first and last name of the operator
operatorCode (string) - operator code assigned during registration on the EFI system

Note: the operator model may also contain other fields that are used by the VG eFiskal GUI and are not required for the integration of external applications.

GET/api/users#

Spisak svih operatera

List of all operators

Ovaj API poziv vraća spisak svih operatera registrovanih na ovom uređaju. Odgovor sadrži niz operatera prema prethodno navedenom modelu podataka operatera.

Svaki operater poseduje jedinstve uuid koji je neophodno zapamtiti u spoljnom sistemu koji se integriše kako bi mogao prosleđuje informaciju o operateru na odgovarajućim mestima u raznim zahtevima (fiskalizacija računa, fiskalizacija depozita, itd.).

This API call returns the list of all operators registered on this device. The response contains an array of operators according to the previously described operator data model.

Each operator has a unique uuid that must be stored in the external system being integrated so that it can pass the operator information at the appropriate places in various requests (invoice fiscalization, deposit fiscalization, etc.).

Primer zahtevaRequest example

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

Primer odgovoraResponse example 200 OK

[
  {
    "uuid": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "name": "Operater 1",
    "operatorCode": "xe944oq388",
    "pin": "1111",
    "isAdmin": true,
    "accessRights": "{\"invoice\":{\"invoiceCreate\":true,\"order\":true},\"transactions\":{\"invoiceOverview\":true,\"depositsOverview\":true},\"info\":{\"infoView\":true},\"reports\":{\"reports\":tru… [skraćeno]",
    "updatedAt": "2023-12-15T09:38:13.000+01:00",
    "status": 1
  },
  {
    "uuid": "9a428af9-2f7d-4f1e-b002-b96852970c3f",
    "name": "Operater 2",
    "operatorCode": "xe944oq388",
    "pin": "1111",
    "isAdmin": true,
    "accessRights": "{\"invoice\":{\"invoiceCreate\":true,\"invoiceCorrective\":true,\"invoiceAdvance\":true,\"invoiceCopy\":true,\"order\":true},\"transactions\":{\"invoiceOverview\":true,\"deposit… [skraćeno]",
    "updatedAt": "2023-12-16T08:51:01.000+01:00",
    "status": 1
  },
  {
    "uuid": "9a4289d4-64fe-4243-8aa0-583be5a5d8e9",
    "name": "Operater 3",
    "operatorCode": "xe944oq388",
    "pin": "1111",
    "isAdmin": true,
    "accessRights": "{\"invoice\":{\"invoiceCreate\":true,\"invoiceCorrective\":true,\"invoiceAdvance\":true,\"invoiceCopy\":true,\"order\":true},\"transactions\":{\"invoiceOverview\":true,\"deposit… [skraćeno]",
    "updatedAt": "2023-12-16T08:51:09.000+01:00",
    "status": 1
  },
  {
    "uuid": "9a66e4e9-4516-4ae2-a1e2-c316abb1be2a",
    "name": "Operater 4",
    "operatorCode": "xe944oq388",
    "pin": "1111",
    "isAdmin": true,
    "accessRights": "{\"invoice\":{\"invoiceCreate\":true,\"invoiceCorrective\":true,\"invoiceAdvance\":true,\"invoiceCopy\":true,\"order\":true},\"transactions\":{\"invoiceOverview\":true,\"deposit… [skraćeno]",
    "updatedAt": "2023-10-18T22:12:58.000+02:00",
    "status": 1
  }
]

Artikli

Articles

Katalog artikala sadrži spisak artikala sa svim potrebnim podacima. Da bi se artikl našao na računu neophodno ga je prvo otvoriti/registrovati u VG eFiskal katalogu artikala.

Model artikla sadrži sledeća bitna polja:

UUID (uuid) - jedinstven identifikator artikla
name (string) - naziv artikla
uom (string) - jedinica mere artikla
gtin (string) - gtin (barkod) artikla
price (money) - maloprodajna cena artikla
label (tax-rate) - poreska stopa po kojoj se artikl oporezuje
taxRate (percent) - iznos poreske stope

Napomena: model artikala može sadržati i druga polja koja se koriste od strane VG eFiskal GUI-a i nisu neophodna za integraciju spoljnih aplikacija.

The article catalog contains a list of articles with all the required data. In order for an article to appear on an invoice, it must first be created/registered in the VG eFiskal article catalog.

The article model contains the following important fields:

UUID (uuid) - unique identifier of the article
name (string) - name of the article
uom (string) - unit of measure of the article
gtin (string) - gtin (barcode) of the article
price (money) - retail price of the article
label (tax-rate) - tax rate at which the article is taxed
taxRate (percent) - amount of the tax rate

Note: the article model may also contain other fields that are used by the VG eFiskal GUI and are not required for the integration of external applications.

POST/api/articles#

Pravljenje novog artikla

Creating a new article

Pozivanjem ovog API-a kreira se novi artikl u katalogu artikala. Nakon kreiranja artikla u odgovoru se dobija uuid (jedinstven identifikator) artikla koji je neophodno zapamtiti u spoljnom sistemu kako bi se mogao proslediti prilikom fiskalizacije računa.

Zahtev i odgovor sadrže podatke prema modelu artikla.

Calling this API creates a new article in the article catalog. After the article is created, the response returns the uuid (unique identifier) of the article, which must be stored in the external system so that it can be passed during invoice fiscalization.

The request and response contain data according to the article model.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/articles' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Artikl 1",
    "uom": "kom",
    "gtin": "8600115399062",
    "price": 1.50,
    "label": "VAT_21",
    "taxRate": 21
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "1210ccfa-7114-46a9-959d-18747be2dafe",
  "name": "Artikl 1",
  "uom": "kom",
  "articleId": 12,
  "gtin": "8600115399062",
  "price": 1.5,
  "priceWithoutTax": null,
  "priceLocked": false,
  "qty": null,
  "label": "VAT_21",
  "taxRate": 21,
  "categoryUuid": null,
  "status": 1
}

POST/api/articles/:articleUuid?properties=name,uom,price#

Ažuriranje podataka postojećeg artikla

Updating the data of an existing article

Namena ovog poziva je da se izmene pojedini podaci vezano za artikl koji je prethodno otvoren u sistemu. U okviru URL-a se navodi UUID artikla koji se ažurira kao i spisak atributa koji se menjaju, dok se njihove nove vrednosti navode u telu zahteva.

The purpose of this call is to modify certain data related to an article that was previously created in the system. The UUID of the article being updated is specified within the URL, along with the list of attributes being changed, while their new values are specified in the request body.

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`articleUuid`	`1210ccfa-7114-46a9-959d-18747be2dafe`	UUID artikla koji se ažuriraUUID of the article being updated

Query parametriQuery parameters

ParametarParameter	PrimerExample	OpisDescription
`properties`	`name,uom,price`

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/articles/1210ccfa-7114-46a9-959d-18747be2dafe?properties=name,uom,price' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Artikl 1 Novi",
    "uom": "kg",
    "price": 11.50
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "1210ccfa-7114-46a9-959d-18747be2dafe",
  "name": "Artikl 1 Novi",
  "uom": "kg",
  "articleId": 12,
  "gtin": "8600115399062",
  "price": 11.5,
  "priceWithoutTax": null,
  "priceLocked": false,
  "qty": null,
  "label": "VAT_21",
  "taxRate": 21,
  "categoryUuid": null,
  "status": 1
}

POST/api/articles/search#

Pretraga kataloga artikala

Searching the article catalog

API za pretraga baze artikala je dizajniran generički kako bi omogućio spoljnom sistemu da definiše proizvoljan kriterijum za pretragu.

Zahtev sadrži sledeća polja:

filter (object) - objekat koji sadrži niz uslova koji moraju biti ispunjeni kako bi se artikl našao u rezultatu i koji sadrži sledeća polja
- conditions (list(objects)) - lista uslova gde svaki uslov sadrži:
  - property (string): naziv atributa entita artikla koji se proverava i može biti: uuid, name, uom, gtin, price, label, taxRate
  - op (string): operacija poređenja i može biti: == (jednako), != (različito), ~ (slično) < (manje), > (veće), <= (manje ili jednako(, >= (veće ili jednako), IS_NULL (artibut je prazan), IS_NOT_NULL (atribut nije prazan)
  - value (string): vrednost sa kojom se poredi trenutna vrednost atributa
- type (string): može da ima vrednost AND (svi uslovi moraju biti ispunjeni) ili OR (dovoljno je da je samo jedan uslov ispunjen)
order (list(objects)) - niz atributa po kojima će biti poređan rezultat gde svaki element sadrži:
- property (string): naziv atributa entita artikla (isti atributi kao i gore)
- direction (string): znak + (rastući redosled) ili znak - (opadajući redosled)
limit (integer) - maksimalan broj rezultata u odgovoru

U nastavku je naveden primer zahteva koji odgovara upitu za prikaz svih artikala koji se zovu "Artikl 1" ili imaju cenu veću od 10 a da rezultat bude sortiran po ceni u rastućem redosledu:

The article catalog search API is designed generically to allow an external system to define an arbitrary search criterion.

The request contains the following fields:

filter (object) - an object containing a set of conditions that must be met for an article to appear in the result, and which contains the following fields
- conditions (list(objects)) - a list of conditions where each condition contains:
  - property (string): the name of the article entity attribute being checked, which can be: uuid, name, uom, gtin, price, label, taxRate
  - op (string): the comparison operation, which can be: == (equal), != (not equal), ~ (similar) < (less than), > (greater than), <= (less than or equal), >= (greater than or equal), IS_NULL (the attribute is empty), IS_NOT_NULL (the attribute is not empty)
  - value (string): the value against which the current value of the attribute is compared
- type (string): can have the value AND (all conditions must be met) or OR (it is sufficient that only one condition is met)
order (list(objects)) - a set of attributes by which the result will be ordered, where each element contains:
- property (string): the name of the article entity attribute (the same attributes as above)
- direction (string): the + sign (ascending order) or the - sign (descending order)
limit (integer) - the maximum number of results in the response

Below is an example of a request corresponding to a query for displaying all articles named "Article 1" or having a price greater than 10, with the result sorted by price in ascending order:

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/articles/search' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
        "type": "OR",
        "conditions": [
            {
                "property": "name",
                "op": "==",
                "value": "Artikl 1"
            },
            {
                "property": "price",
                "op": ">",
                "value": "10.00"
            }
       ]
    },
    "order": [
        {
            "property": "price",
            "direction": "+"
        }
    ],
    "limit": 100
}'

Primer odgovoraResponse example 200 OK

[
  {
    "uuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
    "name": "Artikl 1",
    "uom": "kom",
    "articleId": 1,
    "gtin": "12345678",
    "price": 11,
    "priceWithoutTax": 1.24,
    "priceLocked": false,
    "qty": -238,
    "label": "VAT_21",
    "taxRate": 21,
    "categoryUuid": "5446eeb0-976d-48a0-a8e8-e64e8127775b",
    "status": 1
  },
  {
    "uuid": "1210ccfa-7114-46a9-959d-18747be2dafe",
    "name": "Artikl 1 Novi",
    "uom": "kg",
    "articleId": 12,
    "gtin": "8600115399062",
    "price": 11.5,
    "priceWithoutTax": null,
    "priceLocked": false,
    "qty": null,
    "label": "VAT_21",
    "taxRate": 21,
    "categoryUuid": null,
    "status": 1
  },
  {
    "uuid": "9a6e0f3c-bf3b-4ad6-afff-d558c97d8f53",
    "name": "Artikl 12",
    "uom": "kom",
    "articleId": 12,
    "gtin": null,
    "price": 12,
    "priceWithoutTax": null,
    "priceLocked": false,
    "qty": null,
    "label": "VAT_21",
    "taxRate": 21,
    "categoryUuid": null,
    "status": 1
  },
  {
    "uuid": "e2dd0407-e960-4dee-a53e-f28e400d7fe9",
    "name": "Artikl 2",
    "uom": "kom",
    "articleId": 2,
    "gtin": "87654321",
    "price": 15,
    "priceWithoutTax": 0,
    "priceLocked": false,
    "qty": -14,
    "label": "VAT_21",
    "taxRate": 21,
    "categoryUuid": "f2baa69b-d488-493a-b37b-08284593df3e",
    "status": 1
  }
]

DELETE/api/articles/:articleUuid#

Brisanje artikla

Deleting an article

Ovaj poziv omogućava da se obriše artikl sa navedenim UUID-om. Nakon uspešnog brisanja odgovor će sadržati kompletan entitet artikla koji je obrisan.

Napomena: nakon brisanja artikla isti više neće biti vidljiv ali se on ne uklanja potpuno iz baze podataka zbog potrebe za održavanjem referencijalnog integriteta kao i istorijskog izveštavanja.

This call allows you to delete the article with the specified UUID. After successful deletion, the response will contain the complete entity of the deleted article.

Note: after an article is deleted, it will no longer be visible, but it is not completely removed from the database due to the need to maintain referential integrity as well as historical reporting.

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`articleUuid`	`1210ccfa-7114-46a9-959d-18747be2dafe`	UUID artikla koji se brišeUUID of the article being deleted

Primer zahtevaRequest example

curl -X DELETE 'http://127.0.0.1:4566/api/articles/1210ccfa-7114-46a9-959d-18747be2dafe' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "uuid": "1210ccfa-7114-46a9-959d-18747be2dafe",
  "name": "Artikl 1 Novi",
  "uom": "kg",
  "articleId": 12,
  "gtin": "8600115399062",
  "price": 11.5,
  "priceWithoutTax": null,
  "priceLocked": false,
  "qty": null,
  "label": "VAT_21",
  "taxRate": 21,
  "categoryUuid": null,
  "status": -1
}

Depoziti

Deposits

Naredni API pozivi su namenjeni za potrebe fiskalizacije inicijalnog depozita kao i naknadnog povlačećnja gotovine iz ENU-a.

The following API calls are intended for the fiscalization of the initial deposit as well as for subsequent cash withdrawal from the ENU.

POST/api/deposits/initial#

Inicijalni depozit

Initial deposit

Namena ovog poziva je da se postavi inicijalni depozit. Telo zahteva sadrži sledeće parametre:

userUuid (uuid) - UUID operatera koji postavlja inicijalni depozit
amount (money) - iznos depozita u EUR (nula ili pozitivan broj)

Odgovor sadriži sledeća polja:

businessUnitCode (string) - kod poslovne jedinica
tcrCode (string) - ENU kod
depositType (string) - vrednost Initial za inicijalni depozit
createdAt (timestamp) - vreme kada je zahtev kreiran
createdBy (uuid) - UUID operatera koji je kreirao zahtev
amount (money) - iznos inicijalnog depozita
registrationStatus (string) - može biti Completed (zahtev je fiskalizovan), Pending (zahtev će biti naknadno fiskalizovan) ili Error (greška tokom fiskalizacije)
registrationFcdc (string) - Fiskalizacioni kod, ukoliko nije bilo moguće odmah fiskalizovati zahtev (npr. zbog nedostupnosti interneta) onda će ovo polje imati null vrednost
registeredAt (timestamp) - vreme fiskalizacije
uuid (UUID) - interni UUID ovog zahteva

The purpose of this call is to set the initial deposit. The request body contains the following parameters:

userUuid (uuid) - UUID of the operator setting the initial deposit
amount (money) - deposit amount in EUR (zero or a positive number)

The response contains the following fields:

businessUnitCode (string) - business unit code
tcrCode (string) - ENU code
depositType (string) - value Initial for the initial deposit
createdAt (timestamp) - the time when the request was created
createdBy (uuid) - UUID of the operator who created the request
amount (money) - amount of the initial deposit
registrationStatus (string) - can be Completed (the request has been fiscalized), Pending (the request will be fiscalized later) or Error (an error occurred during fiscalization)
registrationFcdc (string) - Fiscalization code; if it was not possible to fiscalize the request immediately (e.g. due to internet unavailability) then this field will have a null value
registeredAt (timestamp) - the time of fiscalization
uuid (UUID) - internal UUID of this request

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/deposits/initial' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userUuid": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "amount": 100.00
}'

Primer odgovoraResponse example 200 OK

{
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "depositType": "Initial",
  "createdAt": "2023-12-17T00:47:25.125+01:00",
  "createdBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
  "amount": 100,
  "registrationStatus": "Completed",
  "registrationFcdc": "70431ce3-85fd-4602-98b5-c09f54b44091",
  "registrationError": null,
  "registeredAt": "2023-12-17T00:47:25.345+01:00",
  "uuid": "94158905-92c5-4092-9188-f4347e402e57"
}

POST/api/deposits/withdraw#

Povlačenje gotovine

Cash withdrawal

Namena ovog poziva je da se povuče određen iznos depozita. Telo zahteva sadrži sledeće parametre:

userUuid (uuid) - UUID operatera koji vrši povlačenje depozita
amount (money) - iznos depozita koji se povlači u EUR (pozitivan broj)

Odgovor sadrži iste podatke kao i u slučaju inicijalnog depozita osim sledećih izmena:

depositType (string) - vrednost Withdraw za povlačenje depozita

The purpose of this call is to withdraw a certain amount of the deposit. The request body contains the following parameters:

userUuid (uuid) - UUID of the operator performing the deposit withdrawal
amount (money) - amount of the deposit being withdrawn in EUR (a positive number)

The response contains the same data as in the case of the initial deposit except for the following changes:

depositType (string) - value Withdraw for the deposit withdrawal

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/deposits/withdraw' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userUuid": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "amount": 1.00
}'

Primer odgovoraResponse example 200 OK

{
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "depositType": "Withdraw",
  "createdAt": "2023-12-16T09:46:46.307+01:00",
  "createdBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
  "amount": 1,
  "registrationStatus": "Completed",
  "registrationFcdc": "2643fcd8-308b-42a1-a1b2-f312d29883f0",
  "registrationError": null,
  "registeredAt": "2023-12-16T09:46:46.570+01:00",
  "uuid": "191de878-9b30-4084-9f08-ba06d8f81261"
}

Fiskalizacija

Fiscalization

U nastavku je opisan API poziv za fiskalizaciju računa. Prilikom fiskalizacije svakog računa se šalje zahtev za fiskalizacijom i njegov opšti model podataka je:

invoiceRequest (object): ovaj objekat sadrži podatke o računu koji se fiskalizuje
- invoiceType (string) - tip računa može biti Invoice (račun), Corrective (korektivni račun), Advance (avansni račun)
- invoiceKind (string) - vrsta računa može biti Cash (gotovinski), NonCash (bezgotovinski)
- issuedBy (uuid) - UUID operatera koji je izdao račun
- payment (list(object)): niz objekata koji opisuju načine plaćanja računa gde svaki element sadrži sledeće podatke:
  - paymentType (string): može biti za gotovinske račune BankNote, Card, Order, Advance ili OtherCash a za bezgotovinske račune: BusinessCard, SVoucher, Company, Order, Account, Factoring ili Other.
  - amount (money): iznos koji je uplaćen po ovom načinu plaćanja
  - advanceInvoiceIic (string): opciono polje, sadrži IKOF avansnog računa samo ukoliko je plaćanje Advance
- items (list(object)): niz objekata koji opisuju stavke računa gde svaki element sadrži sledeće podatke:
  - articleUuid (uuid) - UUID artikla
  - name (string) - naziv artikla
  - uom (string) - jedinica mere
  - label (tax-rate) - poreska stopa
  - taxRate (percent) - iznos poreza
  - unitPrice (money) - maloprodajna jedinična cena
  - quantity (quantity) - količina
  - discount (percent) - iznos popusta u %
  - discountAmount (money) - iznos popusta u EUR na ukupnu cenu
  - totalAmount (money) - ukupna vrednost stavke sa primenjenim popustima
- correctiveInvoice (object) - opciono polje, ovo polje se dodaje i sadrži podatke o računu koji se koriguje:
  - iicReference (string) - IKOF računa koji se koriguje
  - issueDateTime (timestamp) - datum i vreme izdavanja računa koji se koriguje
  - correctiveInvoiceType (string) - postavlja se na vrednost Corrective (korekcije koje su rezultat poslovne odluke) ili ErrorCorrective (korekcije koje su rezultat ispravke tehničke greške)
- buyer (object) - opciono polje, podaci o kupcu
  - idType (string) - tip identifikacije kupca, može biti Tin (PIB/JMBG broj), Id (lični matični broj), Pass (broj pasoša), VAT (PDV broj), Tax (poreski broj), Soc (Broj socijalnog osiguranja)
  - idNumber (string) - identifikacioni broj kupca za tip identifikacije navedenog u prethodnom polju
  - name (string) - ima kupca
  - address (string) - adresa kupca
  - city (string) - grad kupca
  - country (string) - troslovna identifikacija zemlje kupca (ISO 3166-1 alpha 3), najčešće vrednosti MNE (Crna Gora), SRB (Srbija), ALB (Albanija), GRC (Grčka), MKD (Makedonija), RKS (Kosovo), HRV (Hrvatska), BIH (Bosna i Hercegovina), SVN (Slovenija), ITA (Italija), RUS (Rusija)
  - tic (string) - broj poreske identifikacione kartice
- note (string) - opciono polje, napomena na računu
- taxPeriod (string) - opciono polje, poreski period računa (u formatu MM/GGGG gde je MM mesec a GGGG godina poreskog perioda)
correctInvoiceId (int) - opciono polje, interni id entiteta računa bazi, koristi se u slučaju delimične refundacije računa koji je izdat na istom uređaju (postoji u bazi računa), pogledati oddgovarajući primer u nastavku.
print (boolean) - ukoliko je true fiskalni račun će biti odštampan na štampaču
email (string): email adresa na koju se šalje račun
receiptLayout (string): može da ima vrednosti Slip (račun se šalje u formatu isečka) ili Invoice (račun se šalje u A4 formatu)
receiptImageFormat (string): format računa može biti Png, Pdf ili Html
renderReceiptImage (boolean): postaviti na true kako bi se u odgovoru nalazila i slika računa u izabranom formatu. U zavnisnosti od izabranog format slika se nalazi u jednom od sledećih polja: invoiceImagePngBase64, invoiceImagePdfBase64 ili invoiceImageHtml

Nakon uspešne fiskalizacije API vraća odgovor koji sadrži sledeća polja:

uuid (uuid) - VG eFiskal (interni) UUID računa
businessUnitCode (string) - kod poslovne jedinice
tcrCode (string) - ENU kod
invoiceId (int) - interni id entiteta računa u bazi podataka (odgovara polju "id" u modelu podataka)
invoiceOrdNumber (int) - redni broj računa u okviru kalendarske godine
invoiceNumber (string) - fiskalni broj računa
invoiceInternalNumber (string) - interni broj računa
verificationUrl (string) - URL preko koga može da se proveri ispravnost računa
verificationQRCode (string) - Base64 kodirana GIF slika URL-a preko koga može da se proveri ispravnost računa
totalAmount (money) - ukupna vrednost računa
iic (string) - IKOF računa, ovo polje ima vrednost ukoliko je račun odmah fiskalizovan, dok u slučaju nemogućnosti fiskalizacije (npr. zbog nepostojanja internet veze) ovo polje će imati null vrednost.
registrationFic (string) - JIKR računa, ovo polje ima vrednost ukoliko je račun odmah fiskalizovan, dok u slučaju nemogućnosti fiskalizacije (npr. zbog nepostojanja internet veze) ovo polje će imati null vrednost
registrationStatus (string) - status fiskalizacije može biti Completed (fiskalizacija obavljena), Pending (fiskalizacija će biti pokušana naknadno), Error (greška tokom fiskalizacije)
registrationError (string) - sadrži detalje greške u slučaju da je registrationStatus=ERROR
taxItems (object) - objekat koji sadrži sumarne informacije o iznosima po poreskim stopama:
- label (tax-rate) - oznaka poreske stope
- totalAmountWithoutTax (money) - ukupan iznos bez poreza
- taxRate (percent) - iznos poreza u %
- taxAmount (money) - iznos poreza u EUR
businessName (string) - naziv kompanije koja je fiskalizovala račun
businessAddress (string) - adresa kompanije koja je fiskalizovala račun
businessCity (string) - grad kompanije koja je fiskalizovala račun
locationName (string) - naziv lokacije koja je fiskalizovala račun
locationAddress (string) - adresa lokacije koja je fiskalizovala račun
locationCity (string) - grad lokacije koja je fiskalizovala račun
tin (string) - PIB koja je fiskalizovala račun
vatId (string) - PDV broj koja je fiskalizovala račun (opciono, ukoliko je korisnik u PDV-u)
invoiceImagePngBase64 (string) - ukoliko je zahtevana u ovom polju se nala Base64 kodirana slika računa u PNG formatu
invoiceImagePdfBase64 (string) - ukoliko je zahtevana u ovom polju se nala Base64 kodirana slika računa u PDF formatu
invoiceImageHtml (string) - ukoliko je zahtevana u ovom polju se nala HTML računa

U cilju lakšeg razumevanja u nastavku su navedeni razni primeri fiskalizacije koji se najčešće pojavljuju u radu.

The API call for invoice fiscalization is described below. When fiscalizing each invoice, a fiscalization request is sent, and its general data model is:

invoiceRequest (object): this object contains data about the invoice being fiscalized
- invoiceType (string) - the invoice type can be Invoice (invoice), Corrective (corrective invoice), Advance (advance invoice)
- invoiceKind (string) - the invoice kind can be Cash (cash), NonCash (non-cash)
- issuedBy (uuid) - UUID of the operator who issued the invoice
- payment (list(object)): an array of objects describing the invoice payment methods, where each element contains the following data:
  - paymentType (string): for cash invoices it can be BankNote, Card, Order, Advance or OtherCash, and for non-cash invoices: BusinessCard, SVoucher, Company, Order, Account, Factoring or Other.
  - amount (money): the amount paid via this payment method
  - advanceInvoiceIic (string): optional field, contains the IIC of the advance invoice only if the payment is Advance
- items (list(object)): an array of objects describing the invoice items, where each element contains the following data:
  - articleUuid (uuid) - UUID of the article
  - name (string) - article name
  - uom (string) - unit of measure
  - label (tax-rate) - tax rate
  - taxRate (percent) - tax amount
  - unitPrice (money) - retail unit price
  - quantity (quantity) - quantity
  - discount (percent) - discount amount in %
  - discountAmount (money) - discount amount in EUR on the total price
  - totalAmount (money) - total value of the item with applied discounts
- correctiveInvoice (object) - optional field, this field is added and contains data about the invoice being corrected:
  - iicReference (string) - IIC of the invoice being corrected
  - issueDateTime (timestamp) - date and time of issuance of the invoice being corrected
  - correctiveInvoiceType (string) - set to the value Corrective (corrections resulting from a business decision) or ErrorCorrective (corrections resulting from fixing a technical error)
- buyer (object) - optional field, buyer data
  - idType (string) - type of buyer identification, can be Tin (TIN/personal ID number), Id (personal identification number), Pass (passport number), VAT (VAT number), Tax (tax number), Soc (social security number)
  - idNumber (string) - buyer identification number for the identification type specified in the previous field
  - name (string) - buyer name
  - address (string) - buyer address
  - city (string) - buyer city
  - country (string) - three-letter identification of the buyer's country (ISO 3166-1 alpha 3), most common values MNE (Montenegro), SRB (Serbia), ALB (Albania), GRC (Greece), MKD (Macedonia), RKS (Kosovo), HRV (Croatia), BIH (Bosnia and Herzegovina), SVN (Slovenia), ITA (Italy), RUS (Russia)
  - tic (string) - tax identification card number
- note (string) - optional field, note on the invoice
- taxPeriod (string) - optional field, tax period of the invoice (in the format MM/GGGG where MM is the month and GGGG is the year of the tax period)
correctInvoiceId (int) - optional field, internal id of the invoice entity in the database, used in case of partial refund of an invoice issued on the same device (existing in the invoice database), see the corresponding example below.
print (boolean) - if true, the fiscal invoice will be printed on the printer
email (string): email address to which the invoice is sent
receiptLayout (string): can have the values Slip (the invoice is sent in slip format) or Invoice (the invoice is sent in A4 format)
receiptImageFormat (string): the invoice format can be Png, Pdf or Html
renderReceiptImage (boolean): set to true so that the response also includes the invoice image in the selected format. Depending on the selected format, the image is located in one of the following fields: invoiceImagePngBase64, invoiceImagePdfBase64 or invoiceImageHtml

After successful fiscalization, the API returns a response containing the following fields:

uuid (uuid) - VG eFiskal (internal) UUID of the invoice
businessUnitCode (string) - business unit code
tcrCode (string) - ENU code
invoiceId (int) - internal id of the invoice entity in the database (corresponds to the "id" field in the data model)
invoiceOrdNumber (int) - ordinal number of the invoice within the calendar year
invoiceNumber (string) - fiscal invoice number
invoiceInternalNumber (string) - internal invoice number
verificationUrl (string) - URL through which the validity of the invoice can be verified
verificationQRCode (string) - Base64-encoded GIF image of the URL through which the validity of the invoice can be verified
totalAmount (money) - total value of the invoice
iic (string) - IIC of the invoice; this field has a value if the invoice was fiscalized immediately, while in case fiscalization is not possible (e.g. due to lack of internet connection) this field will have a null value.
registrationFic (string) - FIC of the invoice; this field has a value if the invoice was fiscalized immediately, while in case fiscalization is not possible (e.g. due to lack of internet connection) this field will have a null value
registrationStatus (string) - fiscalization status can be Completed (fiscalization performed), Pending (fiscalization will be attempted later), Error (error during fiscalization)
registrationError (string) - contains error details in case registrationStatus=ERROR
taxItems (object) - an object containing summary information about amounts per tax rate:
- label (tax-rate) - tax rate label
- totalAmountWithoutTax (money) - total amount without tax
- taxRate (percent) - tax amount in %
- taxAmount (money) - tax amount in EUR
businessName (string) - name of the company that fiscalized the invoice
businessAddress (string) - address of the company that fiscalized the invoice
businessCity (string) - city of the company that fiscalized the invoice
locationName (string) - name of the location that fiscalized the invoice
locationAddress (string) - address of the location that fiscalized the invoice
locationCity (string) - city of the location that fiscalized the invoice
tin (string) - TIN that fiscalized the invoice
vatId (string) - VAT number that fiscalized the invoice (optional, if the user is VAT-registered)
invoiceImagePngBase64 (string) - if requested, this field contains the Base64-encoded invoice image in PNG format
invoiceImagePdfBase64 (string) - if requested, this field contains the Base64-encoded invoice image in PDF format
invoiceImageHtml (string) - if requested, this field contains the HTML of the invoice

To facilitate understanding, various fiscalization examples that most commonly occur in practice are listed below.

Primeri

Examples

POST/api/invoices#

Fiskalizacija gotovinskog računa sa štampom

Fiscalization of a cash invoice with printing

U nastavku je naveden primer fiskalizacije gotovinskog računa:

invoiceRequest (object) - sadržaj računa
- issuedBy (uuid) - UUID operatera koji je izdao račun
- invoiceType (string) - tip računa (Invoice za standardni račun)
- invoiceKind (string) - vrsta računa (Cash za gotovinski račun)
- payment (object) - niz objekata koji obisuju vrste plaćanja:
  - amount (money) - iznos uplate za navedeni tip plaćanja
  - paymentType (string) - tip plaćanja (za gotovinske račune može biti BankNote, Card, Advance, OtherCash)
- items (object) - niz objekata koji opisuju stavke računa:
  - articleUuid (uuid) - UUID artikla
  - name (string) - naziv artikla
  - uom (string) - jedinica mere
  - label (tax-rate) - poreska stopa
  - taxRate (percent) - iznos poreza
  - unitPrice (money) - maloprodajna jedinična cena
  - quantity (quantity) - količina
  - discount (percent) - iznos popusta u %
  - discountAmount (money) - iznos popusta u EUR na ukupnu cenu
  - totalAmount (money) - ukupna vrednost stavke sa primenjenim popustima

Below is an example of fiscalizing a cash invoice:

invoiceRequest (object) - invoice content
- issuedBy (uuid) - UUID of the operator who issued the invoice
- invoiceType (string) - invoice type (Invoice for a standard invoice)
- invoiceKind (string) - invoice kind (Cash for a cash invoice)
- payment (object) - an array of objects describing the payment types:
  - amount (money) - payment amount for the specified payment type
  - paymentType (string) - payment type (for cash invoices it can be BankNote, Card, Advance, OtherCash)
- items (object) - an array of objects describing the invoice items:
  - articleUuid (uuid) - UUID of the article
  - name (string) - article name
  - uom (string) - unit of measure
  - label (tax-rate) - tax rate
  - taxRate (percent) - tax amount
  - unitPrice (money) - retail unit price
  - quantity (quantity) - quantity
  - discount (percent) - discount amount in %
  - discountAmount (money) - discount amount in EUR on the total price
  - totalAmount (money) - total value of the item with applied discounts

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
        "invoiceType": "Invoice",
        "invoiceKind": "Cash",
        "payment": [
            {
                "amount": 8.00,
                "paymentType": "BankNote"
            }
        ],
        "items": [
            {
                "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
                "name": "Artikl 1",
                "uom": "kom",
                "label": "VAT_21",
                "taxRate": 21.0,
                "unitPrice": 10.00,
                "quantity": 1.000,
                "discount": 20,
                "discountAmount": 2.00,
                "totalAmount": 8.00
            }
        ]
    }
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "f79c4a19-5a14-4409-869b-9b84d7dc48c6",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 239,
  "invoiceOrdNumber": 239,
  "invoiceNumber": "vl911cs439/239/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-239/2023",
  "issuedAt": "2023-12-16T09:48:36.809+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=F9BA6A34AE7A321A4DF97E438704486D&tin=12345678&crtd=2023-12-16T09:48:36+01:00&ord=239&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": 8,
  "iic": "F9BA6A34AE7A321A4DF97E438704486D",
  "registrationFic": "512beaff-5578-490c-b1a9-60588d65ebad",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": 6.61,
      "taxRate": 21,
      "taxAmount": 1.39
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": null,
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices#

Fiskalizacija gotovinskog računa sa podacima o kupcu i napomenom

Fiscalization of a cash invoice with customer data and a note

Svaki račun može opciono da sadrži podatke o kupcu kao i napomenu. U nastavku je naveden primer fiskalizacije gotovinskog računa za ovaj slučaj. U odnosu na prethodni primer dodatna polja u zahtevu su:

invoiceRequest (object) - sadržaj računa
- buyer (object):
  - idType (string) - tip identifikacije kupca, može biti Tin (PIB/JMBG broj), Id (lični matični broj), Pass (broj pasoša), VAT (PDV broj), Tax (poreski broj), Soc (Broj socijalnog osiguranja)
  - idNumber (string) - identifikacioni broj kupca za tip identifikacije navedenog u prethodnom polju
  - name (string) - ima kupca
  - address (string) - adresa kupca
  - city (string) - grad kupca
  - country (string) - troslovna identifikacija zemlje kupca (ISO 3166-1 alpha 3), najčešće vrednosti MNE (Crna Gora), SRB (Srbija), ALB (Albanija), GRC (Grčka), MKD (Makedonija), RKS (Kosovo), HRV (Hrvatska), BIH (Bosna i Hercegovina), SVN (Slovenija), ITA (Italija), RUS (Rusija)
  - tic (string) - broj poreske identifikacione kartice
- note (string) - napomena na računu

Odgovor sadrži ista polja kao u prethodnom primeru.

Each invoice may optionally contain buyer information as well as a note. Below is an example of cash invoice fiscalization for this case. Compared to the previous example, the additional fields in the request are:

invoiceRequest (object) - invoice content
- buyer (object):
  - idType (string) - buyer identification type, which can be Tin (PIB/JMBG number), Id (personal identification number), Pass (passport number), VAT (VAT number), Tax (tax number), Soc (social security number)
  - idNumber (string) - buyer identification number for the identification type specified in the previous field
  - name (string) - buyer name
  - address (string) - buyer address
  - city (string) - buyer city
  - country (string) - three-letter identification of the buyer's country (ISO 3166-1 alpha 3), most common values being MNE (Montenegro), SRB (Serbia), ALB (Albania), GRC (Greece), MKD (Macedonia), RKS (Kosovo), HRV (Croatia), BIH (Bosnia and Herzegovina), SVN (Slovenia), ITA (Italy), RUS (Russia)
  - tic (string) - tax identification card number
- note (string) - note on the invoice

The response contains the same fields as in the previous example.

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
        "invoiceType": "Invoice",
        "invoiceKind": "Cash",
        "buyer": {
            "idType": "Tin",
            "idNumber": "02631911",
            "name": "VG eFiskal",
            "address": "Jovana Tomaševića",
            "city": "Bar",
            "country": "MNE"
        },
        "note": "Ovo je napomena na računu",
        "payment": [
            {
                "amount": 8.00,
                "paymentType": "BankNote"
            }
        ],
        "items": [
            {
                "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
                "name": "Artikl 1",
                "uom": "kom",
                "label": "VAT_21",
                "taxRate": 21.0,
                "unitPrice": 10.00,
                "quantity": 1.000,
                "discount": 20,
                "discountAmount": 2.00,
                "totalAmount": 8.00
            }
        ]
    }
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "86f03e20-2ea2-4b13-909d-967268320ace",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 250,
  "invoiceOrdNumber": 250,
  "invoiceNumber": "vl911cs439/250/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-250/2023",
  "issuedAt": "2023-12-16T23:17:36.733+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=F213A2C8E6065F0FAC5034624BFC2D34&tin=12345678&crtd=2023-12-16T23:17:36+01:00&ord=250&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": 8,
  "iic": "F213A2C8E6065F0FAC5034624BFC2D34",
  "registrationFic": "f4562c91-a219-432e-91b2-dd1119d004c9",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": 6.61,
      "taxRate": 21,
      "taxAmount": 1.39
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": null,
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices#

Fiskalizacija gotovinskog računa sa slanjem na email

Cash invoice fiscalization with sending to email

U nastavku je primer kako se realizuje račun koji se šalje na email bez štampanja. Primer je naveden za gotovinski račun ali isti princip može da se primeni na bilo koji drugi tip računa.

Zahtev i odgovoru su isti kao u prethodnog primera uz sledeće izmene u zahtevu:

print (boolean): treba postaviti na false ukoliko se ne želi štampa računa
email (string): email adresa na koju se šalje račun
receiptLayout (string): može da ima vrednosti Slip (račun se šalje u formatu isečka) ili Invoice (račun se šalje u A4 formatu)
receiptImageFormat (string): format računa može biti Png, Pdf ili Html

Below is an example of how to create an invoice that is sent to email without printing. The example is given for a cash invoice, but the same principle can be applied to any other type of invoice.

The request and response are the same as in the previous example, with the following changes to the request:

print (boolean): should be set to false if invoice printing is not desired
email (string): the email address to which the invoice is sent
receiptLayout (string): can have the values Slip (the invoice is sent in slip format) or Invoice (the invoice is sent in A4 format)
receiptImageFormat (string): the invoice format can be Png, Pdf ili Html

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "print": false,
    "email": "test@example.com",
    "receiptLayout": "Invoice",
    "receiptImageFormat": "Pdf",
    "invoiceRequest": {
        "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
        "invoiceType": "Invoice",
        "invoiceKind": "Cash",
        "payment": [
            {
                "amount": 8.00,
                "paymentType": "BankNote"
            }
        ],
        "items": [
            {
                "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
                "name": "Artikl 1",
                "uom": "kom",
                "label": "VAT_21",
                "taxRate": 21.0,
                "unitPrice": 10.00,
                "quantity": 1.000,
                "discount": 20,
                "discountAmount": 2.00,
                "totalAmount": 8.00
            }
        ]
    }
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "32837585-d96c-4fe7-b48e-7d678e51a307",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 240,
  "invoiceOrdNumber": 240,
  "invoiceNumber": "vl911cs439/240/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-240/2023",
  "issuedAt": "2023-12-16T09:49:02.586+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=53C674F5A357F25567FA04E891B94A4D&tin=12345678&crtd=2023-12-16T09:49:02+01:00&ord=240&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": 8,
  "iic": "53C674F5A357F25567FA04E891B94A4D",
  "registrationFic": "3ff8fbba-ef7f-4073-bf87-23c2e347476c",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": 6.61,
      "taxRate": 21,
      "taxAmount": 1.39
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": null,
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices#

Fiskalizacija gotovinskog računa sa generisanjem slike računa

Cash invoice fiscalization with invoice image generation

U nastavku je primer kako se realizuje fiskalizacija računa uz generisanje slike računa u željenom formatu ali bez slanja na email ili štampu. Ovaj scenario može da bude odgovarajući u slučajevima kada spoljna aplikacija koristi svoj mehanizam za štampu ili distribuciju računa. Primer je naveden za gotovinski račun ali isti princip može da se primeni na bilo koji drugi tip računa.

Zahtev i odgovoru su isti kao u prethodnog primera uz sledeće izmene:

print (boolean): treba postaviti na false ukoliko se ne želi štampa računa
receiptLayout (string): može da ima vrednosti Slip (račun se šalje u formatu isečka) ili Invoice (račun se šalje u A4 formatu)
receiptImageFormat (string): format računa može biti Png, Pdf ili Html
renderReceiptImage (boolean): postaviti na true kako bi se u odgovoru nalazila i slika računa u izabranom formatu. U zavnisnosti od izabranog format slika se nalazi u jednom od sledećih polja: invoiceImagePngBase64, invoiceImagePdfBase64 ili invoiceImageHtml

Below is an example of how to perform invoice fiscalization while generating an invoice image in the desired format, but without sending it to email or printing it. This scenario may be appropriate in cases where an external application uses its own mechanism for printing or distributing invoices. The example is given for a cash invoice, but the same principle can be applied to any other type of invoice.

The request and response are the same as in the previous example, with the following changes:

print (boolean): should be set to false if invoice printing is not desired
receiptLayout (string): can have the values Slip (the invoice is sent in slip format) or Invoice (the invoice is sent in A4 format)
receiptImageFormat (string): the invoice format can be Png, Pdf ili Html
renderReceiptImage (boolean): set to true so that the response also includes the invoice image in the selected format. Depending on the selected format, the image is located in one of the following fields: invoiceImagePngBase64, invoiceImagePdfBase64 or invoiceImageHtml

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "print": false,
    "receiptLayout": "Slip",
    "receiptImageFormat": "Png",
    "renderReceiptImage": true,
    "invoiceRequest": {
        "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
        "invoiceType": "Invoice",
        "invoiceKind": "Cash",
        "payment": [
            {
                "amount": 8.00,
                "paymentType": "BankNote"
            }
        ],
        "items": [
            {
                "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
                "name": "Artikl 1",
                "uom": "kom",
                "label": "VAT_21",
                "taxRate": 21.0,
                "unitPrice": 10.00,
                "quantity": 1.000,
                "discount": 20,
                "discountAmount": 2.00,
                "totalAmount": 8.00
            }
        ]
    }
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "11506638-7b52-4003-8d98-971cd16cd64e",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 241,
  "invoiceOrdNumber": 241,
  "invoiceNumber": "vl911cs439/241/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-241/2023",
  "issuedAt": "2023-12-16T09:49:23.627+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=69FD942979ED074446D5075A19122712&tin=12345678&crtd=2023-12-16T09:49:23+01:00&ord=241&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": 8,
  "iic": "69FD942979ED074446D5075A19122712",
  "registrationFic": "9d7f7d2a-83de-4e90-9791-fd7a0cbfb30f",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": 6.61,
      "taxRate": 21,
      "taxAmount": 1.39
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": "iVBORw0KGgoAAAANSUhEUgAAAYAAAAQiCAAAAACHQHUhAAAplElEQVR42u2dh7arOMxG9f4vrb/MPYnVbNNC21pr7uQkgYA2WC7ikyh2qsnbzlf++w8A5xG4lP/fB+Ba1/8bARADbDsgf6/lz/zbtvH+fN5+67tR… [skraćeno]",
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

DELETE/api/invoices/:invoiceId#

Potpuna refundacija računa koji je izdat na istom uređaju

Full refund of an invoice issued on the same device

Ukoliko je potrebno izvršiti potpunu refundaciju računa koji je prethodno izdat na istom uređaju (postoji u bazi računa) onda je najlakši način iskoristiti ovaj poziv prosleđivanjem internog id broja entiteta računa (polje id iz modela podataka računa odnosno invoiceId iz odgovora prilikom fiskalizacije). Ovaj poziv će na osnovu sadržaja orginalnog računa napraviti ispravan korektivni račun i fiskalizovati ga. Opciono u telu zahteva mogu da se navedu dodatni parametri (potpuno odgovaraju odgovarajućim parametrima u drugim pozivima za fiskalizaciju):

print (boolean): treba postaviti na false ukoliko se ne želi štampa računa
receiptLayout (string): može da ima vrednosti Slip (račun se šalje u formatu isečka) ili Invoice (račun se šalje u A4 formatu)
receiptImageFormat (string): format računa može biti Png, Pdf ili Html
renderReceiptImage (boolean): postaviti na true kako bi se u odgovoru nalazila i slika računa u izabranom formatu. U zavnisnosti od izabranog format slika se nalazi u jednom od sledećih polja: invoiceImagePngBase64, invoiceImagePdfBase64 ili invoiceImageHtml

If you need to perform a full refund of an invoice that was previously issued on the same device (it exists in the invoice database), then the easiest way is to use this call by passing the internal id number of the invoice entity (the id field from the invoice data model, i.e. invoiceId from the response during fiscalization). Based on the contents of the original invoice, this call will create a correct corrective invoice and fiscalize it. Optionally, additional parameters can be specified in the request body (they fully correspond to the matching parameters in other fiscalization calls):

print (boolean): set to false if you do not want the invoice to be printed
receiptLayout (string): can have the values Slip (the invoice is sent in slip format) or Invoice (the invoice is sent in A4 format)
receiptImageFormat (string): the invoice format can be Png, Pdf or Html
renderReceiptImage (boolean): set to true so that the response also contains the invoice image in the selected format. Depending on the selected format, the image is located in one of the following fields: invoiceImagePngBase64, invoiceImagePdfBase64 or invoiceImageHtml

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`invoiceId`	`242`	Interni id broj entiteta računa koji se refundira (polje "id" iz modela podataka entiteta računa odnosno "invoiceId" iz odgovora pri fiskalizaciji računa)The internal id number of the invoice entity being refunded (the "id" field from the invoice entity data model, i.e. "invoiceId" from the response during invoice fiscalization)

Primer zahtevaRequest example

curl -X DELETE 'http://127.0.0.1:4566/api/invoices/242' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "print": false,
    "email": "test@example.com",
    "receiptLayout": "Invoice",
    "receiptImageFormat": "Pdf"
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "b6f4d1cb-cf75-4eb3-872b-ea93c97527ba",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 243,
  "invoiceOrdNumber": 243,
  "invoiceNumber": "vl911cs439/243/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-243/2023",
  "issuedAt": "2023-12-16T14:51:56.622+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=2049B7AF77691B1738308DE36B075798&tin=12345678&crtd=2023-12-16T14:51:56+01:00&ord=243&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=-8.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": -8,
  "iic": "2049B7AF77691B1738308DE36B075798",
  "registrationFic": "b5ea985b-b1be-41da-a383-40e099317aba",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": -6.61,
      "taxRate": 21,
      "taxAmount": -1.39
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": null,
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices#

Delimična korekcija računa

Partial invoice correction

Ovaj poziv služi za delimična korekcijna računa koji je izdat na istom uređaju (postoji u bazi računa). Delimična korekcija se realizuje kroz fiskalizaciju dva računa: potpune korekcije prvobitnog računa a potpom fiskalizacije novog računa.

Zahtev je isti kao u slučaju izdavanja običnog računa uz uključivanje dodatnog polja u zahtevu:

correctInvoiceId (int) - interni id entiteta računa koji odgovara vrednosti polja id iz modela entiteta računa odnosno invoiceId iz odogovora prilikom fiskalizacije

This call is used for partial correction of an invoice that was issued on the same device (it exists in the invoice database). A partial correction is carried out through the fiscalization of two invoices: a full correction of the original invoice and then the fiscalization of a new invoice.

The request is the same as when issuing a regular invoice, with the inclusion of an additional field in the request:

correctInvoiceId (int) - the internal id of the invoice entity that corresponds to the value of the id field from the invoice entity model, i.e. invoiceId from the response during fiscalization

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "correctInvoiceId": 244,
    "invoiceRequest": {
        "invoiceType": "Invoice",
        "invoiceKind": "Cash",
        "payment": [
            {
                "amount": 4.00,
                "paymentType": "BankNote"
            }
        ],
        "items": [
            {
                "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
                "name": "Artikl 1",
                "uom": "kom",
                "label": "VAT_21",
                "taxRate": 21,
                "totalAmount": 4.00,
                "unitPrice": 2.00,
                "quantity": 2.000,
                "discount": 0,
                "discountAmount": 0
            }
        ],
        "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c"
    }
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "301a3b32-3fd0-460b-926b-171238b18bf4",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 246,
  "invoiceOrdNumber": 246,
  "invoiceNumber": "vl911cs439/246/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-246/2023",
  "issuedAt": "2023-12-16T14:59:21.052+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=9727188EBB01E4BAB16285B26B73E451&tin=12345678&crtd=2023-12-16T14:59:21+01:00&ord=246&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=4.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": 4,
  "iic": "9727188EBB01E4BAB16285B26B73E451",
  "registrationFic": "7af8e124-30da-4167-86ad-0da36868eccb",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": 3.31,
      "taxRate": 21,
      "taxAmount": 0.69
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": null,
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices#

Izdavanje opšteg korektivnog računa

Issuing a general corrective invoice

Ovaj poziv je namenjen za situacije kada ne mogu da se koriste prethodne dve metode za izdavanje korektivnog računa (npr. ako prethodni račun nije izdat na istom uređaju ili se ne nalazi u bazi računa) ili kada je potrebno izdati specifičan korektivni račun.

Zahtev je isti kao u prethodnim slučajevima fiskalizacije uz sledeće izmene:

invoiceType (string) - postavlja se na vrednost Corrective
payment (list(object)):
- amount (money) - može da ima pozitivnu ili negativnu vrednost u zavisnosti u kom pravcu se radi korekcija
correctiveInvoice (object) - ovo polje se dodaje i sadrži podatke o računu koji se koriguje:
- iicReference (string) - IKOF računa koji se koriguje
- issueDateTime (timestamp) - datum i vreme izdavanja računa koji se koriguje
- correctiveInvoiceType (string) - postavlja se na vrednost Corrective (korekcije koje su rezultat poslovne odluke) ili ErrorCorrective (korekcije koje su rezultat ispravke tehničke greške)
items (list(object)):
- quantity (quantity) - može da ima pozitivnu ili negativnu vrednost u zavisnosti u kom pravcu se radi korekcija
- totalAmount (money) - može da ima pozitivnu ili negativnu vrednost u zavisnosti u kom pravcu se radi korekcija

This call is intended for situations where the previous two methods for issuing a corrective invoice cannot be used (e.g. if the previous invoice was not issued on the same device or is not in the invoice database) or when a specific corrective invoice needs to be issued.

The request is the same as in the previous fiscalization cases, with the following changes:

invoiceType (string) - set to the value Corrective
payment (list(object)):
- amount (money) - can have a positive or negative value depending on the direction in which the correction is made
correctiveInvoice (object) - this field is added and contains data about the invoice being corrected:
- iicReference (string) - the IIC of the invoice being corrected
- issueDateTime (timestamp) - the date and time of issuance of the invoice being corrected
- correctiveInvoiceType (string) - set to the value Corrective (corrections resulting from a business decision) or ErrorCorrective (corrections resulting from fixing a technical error)
items (list(object)):
- quantity (quantity) - can have a positive or negative value depending on the direction in which the correction is made
- totalAmount (money) - can have a positive or negative value depending on the direction in which the correction is made

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceRequest": {
        "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
        "invoiceType": "Corrective",
        "invoiceKind": "Cash",
        "payment": [
            {
                "amount": -4.00,
                "paymentType": "BankNote"
            }
        ],
        "correctiveInvoice": {
            "iicReference": "FA42B672845655E1599567EE9F360BED",
            "issueDateTime": "2023-12-16T15:09:14.846+01:00",
            "correctiveInvoiceType": "Corrective"
        },
        "items": [
            {
                "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
                "name": "Artikl 1",
                "uom": "kom",
                "label": "VAT_21",
                "taxRate": 21,
                "unitPrice": 10.00,
                "quantity": -0.500,
                "discount": 20,
                "discountAmount": 2.00,
                "totalAmount": -4.00
            }
        ]
    }
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "20ad3ca1-1329-4f99-8155-5caf3e68e75c",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 248,
  "invoiceOrdNumber": 248,
  "invoiceNumber": "vl911cs439/248/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-248/2023",
  "issuedAt": "2023-12-16T15:11:38.636+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=F1AFC9CBF1EA70E9B0447D8638B5CD6E&tin=12345678&crtd=2023-12-16T15:11:38+01:00&ord=248&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=-4.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": -4,
  "iic": "F1AFC9CBF1EA70E9B0447D8638B5CD6E",
  "registrationFic": "e8784c0c-1533-43e2-8e15-007c42da77f8",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": -3.31,
      "taxRate": 21,
      "taxAmount": -0.69
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": null,
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices/:invoiceId/copy#

Izdavanje kopije računa

Issuing an invoice copy

Ovaj poziv služi za izdavanje kopije računa. Kopija računa se ne fiskalizuje niti se pamti u bazi računa već služi isključivo da po potrebi može da se ponovo odštampa, pošalje na mail ili napravi slika postojećeg računa. Izgled računa će biti isti kao i orginalni račun uz napomenu u naslovu računa da se radi o kopiji.

U telu zahteva se mogu navesti sledeći parametri:

print (boolean): treba postaviti na false ukoliko se ne želi štampa računa
receiptLayout (string): može da ima vrednosti Slip (račun se šalje u formatu isečka) ili Invoice (račun se šalje u A4 formatu)
receiptImageFormat (string): format računa može biti Png, Pdf ili Html
renderReceiptImage (boolean): postaviti na true kako bi se u odgovoru nalazila i slika računa u izabranom formatu. U zavnisnosti od izabranog format slika se nalazi u jednom od sledećih polja: invoiceImagePngBase64, invoiceImagePdfBase64 ili invoiceImageHtml

Odgovor sadrži isti odgovor koji je bio poslat kada je prvi put originalni račun bio fiskalizovan.

This call is used to issue an invoice copy. The invoice copy is not fiscalized nor stored in the invoice database; it serves solely so that, when needed, it can be reprinted, sent by e-mail, or have an image of the existing invoice generated. The invoice layout will be the same as the original invoice, with a note in the invoice title indicating that it is a copy.

The following parameters can be specified in the request body:

print (boolean): should be set to false if invoice printing is not desired
receiptLayout (string): can have the values Slip (the invoice is sent in slip format) or Invoice (the invoice is sent in A4 format)
receiptImageFormat (string): the invoice format can be Png, Pdf or Html
renderReceiptImage (boolean): set to true so that the response also contains the invoice image in the selected format. Depending on the selected format, the image is found in one of the following fields: invoiceImagePngBase64, invoiceImagePdfBase64 or invoiceImageHtml

The response contains the same response that was sent when the original invoice was first fiscalized.

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`invoiceId`	`249`	Interni id broj entiteta računa čija kopija se izdaje (polje "id" iz modela podataka entiteta računa odnosno "invoiceId" iz odgovora pri fiskalizaciji računa)Internal id number of the invoice entity whose copy is being issued (the "id" field from the invoice entity data model, i.e. "invoiceId" from the response when fiscalizing the invoice)

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices/249/copy' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "print": true
}'

Primer odgovoraResponse example 200 OK

{
  "uuid": "a24cca98-b1c8-4831-b0e2-e8f15d1561f1",
  "businessUnitCode": "vl911cs439",
  "tcrCode": "hh199qa619",
  "invoiceId": 249,
  "invoiceOrdNumber": 249,
  "invoiceNumber": "vl911cs439/249/2023/hh199qa619",
  "invoiceInternalNumber": "1-1-249/2023",
  "issuedAt": "2023-12-16T15:26:58.591+01:00",
  "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=55430B17816334FEBC7331BD66626E08&tin=12345678&crtd=2023-12-16T15:26:58+01:00&ord=249&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
  "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
  "totalAmount": 8,
  "iic": "55430B17816334FEBC7331BD66626E08",
  "registrationFic": "baab2286-5b98-466a-965d-95e86388a4cd",
  "registrationStatus": "Completed",
  "registrationError": null,
  "taxItems": [
    {
      "label": "VAT_21",
      "totalAmountWithoutTax": 6.61,
      "taxRate": 21,
      "taxAmount": 1.39
    }
  ],
  "businessName": "Test Company",
  "businessAddress": "Jovana Tomaševića 9",
  "businessCity": "Bar",
  "locationName": "Test Poslovna Jedinica",
  "locationAddress": "Njegoševa 99",
  "locationCity": "Podgorica",
  "tin": "12345678",
  "vatId": "123/12-000",
  "invoiceImagePngBase64": "iVBORw0KGgoAAAANSUhEUgAACMUAAAR8CAAAAACyGu7HAACAAElEQVR42uydB3wWRfrHJ72HUBIgEELvSFFBQQUrHUVEyiFiL6cHnooFFf5iOc8D5bCAJ3iAgmcBpSgiHRVQikoRBQRBQgiEFNLLu/+d2f6+M1sA… [skraćeno]",
  "invoiceImagePdfBase64": null,
  "invoiceImageHtml": null
}

POST/api/invoices/search#

Pretraga baze računa

Invoice database search

izaciju računa.

Namena ovog API poziva je da spoljni sistem može da obavi pretragu baze računa po raznim kriterijumima. Telo zahteva sadrži filter koji može da sadrži jedan ili više kriterijuma i rezultat će sadržati samo račune koji odgovaraju svim kriterijumima:

fromDate (timestamp) - račun je izdat nakon ovog datuma (uključujući)
toDate (timestamp) - račun je izdat pre ovog datuma (uključujući)
invoiceTypes (list(string)) - niz tipova računa (Invoice, Corrective, Advance) i biće izabrani računi čiji se tip nalazi u ovom nizu
invoiceKinds (list(string)) - niz vrsta računa (Cash, NonCash) i biće izabrani računi čiji se tip nalazi u ovom nizu
amountFrom (money) - ukupna vrednost računa je jednaka ili veća navedenom iznosu
amountTo (money) - ukupna vrednost računa je manja ili jednaka navedenom iznosu
paymentTypes (list(string)) - niz vrsta plaćanja (BankNote, Card, OtherCash, BusinessCard, Account, Other)), biće izabrani računi čija je bar jedna vrsta plaćanja u navedenom nizu
year (int) - kalendarska godina u kojoj je izdat račun
ord (int) - redni broj računa
issuedBy (uuid) - UUID operatera koji je izdao račun
iic (string) - IKOF računa
registrationFic (string) - JIKR računa
registrationStatuses (list(string)) - niz registracionih status (Completed, Pending, Error), biće izabrani računi čiji status odgovara jednom od navedenih status u listi

Odgovor sadrži niz računa koji zadovoljavaju zadati kriterijum gde svaki element sadrži sledeća polja:

id (int) - interni broj entiteta računa
businessUnitCode (string) - kod poslovne jedinice
tcrCode (string) - ENU kod
year (int) - godina u kojoj je izdat račun
ord (int) - redni broj računa u kalendarskoj godini
invoiceType (string) - tip računa može biti Invoice (račun), Corrective (korektivni račun), Advance (avansni račun)
invoiceKind (string) - vrsta računa može biti Cash (gotovinski), NonCash (bezgotovinski)
issuedBy (uuid) - UUID operatera koji je izdao račun
totalAmount (money) - ukupan iznos računa
iic (string) - IKOF fiskalizovanog računa (null ukoliko račun nije fiskalizovan)
registrationStatus (string) - status fiskalizacije računa može biti Completed (fiskalizovan), Pending (fiskalizacija u toku), Error (greška tokom fiskalizacije)
registrationFic (string) - JIKR fiskalizovanog računa (null ukoliko račun nije fiskalizovan)
registrationError (string) - sadrži detalje grešeke koja se desila tokom fiskalizacije odnosno null u ostalim slučajevima
isIssuedOffline (boolean) - da li je račun izdat u offline režimu rada
isCanceled (boolean) - da li je račun korigovan
clientUuid (uuid) - UUID kupca u VG eFiskal bazi
buyer (object) - podaci o kupcu
- idType (string) - tip identifikacije kupca, može biti Tin (PIB/JMBG broj), Id (lični matični broj), Pass (broj pasoša), VAT (PDV broj), Tax (poreski broj), Soc (Broj socijalnog osiguranja)
- idNumber (string) - identifikacioni broj kupca za tip identifikacije navedenog u prethodnom polju
- name (string) - ima kupca
- address (string) - adresa kupca
- city (string) - grad kupca
- country (string) - troslovna identifikacija zemlje kupca (ISO 3166-1 alpha 3), najčešće vrednosti MNE (Crna Gora), SRB (Srbija), ALB (Albanija), GRC (Grčka), MKD (Makedonija), RKS (Kosovo), HRV (Hrvatska), BIH (Bosna i Hercegovina), SVN (Slovenija), ITA (Italija), RUS (Rusija)
- tic (string) - broj poreske identifikacione kartice
note (string) - napomena na fakturi

ization of invoices.

The purpose of this API call is to allow an external system to search the invoice database by various criteria. The request body contains a filter that may include one or more criteria, and the result will contain only invoices that match all criteria:

fromDate (timestamp) - invoice was issued after this date (inclusive)
toDate (timestamp) - invoice was issued before this date (inclusive)
invoiceTypes (list(string)) - an array of invoice types (Invoice, Corrective, Advance) and invoices whose type is in this array will be selected
invoiceKinds (list(string)) - an array of invoice kinds (Cash, NonCash) and invoices whose kind is in this array will be selected
amountFrom (money) - the total value of the invoice is equal to or greater than the specified amount
amountTo (money) - the total value of the invoice is less than or equal to the specified amount
paymentTypes (list(string)) - an array of payment types (BankNote, Card, OtherCash, BusinessCard, Account, Other)), invoices with at least one payment type in the specified array will be selected
year (int) - the calendar year in which the invoice was issued
ord (int) - the ordinal number of the invoice
issuedBy (uuid) - UUID of the operator who issued the invoice
iic (string) - the IIC of the invoice
registrationFic (string) - the FIC of the invoice
registrationStatuses (list(string)) - an array of registration statuses (Completed, Pending, Error), invoices whose status matches one of the statuses listed will be selected

The response contains an array of invoices that satisfy the given criteria, where each element contains the following fields:

id (int) - the internal number of the invoice entity
businessUnitCode (string) - the business unit code
tcrCode (string) - the TCR code
year (int) - the year in which the invoice was issued
ord (int) - the ordinal number of the invoice in the calendar year
invoiceType (string) - the invoice type can be Invoice, Corrective (corrective invoice), Advance (advance invoice)
invoiceKind (string) - the invoice kind can be Cash (cash), NonCash (non-cash)
issuedBy (uuid) - UUID of the operator who issued the invoice
totalAmount (money) - the total amount of the invoice
iic (string) - the IIC of the fiscalized invoice (null if the invoice is not fiscalized)
registrationStatus (string) - the fiscalization status of the invoice can be Completed (fiscalized), Pending (fiscalization in progress), Error (error during fiscalization)
registrationFic (string) - the FIC of the fiscalized invoice (null if the invoice is not fiscalized)
registrationError (string) - contains details of the error that occurred during fiscalization, or null in other cases
isIssuedOffline (boolean) - whether the invoice was issued in offline mode
isCanceled (boolean) - whether the invoice has been corrected
clientUuid (uuid) - UUID of the buyer in the VG eFiskal database
buyer (object) - buyer data
- idType (string) - the buyer's identification type, can be Tin (TIN/personal ID number), Id (personal identification number), Pass (passport number), VAT (VAT number), Tax (tax number), Soc (social security number)
- idNumber (string) - the buyer's identification number for the identification type specified in the previous field
- name (string) - the buyer's name
- address (string) - the buyer's address
- city (string) - the buyer's city
- country (string) - the three-letter country identification of the buyer (ISO 3166-1 alpha 3), most common values MNE (Montenegro), SRB (Serbia), ALB (Albania), GRC (Greece), MKD (Macedonia), RKS (Kosovo), HRV (Croatia), BIH (Bosnia and Herzegovina), SVN (Slovenia), ITA (Italy), RUS (Russia)
- tic (string) - the tax identification card number
note (string) - a note on the invoice

Primer zahtevaRequest example

curl -X POST 'http://127.0.0.1:4566/api/invoices/search' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fromDate": "2023-11-12T08:00:00+01:00",
    "toDate": "2023-11-21T23:59:59+01:00",
    "invoiceTypes": ["Invoice"],
    "invoiceKinds": ["Cash"],
    "amountFrom": 1.00,
    "amountTo": 100.00
}'

Primer odgovoraResponse example 200 OK

[
  {
    "id": 193,
    "businessUnitCode": "vl911cs439",
    "tcrCode": "hh199qa619",
    "year": 2023,
    "ord": 193,
    "invoiceType": "Invoice",
    "invoiceKind": "Cash",
    "issuedAt": "2023-11-12T19:01:48.000+01:00",
    "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "totalAmount": 10,
    "iic": "FCC24912F8F044E1A3CD41407988A9EF",
    "registrationStatus": "Completed",
    "registrationFic": "2e5357bf-9908-4d3c-a38a-759c7da73833",
    "registrationError": null,
    "registeredAt": "2023-11-12T19:01:48.000+01:00",
    "isIssuedOffline": false,
    "isCanceled": true,
    "clientUuid": null,
    "buyer": null,
    "note": null
  },
  {
    "id": 195,
    "businessUnitCode": "vl911cs439",
    "tcrCode": "hh199qa619",
    "year": 2023,
    "ord": 195,
    "invoiceType": "Invoice",
    "invoiceKind": "Cash",
    "issuedAt": "2023-11-15T21:35:11.000+01:00",
    "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "totalAmount": 10,
    "iic": "C11D9EC0D918199B3A40D130C5FA810A",
    "registrationStatus": "Completed",
    "registrationFic": "bb378b60-3e49-4c23-be91-7424e90310ca",
    "registrationError": null,
    "registeredAt": "2023-11-15T21:36:17.000+01:00",
    "isIssuedOffline": true,
    "isCanceled": false,
    "clientUuid": null,
    "buyer": null,
    "note": null
  },
  {
    "id": 196,
    "businessUnitCode": "vl911cs439",
    "tcrCode": "hh199qa619",
    "year": 2023,
    "ord": 196,
    "invoiceType": "Invoice",
    "invoiceKind": "Cash",
    "issuedAt": "2023-11-15T21:35:15.000+01:00",
    "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "totalAmount": 10,
    "iic": "C71EC797135939FBF96122480E8B01A2",
    "registrationStatus": "Completed",
    "registrationFic": "d3be43df-4dd7-40fd-b651-867368269a67",
    "registrationError": null,
    "registeredAt": "2023-11-15T23:31:50.000+01:00",
    "isIssuedOffline": true,
    "isCanceled": false,
    "clientUuid": null,
    "buyer": null,
    "note": null
  }
]

GET/api/invoices/:invoiceId?imageFormat=Png&receiptLayout=Slip#

Preuzimanje sadržaja i slike prethodno izdatog računa

Retrieving the content and image of a previously issued invoice

Namena ovog API poziva je da se ponovo preuzmu svi podaci o računu (zahtev prilikom fiskalizacije koa i odgovor) kao i da se opciono dobije slika računa u odgovarajućem formatu.

U okviru URL-a se navodi interni ID entiteta računa koji se želi preuzeti i opciono parametri:

receiptLayout (string) - izgled računa (Slip ili Invoice)
imageFormat (string) - format slike (Png, Pdf, Html)

Slika računa u zadatom formatu i izgledu se nalazi u odgovoru u polju:

receiptImageBase64 (string) - slika računa

The purpose of this API call is to retrieve all invoice data again (the request during fiscalization as well as the response) and to optionally obtain the invoice image in the appropriate format.

The internal ID of the invoice entity to be retrieved is specified in the URL, along with optional parameters:

receiptLayout (string) - invoice layout (Slip or Invoice)
imageFormat (string) - image format (Png, Pdf, Html)

The invoice image in the specified format and layout is found in the response in the field:

receiptImageBase64 (string) - invoice image

Path parametriPath parameters

ParametarParameter	PrimerExample	OpisDescription
`invoiceId`	`250`

Query parametriQuery parameters

ParametarParameter	PrimerExample	OpisDescription
`imageFormat`	`Png`
`receiptLayout`	`Slip`

Primer zahtevaRequest example

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

Primer odgovoraResponse example 200 OK

{
  "invoiceRequest": {
    "invoiceKind": "Cash",
    "invoiceType": "Invoice",
    "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "items": [
      {
        "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
        "name": "Artikl 1",
        "plu": null,
        "gtin": null,
        "uom": "kom",
        "quantity": 1,
        "unitPrice": 10,
        "unitPriceWithoutTaxAndDiscount": 10.3306,
        "taxRate": 21,
        "label": "VAT_21",
        "totalTaxAmount": 1.39,
        "totalAmountWithoutTax": 6.61,
        "totalAmount": 8,
        "discount": 20,
        "discountAmount": 2
      }
    ],
    "payment": [
      {
        "paymentType": "BankNote",
        "amount": 8,
        "companyCardNumber": null,
        "advanceInvoiceIic": null,
        "bankAccountNumber": null,
        "vouchers": null
      }
    ],
    "correctiveInvoice": null,
    "iicReferences": null,
    "clientUuid": null,
    "buyer": {
      "idType": "Tin",
      "idNumber": "02631911",
      "name": "VG eFiskal",
      "address": "Jovana Tomaševića",
      "city": "Bar",
      "country": "MNE",
      "tic": null
    },
    "note": "Ovo je napomena na računu",
    "taxPeriod": null
  },
  "invoiceResponse": {
    "uuid": "86f03e20-2ea2-4b13-909d-967268320ace",
    "businessUnitCode": "vl911cs439",
    "tcrCode": "hh199qa619",
    "invoiceId": 250,
    "invoiceOrdNumber": 250,
    "invoiceNumber": "vl911cs439/250/2023/hh199qa619",
    "invoiceInternalNumber": "1-1-250/2023",
    "issuedAt": "2023-12-16T23:17:36.733+01:00",
    "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=F213A2C8E6065F0FAC5034624BFC2D34&tin=12345678&crtd=2023-12-16T23:17:36+01:00&ord=250&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
    "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
    "totalAmount": 8,
    "iic": "F213A2C8E6065F0FAC5034624BFC2D34",
    "registrationFic": "f4562c91-a219-432e-91b2-dd1119d004c9",
    "registrationStatus": "Completed",
    "registrationError": null,
    "taxItems": [
      {
        "label": "VAT_21",
        "totalAmountWithoutTax": 6.61,
        "taxRate": 21,
        "taxAmount": 1.39
      }
    ],
    "businessName": "Test Company",
    "businessAddress": "Jovana Tomaševića 9",
    "businessCity": "Bar",
    "locationName": "Test Poslovna Jedinica",
    "locationAddress": "Njegoševa 99",
    "locationCity": "Podgorica",
    "tin": "12345678",
    "vatId": "123/12-000",
    "invoiceImagePngBase64": null,
    "invoiceImagePdfBase64": null,
    "invoiceImageHtml": null
  },
  "receiptImageBase64": "iVBORw0KGgoAAAANSUhEUgAAAYAAAARwCAAAAADGBtzdAAAuFUlEQVR42u2dibLsuKpE+f+f5sV9fXZZQIIkz0MS0adrV3mQtWyhASeitEtNvna98t9/BHAdgVvV//cA3Ov+/yIA+gDbDsjfZ/kz/7VtvH+/t1st… [skraćeno]",
  "print": true,
  "receiptLayout": "Slip",
  "renderReceiptImage": false,
  "receiptImageFormat": "Png",
  "skipEftPos": false,
  "autoGenerated": false
}

GET/api/invoices/last#

Preuzimanje poslednjeg računa

Retrieving the last invoice

Ovaj API poziv vraća sadržaj poslednjeg računa i najčešće se koristi u slučaju ukoliko je došlo do problema u komunikaciji između spoljnog sistema i VG eFiskal API-a prilikom fiskalizacije tako da spoljni sistem nema pouzdanu informaciju da li se fiskalizacija desila. Kako bi se izbeglo duplo fiskalizovanje računa spoljni sistem treba da iskoristi ovaj poziv i proveri da li je račun već fiskalizovan ili je poslednji fiskalizovan račun neki drugi.

This API call returns the content of the last invoice and is most often used in case a problem occurred in the communication between the external system and the VG eFiskal API during fiscalization, so that the external system has no reliable information about whether fiscalization took place. In order to avoid double fiscalization of an invoice, the external system should use this call and check whether the invoice has already been fiscalized or whether the last fiscalized invoice is a different one.

Primer zahtevaRequest example

curl -X GET 'http://127.0.0.1:4566/api/invoices/last' \
  -H 'Authorization: Bearer <API_KEY>'

Primer odgovoraResponse example 200 OK

{
  "invoiceRequest": {
    "invoiceKind": "Cash",
    "invoiceType": "Invoice",
    "issuedBy": "9a3c2ab2-8be8-4027-83bf-5896ef2ffe3c",
    "items": [
      {
        "articleUuid": "45a04d26-a381-41fb-9eaf-17098c237e1b",
        "name": "Artikl 1",
        "plu": null,
        "gtin": null,
        "uom": "kom",
        "quantity": 1,
        "unitPrice": 10,
        "unitPriceWithoutTaxAndDiscount": 10.3306,
        "taxRate": 21,
        "label": "VAT_21",
        "totalTaxAmount": 1.39,
        "totalAmountWithoutTax": 6.61,
        "totalAmount": 8,
        "discount": 20,
        "discountAmount": 2
      }
    ],
    "payment": [
      {
        "paymentType": "BankNote",
        "amount": 8,
        "companyCardNumber": null,
        "advanceInvoiceIic": null,
        "bankAccountNumber": null,
        "vouchers": null
      }
    ],
    "correctiveInvoice": null,
    "iicReferences": null,
    "clientUuid": null,
    "buyer": {
      "idType": "Tin",
      "idNumber": "02631911",
      "name": "VG eFiskal",
      "address": "Jovana Tomaševića",
      "city": "Bar",
      "country": "MNE",
      "tic": null
    },
    "note": "Ovo je napomena na računu",
    "taxPeriod": null
  },
  "invoiceResponse": {
    "uuid": "86f03e20-2ea2-4b13-909d-967268320ace",
    "businessUnitCode": "vl911cs439",
    "tcrCode": "hh199qa619",
    "invoiceId": 250,
    "invoiceOrdNumber": 250,
    "invoiceNumber": "vl911cs439/250/2023/hh199qa619",
    "invoiceInternalNumber": "1-1-250/2023",
    "issuedAt": "2023-12-16T23:17:36.733+01:00",
    "verificationUrl": "https://efitest.tax.gov.me/ic/#/verify?iic=F213A2C8E6065F0FAC5034624BFC2D34&tin=12345678&crtd=2023-12-16T23:17:36+01:00&ord=250&bu=vl911cs439&cr=hh199qa619&sw=dg736jg907&prc=8.00",
    "verificationQRCode": "R0lGODlhyADIAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4ODg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEhISIiIiMj… [skraćeno]",
    "totalAmount": 8,
    "iic": "F213A2C8E6065F0FAC5034624BFC2D34",
    "registrationFic": "f4562c91-a219-432e-91b2-dd1119d004c9",
    "registrationStatus": "Completed",
    "registrationError": null,
    "taxItems": [
      {
        "label": "VAT_21",
        "totalAmountWithoutTax": 6.61,
        "taxRate": 21,
        "taxAmount": 1.39
      }
    ],
    "businessName": "Test Company",
    "businessAddress": "Jovana Tomaševića 9",
    "businessCity": "Bar",
    "locationName": "Test Poslovna Jedinica",
    "locationAddress": "Njegoševa 99",
    "locationCity": "Podgorica",
    "tin": "12345678",
    "vatId": "123/12-000",
    "invoiceImagePngBase64": null,
    "invoiceImagePdfBase64": null,
    "invoiceImageHtml": null
  },
  "receiptImageBase64": "iVBORw0KGgoAAAANSUhEUgAAAYAAAARwCAAAAADGBtzdAAAuFUlEQVR42u2dibLsuKpE+f+f5sV9fXZZQIIkz0MS0adrV3mQtWyhASeitEtNvna98t9/BHAdgVvV//cA3Ov+/yIA+gDbDsjfZ/kz/7VtvH+/t1st… [skraćeno]",
  "print": true,
  "receiptLayout": "Slip",
  "renderReceiptImage": false,
  "receiptImageFormat": "Png",
  "skipEftPos": false,
  "autoGenerated": false
}