ELV LPFR — Vodič za integraciju ESIR-a

Za koga je: programeri i tehničari ESIR softvera (fiskalne kase) koji su kupili licencu za ELV LPFR i povezuju svoj ESIR sa njim.
Proizvod: ELV LPFR, verzija 2 · akreditacija Poreske uprave #1698 · šifra proizvođača 8S-0002 · proizvođač ELV d.o.o.
Podrška: [email protected]

Veb verzija: https://allurepos.com/lpfr-api.html

Ukratko#

• ELV LPFR je program za Windows. Radi na računaru na kome je čitač sa karticom Bezbednosnog elementa.
• ESIR mu šalje zahteve preko HTTP-a, na adresu http://localhost:8888/api/v3.
• Posle svakog pokretanja kartica je zaključana. ESIR ili operater mora da unese PIN.
• Račun se potpisuje pozivom POST /api/v3/invoices. Odgovor sadrži broj računa, žurnal, QR kod i potpis.
• ESIR štampa žurnal i QR kod i čuva ceo odgovor.
• Svaki račun šaljite sa zaglavljem RequestId. Ako se odgovor izgubi, račun preuzmite sa GET /api/v3/invoices/{RequestId}. Ne šaljite ga ponovo naslepo.
• Stanje uređaja čitajte sa GET /api/v3/status (polja gsc i mssc).

1. Šta vam treba#

2. Instalacija za 5 minuta#

1. Izaberite pravi paket:

   • za produkcionu karticu preuzmite paket „Produkcija" u „Moje licence";
   • za karticu za testiranje zatražite test paket od podrške: [email protected].

   Nikada ne pokrećite test paket (od podrške) sa produkcionom karticom, niti paket „Produkcija" sa karticom za testiranje. ELV LPFR odbija neusklađeno okruženje (mssc 8215) samo između sopstvenih podešavanja. Karticu sa paketom ne poredi. Zato je izbor paketa vaš posao.

   Po želji proverite otisak preuzetog fajla i uporedite ga sa vrednošću u „Moje licence":

   certutil -hashfile <preuzeti-paket>.zip SHA256

2. Raspakujte ceo ZIP u bilo koji folder, na primer u Preuzimanja. Ne pokrećite program iz samog ZIP-a. Taj folder služi samo za instalaciju: program i podaci posle toga žive na stalnim mestima iz koraka 6. Važno: pri prvoj instalaciji Setup preuzima podešavanja, među njima adresu SUF-a (produkcija ili test), iz fajla .env koji je u istom folderu kao ELV-LPFR-Setup.exe. Zato pokrenite Setup iz raspakovanog foldera onakvog kakav jeste i ne odvajajte ELV-LPFR-Setup.exe od njegovog .env. Bez tog .env (Setup pokrenut iz samog ZIP-a, bez raspakivanja, ili kopiran sam) Setup prvu instalaciju odbija i ne instalira ništa. Postojeća instalacija pri ažuriranju zadržava sopstvena podešavanja.

3. Umetnite karticu u čitač.

4. Dvoklik na ELV-LPFR-Setup.exe. Windows traži potvrdu Administratora: potvrdite je. To je jedino pitanje te vrste pri instalaciji. Prozor Setup-a ne zatvarajte dok ne završi.

5. Windows SmartScreen može jednom da prikaže „Windows je zaštitio vaš računar". Kliknite „Više informacija", pa „Pokreni svakako". To se radi jednom po računaru.

6. Instalacija se završi za nekoliko sekundi. Program i njegova podešavanja (.env) se postavljaju u C:\Program Files\ELV LPFR\, a podaci (baza lpfr.sqlite, licenca) u C:\ProgramData\ELV LPFR\. ELV LPFR se pokreće sam, bez prozora, pri svakoj prijavi korisnika na Windows, a operaterska stranica se otvara. Svaki korak se upisuje u C:\ProgramData\ELV LPFR\instalacija.log (to pošaljite podršci ako nešto pođe naopako). Setup ispisuje i red SUF: … (PRODUKCIJA / production), SUF: … (TEST / sandbox) ili SUF: … (nepoznato / unknown), a kada adresa SUF-a nije podešena, SUF: (nije podesen / not set). Da je okruženje pravo (test ili produkcija) vidite i u odgovoru status ispod: polje "taxCoreApi" sa paketom „Produkcija" ne sadrži sandbox, a sa test paketom (od podrške) je https://api.sandbox.suf.purs.gov.rs.

7. Operaterska stranica http://localhost:8888/ otvara se sama u pregledaču. Na vrhu piše „Unesite PIN kartice". Upišite PIN i kliknite „Otključaj karticu".

   Šta treba da vidite: stranica najavljuje „Windows će posle toga tražiti isti PIN još jednom."

8. Odmah zatim Windows otvara svoj prozor „Smart Card" i traži isti PIN još jednom. Unesite ga i potvrdite. Bez toga se računi izdaju, ali podaci ne stižu Poreskoj upravi. Ako ne vidite prozor, pogledajte traku zadataka.

   Šta treba da vidite: obaveštenje „Konfiguracija preuzeta sa SUF-a: …" i, na vrhu, „Spremno za izdavanje računa".

9. Licenca: na operaterskoj stranici otvorite odeljak „Licenca" → „Aktivacioni kod od prodavca". Upišite kod, kliknite „Aktiviraj" i potvrdite Windows prozor Administratora. Potreban je internet. Sa karticom za testiranje stanje licence je „Nije potrebna" i ovaj korak preskačete.

10. Automatsko pokretanje je već uključeno instalacijom. Posle ponovnog pokretanja ELV LPFR-a (ili računara) ponovo unesite PIN (koraci 7 i 8). Po potrebi operatersku stranicu otvorite ručno: http://localhost:8888/. Posle instalacije ne koristite ni pokreni.cmd, ni autostart-ukljuci.cmd, ni autostart-iskljuci.cmd, ni ELV-LPFR.exe iz ZIP foldera ni iz starog foldera: ELV LPFR se pokreće sam iz C:\Program Files\ELV LPFR\.

Posebni slučajevi instalacije:

• Ažuriranje: raspakujte novi paket i pokrenite novi ELV-LPFR-Setup.exe. ELV LPFR se zaustavlja uredno (račun koji je u toku se završava), prethodni program ostaje sačuvan u C:\Program Files\ELV LPFR\prethodna-verzija\, program se zamenjuje, a podaci, licenca i podešavanja (.env, mrežna i ESIR podešavanja) ostaju; automatsko pokretanje ostaje za istog korisnika Windows-a. Ako se ELV LPFR ne može zaustaviti, ako je otvoren još jedan prozor ELV LPFR-a ili ako je instalirana novija verzija od one u Setup-u, ništa se ne menja i Setup kaže zašto. Ako kopiranje ne uspe, prethodna verzija se vraća.
• Ranija instalacija iz ZIP-a (0.8.2–0.8.7): Setup je pronalazi. Taj folder ostaje folder sa podacima (ništa se ne premešta i ne briše), a program se zatim pokreće iz C:\Program Files\ELV LPFR\. Taj folder sada čuva fiskalne podatke ELV LPFR-a (lpfr.sqlite, licenca): nikada ga ne brišite i ne premeštajte, čak ni kada je u Preuzimanja ili na radnoj površini. Kada se usvajanje završi, iz tog foldera više ništa ne pokrećite: ni pokreni.cmd, ni autostart-ukljuci.cmd, ni autostart-iskljuci.cmd, ni ELV-LPFR.exe. Stari autostart-iskljuci.cmd (0.8.2–0.8.7) briše zadatak „ELV LPFR“ koji je napravio Setup, pa se ELV LPFR posle sledeće prijave ne bi pokrenuo. Ako takvih foldera ima više od jednog, Setup staje i traži da se obratite podršci ([email protected]).
• Zaštita od druge instalacije: posle instalacije ELV-LPFR.exe 0.8.8 ili noviji pokrenut iz bilo kog drugog foldera ne radi (izlazni kod 5) i javlja gde je ELV LPFR instaliran. Tako ne može da nastane druga instalacija bez podataka i licence. Stari ELV-LPFR.exe (0.8.2–0.8.7) u folderu koji je Setup preuzeo nema tu proveru: ne pokrećite ga. autostart-ukljuci.cmd i autostart-iskljuci.cmd iz paketa 0.8.8 (novi ZIP) ne menjaju automatsko pokretanje instaliranog ELV LPFR-a. Tu proveru imaju samo primerci iz paketa 0.8.8: stari (0.8.2–0.8.7) je nemaju, a stari autostart-iskljuci.cmd briše zadatak instaliranog ELV LPFR-a. Zato se iz starog foldera ne pokreće ništa.
• Računar sa AllurePOS kasom: Setup nije potreban i ne instalira ništa (kasa ima sopstveni ELV LPFR).

Kada je sve u redu, operaterska stranica pokazuje:

• na vrhu: „Spremno za izdavanje računa";
• u odeljku „Licenca": stanje „Važeća" i datum „Važi do" (sa karticom za testiranje: „Nije potrebna");
• u panelu „Uređaj": „Pristup za ESIR" = „Samo ovaj računar" (osim ako ste uključili rad na mreži, poglavlja 3.2 i 3.6);
• obaveštenje da su poreske stope i adresa za verifikaciju preuzete sa SUF-a.

Provera iz komandne linije. Na Windows-u uvek kucajte curl.exe, a ne curl: u PowerShell-u je curl drugi program, koji ne prikazuje telo odgovora kada stigne greška. Na novoj instalaciji prvi /status može da traje do oko 30 sekundi (čeka podatke sa SUF-a), zato --max-time 60.

curl.exe -i http://localhost:8888/api/v3/attention
curl.exe http://localhost:8888/api/v3/device-info
curl.exe --max-time 60 http://localhost:8888/api/v3/status

Šta treba da vidite:

• attention: HTTP/1.1 200 OK, bez tela odgovora.
• device-info: "manufacturerCode":"8S-0002", "softwareVersion":"verzija 2", "productName":"ELV LPFR".
• status: "gsc":["0100"], "mssc":[]. Polje "taxCoreApi" sa paketom „Produkcija" ne sadrži sandbox.

2.1 Kako se menja .env#

Neka podešavanja (port, čitač, rad na mreži) su u fajlu .env.

1. Fajl .env je pored programa: C:\Program Files\ELV LPFR\.env (i kod ranije instalacije iz ZIP-a koju je Setup preuzeo; .env u starom folderu se više ne čita). Već sadrži sve redove koji se pominju u ovom vodiču (PORT=8888, PCSC_READER_NAME=, LPFR_LISTEN=, ESIR_TOKEN=, a od izdanja paketa 0.8.6 i LPFR_LAN_TRUST=). Neki su prazni.
2. Otvorite ga u Notepad-u pokrenutom kao Administrator (Windows štiti folder Program Files; bez toga se izmena ne može sačuvati).
3. Upišite vrednost iza znaka = u postojećem redu. Ne dodajte isti red drugi put.
4. Sačuvajte fajl u kodiranju UTF-8.
5. Ponovo pokrenite ELV LPFR (2.2). Vrednosti se čitaju samo pri pokretanju.

Ostale redove ne menjajte. Paket je već podešen za svoje okruženje.

2.2 Zaustavljanje i ponovno pokretanje#

• U Task Manager-u (Upravljač zadacima) pronađite ELV-LPFR.exe i završite zadatak. Uradite to kada se ne izdaje račun. Zatim se odjavite i ponovo prijavite na Windows (ELV LPFR se pokreće sam).
• Posle svakog pokretanja ponovo unesite PIN.
• Foldere sa podacima nikada ne brišite.

2.3 Nova verzija programa#

• Pokrenite novi ELV-LPFR-Setup.exe (opis: odeljak „Posebni slučajevi instalacije“ u ovom poglavlju, stavka „Ažuriranje“). Ne kopirajte fajlove ručno preko instalacije.
• Podaci (.env, lpfr.sqlite, folder licenca\) ostaju na svom mestu i ne smeju se izgubiti.
• Ako nešto pođe naopako, pošaljite C:\ProgramData\ELV LPFR\instalacija.log podršci ([email protected]).

3. Povezivanje ESIR-a#

ELV LPFR ima tri režima pristupa za ESIR. Trenutni režim piše na operaterskoj stranici, panel „Uređaj" → „Pristup za ESIR".

• Za telefon ili tablet sa aplikacijom Poreske uprave postoji jedno dugme: „Poveži telefon ili tablet (ESIR Poreske uprave)" (3.6). Dugme „Isključi pristup sa mreže (Administrator)" vraća „Samo ovaj računar".
• Režim sa tokenom je u odeljku „Napredno: ESIR sa tokenom", dugmad „Dozvoli ESIR-e sa mreže (Administrator)" i „Samo ovaj računar (Administrator)" (3.2).
• Svaka promena traži potvrdu Administratora Windows-a (UAC) i važi odmah, bez ponovnog pokretanja. Ako ne može odmah (na primer port drži drugi program), podešavanje se čuva, a stranica kaže „Promena važi posle ponovnog pokretanja ELV LPFR-a." Tada ELV LPFR ponovo pokrenite (2.2).
• Isti korak Administratora pravi i pravilo zaštitnog zida Windows-a „ELV LPFR (ESIR)": dolazne TCP veze na port ELV LPFR-a, za sve mrežne profile. U režimu bez tokena pravilo važi samo za lokalnu podmrežu, a u režimu „Mreža (LAN)" za sve adrese. Povratak na „Samo ovaj računar" briše pravilo.
• Kada je režim podešen u .env (LPFR_LISTEN), stranica ga ne menja. Piše: „Režim je podešen u .env (LPFR_LISTEN) i menja se tamo, ne na ovoj stranici."
• Izdanje paketa piše u „Moje licence" („Izdanje paketa"). Jedno dugme i promena bez ponovnog pokretanja postoje od izdanja 0.8.7. Izdanje 0.8.6 ima treći režim i pravilo zaštitnog zida, ali sa posebnim dugmadima i uz ponovno pokretanje posle svake promene. Stariji paketi znaju samo prva dva režima.

3.1 ESIR na istom računaru (podrazumevano)#

Osnovna adresa je http://localhost:8888/api/v3 (ili http://127.0.0.1:8888/api/v3). Token nije potreban. Ništa se ne podešava.

• U podrazumevanom režimu ELV LPFR sluša samo na 127.0.0.1 i ::1.
• Zahtev na mrežnu adresu računara (npr. http://192.168.1.20:8888), čak i sa istog računara, zato ne dobija nikakav HTTP odgovor: veza se odbija. Token se tada uopšte ne proverava. Pravilo o tokenu važi samo u radu na mreži (3.2 i 3.6).
• Zahtev na neko drugo ime koje pokazuje na 127.0.0.1 dobija HTTP 403. To je zaštita od veb-stranica koje se predstavljaju kao lokalni program. Dozvoljeni su localhost, 127.0.0.1 i ime računara.
• Port se menja u .env (PORT, poglavlje 2.1). Tada se menja i adresa operaterske stranice.

3.2 ESIR na drugom računaru (rad na mreži, LAN) [ELV]#

Podrazumevano ELV LPFR prima zahteve samo sa računara na kome radi. ESIR koji ne može da šalje token (na primer aplikacija „ESIR Poreska uprava RS" na telefonu) povežite po poglavlju 3.6. Za ESIR na drugom računaru:

1. Uključite rad na mreži, na jedan od dva načina:
   • na operaterskoj stranici, panel „Uređaj" → „Napredno: ESIR sa tokenom" → „Dozvoli ESIR-e sa mreže (Administrator)", pa potvrdite Windows prozor Administratora. ELV LPFR sam pravi token i pravilo zaštitnog zida (korak 5). Do izdanja 0.8.6 dugme je direktno u panelu „Uređaj".
   • ili u .env (poglavlje 2.1) popunite LPFR_LISTEN=lan i ESIR_TOKEN=<najmanje 16 znakova>. Vrednost iz .env ima prednost nad stranicom.
2. Promena na stranici važi odmah (izdanje 0.8.7 ili novije). Ponovo pokrenite ELV LPFR (2.2) posle promene u .env, sa starijim paketom, ili kada stranica kaže „Promena važi posle ponovnog pokretanja ELV LPFR-a."

   Šta treba da vidite: na stranici „Pristup za ESIR" = „Mreža (LAN)"; posle pokretanja u ispisu L-PFR on *:8888 (LAN, X-ESIR-Token; UID …, SUF …, BE pcsc).

3. Na računaru sa ELV LPFR-om, na operaterskoj stranici, kliknite „Prikaži" pored „Deljeni token (X-ESIR-Token)". Prepišite token u podešavanja ESIR-a.
4. U ESIR-u podesite adresu http://<IP-adresa-računara-sa-ELV-LPFR-om>:8888/api/v3. Svaki zahtev mora da nosi zaglavlje X-ESIR-Token: <token>.
5. Zaštitni zid Windows-a na računaru sa ELV LPFR-om mora da propusti dolazne TCP veze na port 8888. Kada rad na mreži uključite na stranici, pravilo „ELV LPFR (ESIR)" je već napravljeno i ovaj korak preskačete. Ručno pravilo treba samo kada je režim podešen u .env (ili sa paketom starijim od 0.8.6). Primer komande (pokrenuti kao Administrator):
   netsh advfirewall firewall add rule name="ELV LPFR 8888" dir=in action=allow protocol=TCP localport=8888

   Šta treba da vidite: Windows odgovara Ok.

Probni poziv sa računara na kome je ESIR:

curl.exe --max-time 60 http://192.168.1.20:8888/api/v3/status -H "X-ESIR-Token: <token>"

Šta treba da vidite: JSON sa poljima "gsc" i "mssc". Bez tokena ili sa pogrešnim: {"message":"Unauthorized"} (HTTP 401).

Više ESIR-a na jedan ELV LPFR je dozvoljeno. Više kasa sa drugih računara može da radi sa istim ELV LPFR-om preko mreže. Sve koriste isti token. RequestId mora biti jedinstven za sve kase zajedno (na primer sa oznakom kase na početku), jer ELV LPFR ima jednu zajedničku bazu.

Šta još treba da znate:

• Zahtev bez tokena ili sa pogrešnim tokenom ne stiže ni do jedne funkcije ELV LPFR-a.
• Ako je rad na mreži zatražen, a token od bar 16 znakova nije podešen, ELV LPFR ostaje na „Samo ovaj računar". To javlja na operaterskoj stranici.
• Programi na samom računaru sa ELV LPFR-om i dalje rade preko localhost, bez tokena.
• Windows prozor „Smart Card" za drugi unos PIN-a (korak 8 u poglavlju 2) uvek se pojavljuje na računaru sa ELV LPFR-om. Posle svakog pokretanja neko mora tamo da ga potvrdi.
• Blokada unosa PIN-a (poglavlje 6.4) otključava se samo na operaterskoj stranici tog računara.

3.3 Zaglavlja HTTP zahteva#

Telo zahteva šaljite u kodiranju UTF-8. Poreske oznake mogu biti ćirilične (npr. Ж).

3.4 ESIR u veb-pregledaču ili u Electron / Tauri / WebView aplikaciji [ELV]#

• ELV LPFR ne šalje CORS zaglavlja (Access-Control-Allow-*). Veb-stranica sa druge adrese zato ne može direktno da čita njegove odgovore.
• Svaki prikaz zasnovan na pregledaču šalje zaglavlje Origin. To važi i za renderer u Electron-u, Tauri-ju i WebView-u.
• POST /pin sa tuđim zaglavljem Origin dobija HTTP 403 {"ok":false,"reason":"cross-origin"}.
• Rešenje: ELV LPFR pozivajte iz pozadinskog dela ESIR-a (server, glavni proces Electron-a, Rust deo Tauri-ja, lokalni servis), ne iz JavaScript-a u prikazu.

3.5 Vreme čekanja i ponovno slanje#

• ELV LPFR ne prepoznaje duplikate. Isti račun poslat dva puta daje dva fiskalna računa. Nikada ne ponavljajte POST /invoices naslepo.
• Svaki račun šaljite sa novim, jedinstvenim RequestId.
• Vreme čekanja u ESIR-u postavite na najmanje 30–60 sekundi. Na novoj instalaciji prvi zahtev može da sačeka preuzimanje podataka sa SUF-a (do 15 sekundi po pozivu, dva poziva). I potpisivanje karticom traje.
• Kada odgovor ne stigne (isteklo vreme, prekinuta veza):
  1. pozovite GET /api/v3/invoices/{RequestId};
  2. HTTP 200: račun je izdat. Koristite taj odgovor;
  3. HTTP 404: račun nije sačuvan. Pre novog slanja pogledajte GET /status. Ako mssc sadrži 8204 (potpisivanje prekinuto, oporavak u toku), sačekajte da šifra nestane i ponovite korak 1;
  4. tek tada pošaljite račun ponovo, sa novim RequestId. Zapamtite oba ID-ja uz isti račun u ESIR-u.
• Greška 2220 (kartica prestala da odgovara usred potpisivanja) rešava se na isti način.
• GET /invoices/{RequestId} radi samo sa karticom u čitaču i unetim PIN-om. Posle restarta prvo unesite PIN.
• Grešku 2400 ne ponavljajte automatski. Prvo pročitajte mssc (poglavlje 6.3).
• POST /pin ne šaljite u petlji. ELV LPFR propušta najviše jedan pokušaj u sekundi. Posle dva uzastopna pogrešna PIN-a zaustavlja dalji unos.

3.6 Uređaji iz lokalne mreže bez tokena (ESIR aplikacija Poreske uprave) [ELV]#

Aplikacija Poreske uprave „ESIR Poreska uprava RS" (Google Play) za telefon i tablet traži samo protokol, IP adresu i port L-PFR-a. Zaglavlje X-ESIR-Token ne može da pošalje. Za takav ESIR služi režim „Lokalna mreža ovog računara (bez tokena)". Potreban je paket ELV LPFR 0.8.6 ili noviji. Jedno dugme i promena bez ponovnog pokretanja postoje od izdanja 0.8.7.

Kako radi:

• Uređaj čija je IPv4 adresa u istoj privatnoj podmreži (10.x.x.x, 172.16–31.x.x, 192.168.x.x) kao jedna od mrežnih kartica ovog računara ne šalje token.
• Uređaj iz druge podmreže, preko VPN-a, sa javnom adresom ili preko IPv6 i dalje mora da šalje X-ESIR-Token. Zato ELV LPFR i u ovom režimu pravi token („Prikaži" pored „Deljeni token (X-ESIR-Token)"). Bez tokena takav zahtev dobija HTTP 401. Takav uređaj, uz token, traži i ručno pravilo zaštitnog zida iz 3.2 (korak 5), jer pravilo koje pravi stranica u ovom režimu propušta samo lokalnu podmrežu. Napravite ga posle promene režima na stranici, jer od izdanja 0.8.7 stranica pri svakoj promeni briše pravilo „ELV LPFR 8888".
• Programi na samom računaru sa ELV LPFR-om i dalje rade preko localhost, bez tokena.

Uključivanje (izdanje 0.8.7 ili novije):

1. Na operaterskoj stranici, panel „Uređaj", kliknite „Poveži telefon ili tablet (ESIR Poreske uprave)". Stranica prvo traži potvrdu, sa upozorenjem „Svaki uređaj u lokalnoj mreži ovog računara, i gost na istoj bežičnoj mreži, moći će da izdaje račune dok je PIN unet." Potvrdite, pa potvrdite i jedan Windows prozor Administratora. Taj jedan korak:
   • uključuje režim „Lokalna mreža ovog računara (bez tokena)";
   • pravi pravilo zaštitnog zida „ELV LPFR (ESIR)", samo za lokalnu podmrežu;
   • briše preusmeravanja porta (netsh interface portproxy, sve četiri vrste) na portu ELV LPFR-a;
   • briše staro ručno pravilo „ELV LPFR 8888". Pravila sa drugim imenima ostaju.
2. Promena važi odmah, bez ponovnog pokretanja.

   Šta treba da vidite: „Pristup sa mreže je uključen, odmah, bez ponovnog pokretanja." i „Pristup za ESIR" = „Lokalna mreža ovog računara (bez tokena)". Ako stranica umesto toga kaže „Promena važi posle ponovnog pokretanja ELV LPFR-a." (na primer port drži drugi program), podešavanje je sačuvano: ponovo pokrenite ELV LPFR (2.2).

3. Stranica zatim pokazuje šta se upisuje u aplikaciju: „U aplikaciji „ESIR Poreska uprava RS": PFR server → L-PFR · HTTP · <adresa> · port <port>". Adresa je privatna IPv4 adresa prave mrežne kartice ovog računara. Virtuelni adapteri (na primer vEthernet ili WSL) se ne prikazuju. Ispod je savet za DHCP rezervaciju: u ruteru zaključajte tu adresu za ovaj računar.
4. Povežite telefon ili tablet na istu mrežu kao računar sa ELV LPFR-om. U aplikaciji „ESIR Poreska uprava RS" izaberite PFR server → L-PFR, protokol HTTP, adresu sa stranice i port 8888. Token se ne unosi.
5. Kliknite „Proveri vezu" (Administrator nije potreban). Spisak sa ✓ i ✗ pokazuje: da li ELV LPFR prima zahteve sa mreže (port); da li postoji pravilo zaštitnog zida „ELV LPFR (ESIR)" (samo lokalna mreža ili sve adrese); da nema preusmeravanja porta (portproxy), jer bi sa njim telefon dobio grešku 403; adresu ovog računara u lokalnoj mreži. Kod svakog ✗ piše da kliknete „Poveži telefon ili tablet".

Isključivanje: „Isključi pristup sa mreže (Administrator)" vraća „Samo ovaj računar", takođe odmah, i briše pravilo „ELV LPFR (ESIR)".

Preko .env, umesto stranice: popunite LPFR_LISTEN=lan i LPFR_LAN_TRUST=subnet (poglavlje 2.1). Token tada nije obavezan. Vrednost iz .env ima prednost nad stranicom, a stranica tada ne menja režim. Ako red LPFR_LAN_TRUST= ne postoji (.env iz starijeg paketa), dodajte ga jednom. Zatim ponovo pokrenite ELV LPFR (2.2) i ručno podesite zaštitni zid (3.2, korak 5).

Šta treba da vidite: u ispisu L-PFR on *:8888 (LAN, lokalna mreža bez tokena + X-ESIR-Token; UID …, SUF …, BE pcsc).

Sa izdanjem 0.8.6: dugme „Dozvoli uređaje iz lokalne mreže bez tokena (Administrator)", a promena važi tek posle ponovnog pokretanja ELV LPFR-a (2.2). Adresu računara tada vidite komandom ipconfig.

Probni poziv sa drugog računara iz iste podmreže, bez tokena:

curl.exe --max-time 60 http://192.168.1.20:8888/api/v3/status

Šta treba da vidite: JSON sa poljima "gsc" i "mssc". HTTP 401 znači da taj računar nije u podmreži računara sa ELV LPFR-om (7.1).

Bezbednost:

• Dok je PIN unet, račune može da izdaje svaki uređaj iz te mreže, i gost na istoj bežičnoj mreži. Goste držite na posebnoj bežičnoj mreži (gostujući Wi-Fi).
• Svaki uređaj primljen bez tokena upisuje se jednom po pokretanju programa u izveštaj o greškama (operaterska stranica, „Greške"), sa šifrom ESIR_LAN_DEVICE i porukom request from <ip> accepted without a token (this PC's local network). Tako vidite koji uređaji šalju zahteve.
• Ostala pravila iz 3.2 važe i ovde: RequestId jedinstven za sve uređaje zajedno; Windows prozor „Smart Card" i otključavanje unosa PIN-a samo na računaru sa ELV LPFR-om.

4. API pregled#

Osnovna adresa: http://localhost:8888/api/v3. Putanje ne razlikuju velika i mala slova. Tela su JSON (UTF-8). Najveće telo zahteva je 1 MB.

Napomene:

• Putanje / i /ui/... pripadaju operaterskoj stranici. Nisu deo API-ja za ESIR.
• Nepoznata putanja dobija 404 {"message":"Bad Request","modelState":[{"property":"","errors":["2806"]}]}.
• Lokalno iščitavanje je najlakše pokrenuti sa operaterske stranice (Pojmovnik, 5 koraka). API prihvata samo priključene izmenjive medijume i putanje iz LOCAL_READOUT_ROOTS.
• POST /invoices tehnički prima i niz računa. Ne koristite to (5.8).

4.1 GET /status — primer (ilustrativno — ne šaljite)#

Primer je sastavljen prema kodu ELV LPFR-a, sa test paketom (sandbox). Vrednosti sa … zavise od kartice i instalacije. Poreska grupa je primer iz test okruženja.

{
  "isPinRequired": false,
  "auditRequired": false,
  "sdcDateTime": "2026-10-04T14:05:09.123+02:00",
  "protocolVersion": "1.0.0.0",
  "softwareVersion": "verzija 2",
  "secureElementVersion": "…",
  "hardwareVersion": "N/A",
  "deviceSerialNumber": "8S-0002-…",
  "mrc": "8S-0002-…",
  "make": "ELV d.o.o.",
  "model": "ELV LPFR",
  "uid": "…",                       // JID kartice; null kada kartica nije u čitaču
  "taxCoreApi": "https://api.sandbox.suf.purs.gov.rs",   // Test paket; kod paketa „Produkcija" bez "sandbox"
  "lastInvoiceNumber": "…",         // "" dok uređaj nije izdao nijedan račun
  "supportedLanguages": ["sr-Cyrl-RS", "en-US"],
  "currentTaxRates": {
    "validFrom": "2023-10-08T06:40:00Z",
    "groupId": 8,
    "taxCategories": [
      { "name": "VAT", "categoryType": 0, "orderId": 6,
        "taxRates": [ { "rate": 10.00, "label": "A" }, { "rate": 0.00, "label": "B" }, { "rate": 19.00, "label": "Ж" } ] },
      …
    ]
  },
  "allTaxRates": [ … ],
  "mssc": [],
  "gsc": ["0100"]
}

Šta ESIR koristi iz /status:

4.2 GET /device-info — primer [ELV]#

{
  "manufacturer": "ELV d.o.o.",
  "manufacturerCode": "8S-0002",
  "softwareVersion": "verzija 2",
  "productName": "ELV LPFR",
  "serialNumber": "<JID kartice>"
}

Radi i bez kartice i bez PIN-a. serialNumber je JID kartice pročitan pri pokretanju programa. Ako kartica nije bila u čitaču pri pokretanju, serialNumber ne pokazuje stvarnu karticu (može biti prazan ili vrednost iz konfiguracije). JID umetnute kartice uvek čitajte iz GET /status → uid.

4.3 GET /environment-parameters — primer (test okruženje)#

Odgovor je doslovno ono što SUF isporučuje. Primer je iz test (sandbox) okruženja:

{
  "organizationName": "Министарство финансија - Пореска управа - Централа",
  "serverTimeZone": "Central Europe Standard Time",
  "street": "Саве Машковића 3-5",
  "city": "Београд",
  "country": "RS",
  "endpoints": {
    "taxpayerAdminPortal": "https://tap.sandbox.suf.purs.gov.rs:443/",
    "taxCoreApi": "https://api.sandbox.suf.purs.gov.rs:443/",
    "vsdc": "https://vsdc.sandbox.suf.purs.gov.rs:443/",
    "root": "https://sandbox.suf.purs.gov.rs:443/v/?vl="
  },
  "environmentName": "СУФ Развој",
  "logo": "https://sandbox.suf.purs.gov.rs:443/DownloadContent/TAlogo.png",
  "ntpServer": "http://0.pool.ntp.org:80/",
  "supportedLanguages": ["sr-Cyrl-RS", "en-US"]
}

5. Izdavanje računa korak po korak#

5.1 Preporučeni tok#

1. Pri pokretanju ESIR-a: GET /attention (200 = ELV LPFR radi), pa GET /status.
2. Ako gsc sadrži 1300: prikažite kasiru „Umetnite karticu u čitač". Čekajte da 1300 nestane.
3. Ako gsc sadrži 1500, pogledajte prvo mssc:
   • ako mssc sadrži 8201 ili 8202: ne šaljite PIN preko API-ja. Odgovor bi bio 423 "1999", čak i sa tačnim PIN-om. Uputite kasira da PIN unese na operaterskoj stranici (6.4);
   • inače tražite PIN od kasira i pošaljite ga sa POST /pin. Na "0100" podsetite kasira da Windows na računaru sa ELV LPFR-om traži isti PIN još jednom.
4. Iz currentTaxRates pročitajte važeće poreske oznake. Proverite da svaki artikal ima oznaku koja postoji.
5. Za svaki račun: POST /invoices, sa zaglavljima Content-Type, RequestId i (po želji) Accept-Language. Jedan račun po zahtevu.
6. Iz odgovora odštampajte žurnal i QR kod. Sačuvajte ceo odgovor uz svoj račun.
7. Tokom rada: periodično pozivajte GET /status, na primer jednom u minuti. Prikažite kasiru upozorenja (1400, mssc).

Unos PIN-a preko API-ja (za proveru; u svakodnevnom radu PIN unosite kroz ESIR ili na operaterskoj stranici):

curl.exe -X POST http://localhost:8888/api/v3/pin -H "Content-Type: application/json" -d "PIN-KARTICE"

• Umesto PIN-KARTICE ide stvarni PIN.
• Pažnja: PIN otkucan u komandnoj liniji može da ostane zapisan u istoriji komandi. Posle provere zatvorite prozor i ne delite snimke ekrana.
• Telo može biti i JSON: {"pin":"1234"}. Tako ga obično šalje ESIR iz svog koda.
• Odgovor je goli JSON string: "0100" (prihvaćeno), "2100" (pogrešan PIN), "2110" (kartica zaključana), "1999" (unos PIN-a je blokiran, 6.4).

5.2 Zahtev: običan račun, gotovina [PURS]#

Primer A — za kopiranje. Najmanji ispravan zahtev (stvarni zahtev iz PURS-ovog referentnog snimka):

{
  "invoiceType": 0,
  "transactionType": 0,
  "payment": [
    { "amount": 110, "paymentType": 1 }
  ],
  "items": [
    { "name": "Hleb", "unitPrice": 110, "quantity": 1, "labels": ["A"], "totalAmount": 110 }
  ]
}

Sačuvajte ga kao racun.json (UTF-8) i pošaljite. Slanje iz fajla radi isto u cmd-u i u PowerShell-u i ne kvari ćirilične oznake:

curl.exe -i --max-time 60 -X POST http://localhost:8888/api/v3/invoices -H "Content-Type: application/json" -H "Accept-Language: sr-Cyrl-RS" -H "RequestId: esir-000123" --data-binary "@racun.json"

Šta treba da vidite: HTTP/1.1 200 OK, zaglavlje RequestId: esir-000123 i telo koje počinje sa {"requestedBy":"<JID>". U telu su invoiceNumber, verificationUrl, verificationQRCode i journal.

Isti račun sa neobaveznim poljima (ilustrativno — ne šaljite; skraćeno sa …):

{
  "invoiceType": 0,
  "transactionType": 0,
  "cashier": "Milica Kovačević",
  "buyerId": "10:105255401",
  "buyerCostCenterId": "20:01234567",
  "invoiceNumber": "<ESIR broj>",
  "dateAndTimeOfIssue": "2026-09-16T08:00:00.000+02:00",
  "payment": [ { "amount": 13958.02, "paymentType": 1 } ],
  "items": [
    { "name": "Cedeni Sok/l", "unitPrice": 349.99, "quantity": 1.5, "labels": ["Ж"], "totalAmount": 524.99, "gtin": "12345678" },
    …
  ]
}

5.3 Polja zahteva#

Pravila u koloni „Provera" sprovodi sam ELV LPFR. U zagradi je šifra greške.

Greška u polju se vraća sa tačnom putanjom polja. Primer (nepostojeća poreska oznaka):

{ "message": "Bad Request", "modelState": [ { "property": "items[0].labels[0]", "errors": ["2310"] } ] }

5.4 Odgovor: šta ESIR štampa i čuva#

Odgovor na Primer A (ilustrativno — ne šaljite). Vrednosti su iz PURS-ovog referentnog snimka, sa poreskom stopom A = 10% kao u primeru 4.1. Oblik i spisak polja su ELV LPFR-ovi. Dugačke vrednosti su skraćene sa ….

{
  "requestedBy": "K6Y3AGSV",
  "signedBy": "K6Y3AGSV",
  "sdcDateTime": "2026-09-15T22:31:52.000Z",
  "invoiceCounter": "184/749ПП",
  "invoiceCounterExtension": "ПП",
  "invoiceNumber": "K6Y3AGSV-K6Y3AGSV-749",
  "taxItems": [
    { "categoryType": 0, "label": "A", "amount": 10, "rate": 10, "categoryName": "VAT" }
  ],
  "totalCounter": 749,
  "transactionTypeCounter": 184,
  "totalAmount": 110,
  "businessName": "ELV d.o.o.",
  "tin": "RS114111400",
  "locationName": "ELV d.o.o.",
  "address": "Beogradska 235c",
  "district": "NOT APPLICABLE",
  "taxGroupRevision": …,
  "mrc": "8S-0002-…",
  "messages": "Success",
  "signature": "…",
  "encryptedInternalData": "…",
  "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=…",
  "verificationQRCode": "…",
  "journal": "============ ФИСКАЛНИ РАЧУН ============\r\n…"
}

Žurnal za gornji primer (srpski):

============ ФИСКАЛНИ РАЧУН ============
              RS114111400
               ELV d.o.o.
               ELV d.o.o.
            Beogradska 235c
             NOT APPLICABLE
Касир:
-------------ПРОМЕТ ПРОДАЈА-------------
Артикли
========================================
Назив   Цена         Кол.         Укупно
Hleb (A)
       110,00          1          110,00
----------------------------------------
Укупан износ:                     110,00
Готовина:                         110,00
========================================
Ознака       Име      Стопа        Порез
A             VAT   10,00%         10,00
----------------------------------------
Укупан износ пореза:               10,00
========================================
ПФР време:           16.9.2026. 00:31:52
ПФР број рачуна:   K6Y3AGSV-K6Y3AGSV-749
Бројач рачуна:                 184/749ПП
========================================
======== КРАЈ ФИСКАЛНОГ РАЧУНА =========

(Prikaz je bez završnih razmaka. U pravom odgovoru redovi zadržavaju razmake za poravnanje i odvojeni su sa \r\n.)

5.5 Jezik žurnala (Accept-Language) [PURS]#

• en ili bilo koje en-… (npr. en-US): žurnal na engleskom („FISCAL INVOICE", „Total Purchase", „SDC Time"…).
• sr, bilo koje sr-… (i sr-Latn-RS), *, nepoznat jezik ili bez zaglavlja: žurnal na srpskom, ćirilicom. Žurnala na latinici nema.
• Kada zaglavlje navodi više jezika, pobeđuje prvi podržan (uz poštovanje q vrednosti).
• Iznosi, količine i vreme (po beogradskom vremenu) pišu se isto na oba jezika.
• Podržani jezici okruženja su u GET /status → supportedLanguages.

5.6 Refundacija, kopija, avans, predračun, obuka [PURS]#

Svaka refundacija (transactionType 1), bilo koje vrste, traži referentDocumentNumber.

Primer B — za kopiranje, posle izmene dva polja. Refundacija računa iz Primera A (stvarni zahtev iz PURS-ovog referentnog snimka). Pre slanja zamenite referentDocumentNumber vrednošću invoiceNumber, a referentDocumentDT vrednošću sdcDateTime iz vašeg odgovora na Primer A. Šaljite ga isto kao Primer A, sa novim RequestId.

{
  "invoiceType": 0,
  "transactionType": 1,
  "cashier": "Tosha",
  "buyerId": "10:105255401",
  "referentDocumentNumber": "K6Y3AGSV-K6Y3AGSV-749",
  "referentDocumentDT": "2026-09-16T00:31:52+02:00",
  "payment": [ { "amount": 110, "paymentType": 1 } ],
  "items": [ { "name": "Hleb", "unitPrice": 110, "quantity": 1, "labels": ["A"], "totalAmount": 110 } ]
}

Važno [ELV]:

• Licenca nikada ne zaustavlja refundaciju, kopiju, obuku ni predračun. Kada licenca nije važeća, odbijaju se samo novi računi Promet–prodaja i Avans–prodaja (šifra 2400).
• Kako se sastavlja konačni račun posle avansa propisuje PURS za ESIR. To nije posebnost ELV LPFR-a i ovde nije opisano.

5.7 Ponovno preuzimanje računa: GET /invoices/{RequestId} [PURS]#

curl.exe http://localhost:8888/api/v3/invoices/esir-000123

Šta treba da vidite: isti JSON kao u prvom odgovoru na Primer A. Za nepoznat RequestId: HTTP 404 {"error":"not found"}.

• Vraća isti rezultat kao prvi odgovor, sa QR kodom i žurnalom.
• Traži se po RequestId koji je ESIR poslao, ne po broju računa. Poziv sa invoiceNumber vraća 404.
• Ako je isti RequestId greškom poslat više puta, vraća se samo poslednji račun.
• Radi samo sa karticom u čitaču i unetim PIN-om (inače 400 {"code":"1300"} ili {"code":"1500"}).
• POST /invoices sa istim RequestId ne vraća stari račun. Pravi novi.

5.8 Nikada ne šaljite više računa u jednom zahtevu#

POST /invoices tehnički prima i niz zahteva i vraća niz rezultata. Ne koristite to:

• svi računi u nizu dele isti RequestId, pa GET /invoices/{RequestId} posle izgubljenog odgovora vraća samo poslednji račun iz niza. Ostale ne možete da preuzmete;
• ako jedan zahtev u nizu padne, raniji su možda već potpisani, a odgovor je samo greška.

Šaljite jedan račun po zahtevu, svaki sa svojim RequestId.

6. Statusne šifre i greške#

6.1 Gde se šifre pojavljuju#

Odgovor sa greškom nikada ne nosi tekst poruke, samo šifru. Razlog [ELV] stanja vidi se u mssc, na operaterskoj stranici i u izveštaju o greškama.

6.2 Šifre iz šifrarnika [PURS]#

6.3 mssc — razlog stanja [ELV]#

mssc (Manufacturer Specific Status Codes) je zvanično polje odgovora „Get Status". ELV LPFR u njega upisuje razlog. U ispravnom stanju je prazan.

Kolona gsc pokazuje šta se tada dodaje u gsc:

• 2400 — novi računi se odbijaju;
• 1999 — samo upozorenje;
• (1500) — ništa se ne dodaje: 1500 je već u gsc jer se traži PIN. To nije blokada računa;
• — — nema promene.

Licenca (81xx):

Zaštita kartice (82xx):

Preporuka za ESIR: kada mssc nije prazan, prikažite kasiru kratku poruku i uputite ga na operatersku stranicu ELV LPFR-a. Tamo je objašnjenje i dugme za potrebnu radnju.

6.4 Tok PIN-a#

[nema kartice] gsc 1300,1500,0210
      | umetnuta kartica
      v
[kartica, PIN nije unet] gsc 1500,0210  <-- posle svakog pokretanja i vraćanja kartice
      | POST /pin  -> "0100"
      v
[spremno] gsc 0100
      | izvađena kartica -> nazad na [nema kartice], PIN se briše

Pravila ELV LPFR-a za POST /pin [ELV]:

• Šaljite tačno 4 cifre. PIN od samih cifara koji nema tačno 4 cifre (i prazno telo) dobija 423 "2100", a kartica se ne pita (ne troši se pokušaj).
• Između dva pokušaja prođe najmanje 1 sekunda. Brži zahtev se samo zadrži, ne odbija.
• Posle 2 uzastopna pogrešna PIN-a ELV LPFR zaustavlja dalje pokušaje: svaki sledeći POST /pin dobija 423 "1999" (mssc 8201), čak i sa tačnim PIN-om. Otključava se samo na operaterskoj stranici, dugmetom „Otključaj unos PIN-a". Tako se kartica čuva od trajnog zaključavanja (2110).
• Kada kartici ostanu najviše 2 pokušaja, PIN poslat iz ESIR-a dobija 423 "1999" (mssc 8202). Tada se PIN unosi samo na operaterskoj stranici.
• Posle "0100" Windows na računaru sa ELV LPFR-om jednom traži isti PIN u prozoru „Smart Card". Taj prozor mora biti potvrđen.

6.5 HTTP statusi#

7. Rešavanje problema#

7.1 Program ne radi ili ESIR ne može da se poveže#

7.2 API vraća šifru greške#

7.3 Kartica, PIN i licenca#

8. Pre nego što krenete u produkciju#

• Pravi paket za karticu. Za produkcionu karticu je preuzet i pokrenut paket „Produkcija". Test paket (od podrške) se nikada ne pokreće sa produkcionom karticom, niti obrnuto. ELV LPFR odbija neusklađeno okruženje (8215) samo između svojih podešavanja, pa je izbor paketa vaša odgovornost. Provera: GET /status → taxCoreApi i verificationUrl prvog računa ne sadrže sandbox.
• Licenca. Za produkcionu karticu: „Licenca" = „Važeća", datum „Važi do" je dobar. Pristup do https://licenca.allurepos.com (port 443) je otvoren. Licenca prati karticu: pri preseljenju na drugi računar pokrenite tamo ELV-LPFR-Setup.exe i prenesite karticu zajedno sa folderom sa podacima C:\ProgramData\ELV LPFR\ (uz zaustavljen ELV LPFR na starom računaru), i licenca i dalje važi.
• Uređaj. GET /device-info vraća 8S-0002, verzija 2, ELV LPFR.
• Autostart. Instalacija je izvršena (ELV-LPFR-Setup.exe), automatsko pokretanje je uključeno. Proba: restart računara → prijava → ELV LPFR radi → PIN unet → Windows prozor potvrđen → „Spremno za izdavanje računa".
• Sat. Usklađivanje sata u Windows-u je uključeno.
• Disk. Ima mnogo više od 100 MB slobodnog prostora.
• ESIR obrađuje stanja: 1300, 1500 (traži PIN, osim kod 8201/8202), odgovore /pin (2100, 2110, 1999), 2400 + mssc, 2210, 2310, 28xx, HTTP 401.
• RequestId. Svaki račun ima jedinstven RequestId, jedinstven i između više kasa. Posle isteka vremena ESIR prvo zove GET /invoices/{RequestId}. Nema slepog ponavljanja. Nema slanja više računa u jednom zahtevu.
• Štampa. Žurnal se štampa doslovno (40 znakova, font fiksne širine), QR kod kao GIF slika. Uz račun se čuvaju invoiceNumber, sdcDateTime, verificationUrl, signature i ceo odgovor.
• Refundacija i kopija su isprobane sa referentDocumentNumber i referentDocumentDT.
• Praćenje. ESIR periodično čita /status i prikazuje upozorenja (1400, mssc). Na operaterskoj stranici „Slanje Poreskoj upravi" broj paketa na čekanju ne raste.
• Rezervne kopije. Folder sa podacima (lpfr.sqlite, licenca\) se nikada ne briše i ne deli na delove. LPFR_MIRROR_DIR je po mogućstvu na drugom disku ili deljenom mrežnom folderu (tamo idu kopija svakog paketa i dnevna kopija baze, do 14 poslednjih). Povremeno „Izvezi sve pakete (rezerva)" na USB.
• Lokalno iščitavanje je isprobano sa USB flešom (Pojmovnik, 5 koraka).
• Jedna kartica, jedan ELV LPFR. Kartica radi samo na jednom računaru. Na tom računaru radi samo jedan primerak ELV LPFR-a.
• Rad na mreži (ako se koristi). Token je sačuvan bezbedno u svim ESIR-ima. Port 8888 je otvoren samo za računare sa ESIR-om.
• Lokalna mreža bez tokena (ako se koristi). „Proveri vezu" pokazuje samo ✓. Adresa računara je zaključana u ruteru (DHCP rezervacija). Gosti su na posebnoj bežičnoj mreži. U izveštaju o greškama (ESIR_LAN_DEVICE) su samo poznati uređaji.

9. Podrška i korisni linkovi#

Kada pišete podršci, pošaljite:

• šifru greške i tačno vreme;
• koji paket koristite („Produkcija" ili test paket od podrške);
• izlaz curl.exe --max-time 60 http://localhost:8888/api/v3/status i curl.exe http://localhost:8888/api/v3/device-info;
• po potrebi izveštaj o greškama: pri lokalnom iščitavanju na medijum se upisuje {JID}-errors.json, a poslednji zapisi su i na operaterskoj stranici („Izveštaj o greškama").

PIN kartice nikada ne šaljite podršci.