HrFiskalizator Help

Kako bi Program radio u ovom načinu u pri konfiguraciji treba odabratik način čekanja na zadatak "Server"

Server če na preddefiniranom portu (default = 8449) vračati odgovore na sljedeče upite(u zagradi skračeni upit) :

Kod prvog pokretanja programa sa ovom konfiguracijom bitno je da ako operativi sustav upita dali HrFiskalizator smije koristiti upisani port , da mu se dozvoli pristup.

Upit se upučuje na adresu http://localhost:port/fiskal?zadatak=upit

Pritom "localhost" može a u nekim slučajevima mora biti zamjenjen lokalnom ili javnom IP adresom.

Ako u postavkama nije definiran Login i Password onda če password i server biti zanemareni a server dostupan bez logina i passworda.

Defaultni Login i Password su : "login" i "password"

*Neka od korisničkih aplikacija (uključujući večinu suvremenih browsera) nemože poslati autentikaciju kroz URL string.
HrFiskalizator se ponaša kao i svaki drugi HTTP server te če prihvatiti autentikaciju kroz header.

Windows COM komponenta "WinHttp.WinHttpRequest.5.1" se naprimjer koristi na sljedeči način (primjer je u VBS ali objekat slično radi i u drugim programskim jezicima)

Testirajte ovu opciju u vašem pregledniku, a ukoliko trebate pomoč oko implementacije ovog načina komuniciranja sa HrFiskalizatorom u svoju aplikaciju, kontaktirajte me za savjet.

U nastavku upita moguči su i neki dodatni parametri prema doljnim primjerima.

Večinu upita je moguče testirati i jednostavnim upisom u web preglednik.

Svi odgovori su plain text odgovori te su utf-8 encoded izuzev HELP koji je Html odgovor te je ISO-8859-2 encoded.

Program nastoji detektirati sve potencijalne korisničke greška te vrača razne poruke o greškama koje su se dogodile pri izvođenju traženog zadatka ili dobivene od servera Porezne uprave.

Najčešča uporaba Hrfiskalizatora je da je pokrenut na računalu na kojem radi i korisnička aplikacija.

Međutim može opsluživati i više klijenata na neke od naprednih načina.

Primjer napredne višekorisničke uporabe 1

Primjer napredne višekorisničke uporabe 2

Pazi ! Kod ovog primjera komunikacija preko interneta između kase i HrFiskalizatora nema enkripciju,a primjenjuje se samo osnovna zaštita Loginom i Passwordom.

Kako bi kasa mogla komunicirati sa HrFiskalizatorom, potrebno je na ruteru Port koji koristi HrFiskalizator preusmjeriti na računalo na kojem radi.

Primjer : http://localhost:8449

Služi kako bi korisnik mogao detektirati prisutnost servera i to bez pokretanja bilo kakvih procedura unutar programa.

Ako je definiran Login i Password onda če samo ovaj poziv biti dostupan bez Logina i passworda (za detekciju servera)

Moguči povrati : HrFiskalizator on port : 8449

EXIT

Gasi program , te je korisna ako programer iz svoje aplikacije želi pokretati HrFiskalizator te ga zatvarati (recimo pri zatvaranju svoje aplikacije).

Primjer : http://localhost:8449/fiskal?zadatak=EXIT"

PING

Služi za provjeru dali program radi i odgovara na preddefinirani port

Primjer : http://localhost:8449/fiskal?zadatak=PING"

Moguči povrati : OK ili povrata nema

ECHO

Služi za provjeru dali program radi i te dali može komunicirati sa serverom porezne uprave.

Primjer : http://localhost:8449/fiskal?zadatak=ECHO"

Moguči povrati : True ili povrata nema

GETSERVER

Služi za provjeru dali je program usmjeran na slanje zahtjeva na Produkcjiski ili Testni Server PU.

Primjer : http://localhost:8449/fiskal?zadatak=GETSERVER"

Moguči povrati : Produkcijski ili Testni

GETHRFVERSION

Primjer : http://localhost:8449/fiskal?zadatak=GETHRFVERSION"

Moguči povrati : Verzija učitanog programa

GENERIRAJUID (GUID)

Primjer : http://localhost:8449/fiskal?zadatak=GENERIRAJUID"

Moguči povrati : generirani jedinstveni broj

GENERIRAJZKI (GZKI)

Zahtjeva dodatnih 6 parametara za izračun ZKI u formatu prema priloženom primjeru.

Primjer :http://localhost:8449/fiskal?zadatak=GENERIRAJZKI

String poslan u POST formatu mora biti u sljedečem obliku :

"time=" + time + "&" + "oib=" + oib + "&" + "brrac=" + brrac + "&" + "iznosrac=" + iznosrac + "&" + "brpos=" + brpos + "&" + "brnaplatnog=" + brnaplatnog

naprimjer :

time=23.09.2016 19:13:35&oib=17052038498&brrac=2571&&iznosrac=200.00&brpos=1&brnaplatnog=1

Moguči povrati : izračunati ZKI broj

DOHVATIVRIJEME (VRIJEME)

Primjer : http://localhost:8449/fiskal?zadatak=VRIJEME"

Moguči povrati : trenutno sistemsko vrijeme u formatu 23.09.2016T19:13:35

GETCONFIG

Primjer : http://localhost:8449/fiskal?zadatak=GETCONFIG"

Moguči povrati : vrača trenutnu konfiguraciju programa

GETSINGLECONFIG

Primjer : http://localhost:8449/fiskal?zadatak=GETSINGLECONFIG&property=PORT"

Moguči povrati : vrača trenutnu konfiguraciju programa za pojedini property

U slučaju greške vrača tekst greške

GETERRORLOG

Primjer : http://localhost:8449/fiskal?zadatak=GETERRORLOG"

Moguči povrati : vrača sadržaj Error.log datoteke

GETMEMORY

Primjer : http://localhost:8449/fiskal?zadatak=GETMEMORY"

Moguči povrati : trenutno stanje memorije unutar JVM

FREEMEMORY

Od programskog Garbage collectora zahtjeva oslobađanje memorije. Nikada u toku testiranja se nije dogodilo da program ostane bez programske memorije, ali ovim pozivom se ona može skoro u potpunosti osloboditi ako usljed velikog naglog broja zadataka dođe do memorijskih problema.

Primjer : http://localhost:8449/fiskal?zadatak=FREEMEMORY"

Moguči povrati : trenutno stanje memorije unutar JVM

RACUNZAHTJEV (RZ)

Koristi se za slanje RAČUNA.

Zahtjeva dodatni parametar broj računa (brfak) prema priloženom primjeru

Primjer : http://localhost:8449/fiskal?zadatak=RACUNZAHTJEV&brfak=1234

POST se sastoji od XML stringa definiranim kao RACUNZAHTJEV prema Tehničkim specifikacijama porezne uprave (primjer u nastavku).

XML string mora biti sadržan u POST parametru "DATA".

Napomena : Ukoliko pri konfiguraciji nije omogučen upis UUIDA te Vremena slanja, tada treba u XML zahtjevu upisati i vrijednosti u tagove
<IdPoruke></IdPoruke> te <DatumVrijeme></DatumVrijeme>.

U koliko su te mogučnosti čekirane če ispuniti vrijednosti UIDom te trenutnim vremenom.

<ZastKod></ZastKod> se u svakom slučaju izračunava te popunjuje, te ga stoga nije potrebno upisivati unutar korisničke aplikacije jer če ionako biti prepisan.

Moguči povrati : String koji se sastoji se sastoji od 4 elementa UID , JIR , Vrijeme povrata iz datoteke PU , ZKI izračunan na osnovu podataka iz XML poruke

U slučaju greške : " " , " " , ZKI izračunan na osnovu podataka iz XML poruke, poruka greške

Elementi stringa su odvojeni sistemskim linijskim separatorom.

*U slučaju greške pri izvođenju procedure, moguče je da bude vračena samo poruka greške ili da ne bude vračena nikakva poruka
, u tom slučaju se gotovo sigurno radi o pogrešno formatiranoj XML poruci zahtjeva.

RACUNPROVJERAZAHTJEV (RZP)

Koristi se za slanje ZAHTJEVA ZA PROVJERU RAČUNA.

Svi _GET(izuzev zadatka) i _POST parametri su istovjetni kao kod RACUNZAHTJEV

Primjer : http://localhost:8449/fiskal?zadatak=RACUNPROVJERAZAHTJEV&brfak=1234

Primjer datoteke za provjeru (Datoteka je istovjet na XML datoteci kao RACUNZAHTJEV i razlikuje se samo po prvoj i zadnjoj liniji), međitim ako server uz ovaj poziv primi i uobičajeni XML string tipa RACUNZAHTJEV prepraviče ga i poslati na provjeru.

Moguči povrati : su istovjetni kao kod RACUNZAHTJEV.

PRATECIDOKUMENTIZAHTJEV (PDZ)
Koristi se za slanje PRATEČEG DOKUMENTA.

Svi _GET(izuzev zadatka) i _POST parametri su istovjetni kao kod RACUNZAHTJEV

Primjer : http://localhost:8449/fiskal?zadatak=PRATECIDOKUMENTIZAHTJEV&brfak=1234

Moguči povrati : su istovjetni kao kod RACUNZAHTJEV.

RACUNPDZAHTJEV (RPDZ)
Koristi se za slanje RAČUNA ZA PRATEČI DOKUMENT.

Svi _GET(izuzev zadatka) i _POST parametri su istovjetni kao kod RACUNZAHTJEV

Primjer : http://localhost:8449/fiskal?zadatak=RACUNPDZAHTJEV&brfak=1234

Moguči povrati : su istovjetni kao kod RACUNZAHTJEV.

PROMIJENINACPLACZAHTJEV
Koristi se za slanje IZMJENE NAČINA PLAĆANJA NA VEČ FISKALIZIRANOM RAČUNU.

Svi _GET(izuzev zadatka) i _POST parametri su istovjetni kao kod RACUNZAHTJEV

Primjer : http://localhost:8449/fiskal?zadatak=PROMIJENINACPLACZAHTJEV&brfak=1234

Detalje pogledajte u "Fiskalizacija - Tehnicka specifikacija za korisnike_v2.2" porezne uprave na strani 30.
Ukoliko je u postavkama definirano speremanje soap poruka za račune, onda če i poruke za izmjenu načina plaćanja biti spremljene u iste foldere.
Ime datoteke će biti istovjetno broju računa+"_PNP".
U slučaju uspjeha funkcija vrača string od 4 reda
P001 <-- Kod za uspjelu operaciju XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX <-- String od 36 X karaktera (dužina je ista kao jir pa se može smatrati da ako se vrati - operacija je uspjela) <-- Prazan red d81d9cc814538e5c3f4c9a1f82a0fbad <-- ZKI jednak kao i kod slanja računa
U slučaju greške u 4 redu pokušava vratiti razloge greške.

NAPOJNICAZAHTJEV (u funkciji od verzije 60)
Koristi se za slanje XMLa NAPOJNICE nakon što smo uspješno fiskalizirali račun.

Svi _GET(izuzev zadatka) i _POST parametri su istovjetni kao kod RACUNZAHTJEV

Primjer : http://localhost:8449/fiskal?zadatak=NAPOJNICAZAHTJEV&brfak=1234

Zahtjev se šalje na istovjetan način kao i za račun i sa gotovo istovjetnom XML strukturom.
Detalje pogledajte u "Fiskalizacija - Tehnicka specifikacija za korisnike v2.5._23_10_23" porezne uprave na strani 46.
Dokumentaciju skinite ovdje
Ukoliko je u postavkama definirano speremanje soap poruka za račune, onda če i poruke za izmjenu načina plaćanja biti spremljene u iste foldere.
Ime datoteke će biti istovjetno broju računa+"_NAP.xml". (U slučaju greške istovjetno broju računa+"_NAP_GRESKA_ŠIFRAGRESKE.xml)
U slučaju uspjeha funkcija vrača string od 4 reda
P036956ee-5b08-4187-92c6-22833652176e <-- uid povratne poruke Uspješna dostava podataka o napojnici. <-- poruka 26.10.2023T17:07:02 <-- vrijeme primitka povratne poruke p002 <-- Oznaka uspješnog povrata
U slučaju greške.
P036956ee-5b08-4187-92c6-22833652176e <-- uid povratne poruke OIB iz poruke zahtjeva nije jednak OIB-u iz certifikata. <-- opis greške 26.10.2023T17:07:02 <-- vrijeme primitka povratne poruke s005 <-- Šifra greške

QRCODE ili CREATEBARCODE
Primjer do verzije 45:
http://localhost:8449/fiskal?zadatak=QRCODE&text=TekstZaKonverzijuKojiPropisujeZakonodavac&size=200

Primjer od verzije 45 nadalje:
http://localhost:8449/fiskal?zadatak=CREATEBARCODE&text=TekstZaKonverzijuKojiPropisujeZakonodavac&barcodetype=QRCODE&width=200&height=200&returnasblob=true&imagetype=png

Primjer od verzije 46 nadalje:
http://localhost:8449/fiskal?zadatak=CREATEBARCODE&text=base64encodedTekstZaKonverzijuKojiPropisujeZakonodavac&barcodetype=QRCODE&width=200&height=200&returnasblob=true&imagetype=png&encoded=true

Podržani barcodetype su QRCODE (primjena pri fiskalizaciji i dr.) i PDF417 (moguča primjena za generiranje barcoda za internet plačanje)
Podržani imagetype format je png,jpg,bmp te gif.
*Ako je height veći od width, barkod če biti kreiran kao vertikalni image.
Znakovi za novi red (linefeed) mogu biti također poslani unutar parametra text.
Sekvenca karaktera unutar parametra text "\r\n" će biti također tretirana kao oznaka za novi red.
Parametri (izuzev parametra zadatak) se mogu poslati i kroz _POST (što je poželjno ako parametar text sadrži linefid karaktere, odnosno više redova) , ukoliko se šalju kao _GET onda parametar text prije slanja mora biti urlencoded.
*ili može biti base64encoded i Queryju mora biti dodan parametar encoded=true

Moguči povrati : BASE64 formatirani string koji sadrži image
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABGklEQVR42u2YQRKDMAhFySrHyE01 uWmOkVVSPqjTTu22/IWMOpq3QeBDVNYvk4c85M+kilqZGc9t4CHRkKbnKDV3yT2NcqyQkCG6MEV2 3JcqhY2o15uURUksqLdehxLLdkOeb+sgkrhK2vDjWz+R5DKQ+74TRtTrBGeRZ9Rj7jsNaQt9RdD5 cAOt0BAXyuadb/V9vGc7mgz0PI3rbtnWl+Ah09YwMXSmQS7CQ5r1PCtDuLzlSyUExDNsA00+vY4n VoYbBgWC2j52AeGktDPb3mkSDXGr2NxBHwgwDfFppmVoEoH7iYb4LmAilmeqeYhJxK5iVvgI2t70 YiQj9VjrPjdYyPmVg4geQmEhp0rg77rZj0aS5//BQ+LJC1TWpO59zQr7AAAAAElFTkSuQmCC
Izvod iz tehničke specifikacije za korisnike
Provjera računa preko QR koda Obveznik fiskalizacije prilikom izdavanja računa, na svakom računu zajedno s podacima računa prikazuje odnosno ispisuje i QR kod tog računa kako bi kupac mogao izvršiti provjeru računa preko njega. Pri određivanju QR koda koristi se QR kod model 1 ili model 2 najmanje moguče inačice. QR kod treba biti minimalno veličine 2 puta 2 centimetra pri čemu prazan prostor sa svih strana QR koda mora biti minimalno 2 milimetara. Ne smije biti ispisan na slici ii logu niti smije sadržavati sliku ili logo. QR kod treba imati minimalno L razinu korekciju greške. Mora biti usklađen sa standardom ISO/IEC 15415. QR kod mora sadržavati zapis sljedećih podataka: - poveznicu https://porezna.gov.hr/rn do web stranice za provjeru računa - ili JIR ili ZKI fiskaliziranog računa (36 znaka za JIR, odnosno 32 znaka za ZKI) - datum i vrijeme izdavanja račiuna u formatu GGGGMMDD_HHMM (13 znakova) - ukupni iznos račiuna (10 znakova) - dodatne separatore (15 znakova) Dodatni separatori koji se moraju koristiti pri formiranju podataka za provjeru računa preko QR koda su navedeni u primjerima poveznica za JIR/ZKI do Internet stranice za provjeru računa. Napomena: Podaci navedeni u primjerima su testni i ne moraju biti poslovno ispravni ili logični. Primjer QR koda (inačica 4) za JIR s raćuna: https://porezna.gov.hr/rn?jir=12345678-1234-1234-1234-123456789012&datv=20190905_1230&izn=100000000 Primjer QR koda (inačica 4) za ZKI s raćuna: https://porezna.gov.hr/rn?zki=12345678123412341234123456789012&datv=20190905_1230&izn=100000000

POZIVI PREMA APIJu TVRTKE IERACUNI (u funkciji od verzije 70)
Api omogučava provjereno najpovoljnije slanje B2G i B2B računa u Hrvatskoj bez pretplate.
Specifikacija Apija je na web adresi https://ie-racuni.com/api/v4.

Nekoliko primjera komunikacije sa apijem :
Primjeri su u Javascriptu uz korištenje Ajaxa.

Url "http://localhost:8449/app/IERACUNI" je fiksna adresa proksija za IERAČUNE unutar HrFiskalizatora, a u nastavku je željena api instrukcija.

Slanje eRačuna prema IERACUNI servisu POST metodom.
$.ajax({ url: 'http://localhost:8449/app/IERACUNI/import?type=INVOICE', method: 'post', data: 'file='+encodeURIComponent(xmlDocument), /*xmlDocument je string koji sadrži XML dokument računa u UBL 2.1 formatu*/ }).done(function (response) { console.log(response); })
Dohvat liste POSLANIH računa.
$.ajax({ url: 'http://localhost:8449/app/IERACUNI/invoices/OUTGOING', method: 'get', }).done(function (response) { console.log(response); })
Dohvat liste PRIMLJENIH računa.
$.ajax({ url: 'http://localhost:8449/app/IERACUNI/invoices/INCOMING', method: 'get', }).done(function (response) { console.log(response); })
Dohvat jsona sa statusom ranije poslanog računa id=7988
$.ajax({ url: 'http://localhost:8449/app/IERACUNI/invoices/7988', method: 'get', }).done(function (response) { console.log(response); })
Preuzimanje (download) računa id=7988
Napomena:radi se o ID računa pridruženog računu prilikom slanja , a ne broju izdanog računa !
Poziv vrača JSON u kojem je key xml, UTF-8 base64-encoded string sa xmlom računa. $.ajax({ url: 'http://localhost:8449/app/IERACUNI/invoices/7988/download', method: 'get', }).done(function (response) { console.log(response); })

POZIVI PREMA APIJu ZA PROVJERU eRačuna (u funkciji od verzije 70)
Osim toga omogućava provjeru svih UBL strukturiranih XML dokumenata, čiju listu možete vidjeti OVDJE.
Api nema ugrađene provjere vezane uz Fiskalizaciju 2.0.
Primjer komunikacije sa apijem :

Slanje eRačuna na provjeru POST metodom.
$.ajax({ url: 'http://localhost:8449/app/PEPPOLVALIDATOR?vesid=org.oasis-open:invoice:2.1', method: 'post', data: encodeURIComponent(xmlDocument), /*xmlDocument je string koji sadrži XML dokument računa u UBL 2.1 formatu*/ }).done(function (response) { console.log(response); })

PROVJERA ERačuna putem korištenjem LOKALNIH XSD datoteka (Promijenjeno od verzije 78)
$.ajax({ url: 'app/eizvjestavanje/xml?action=TESTIRAJLOGIKU&soapaction=Invoice' method: 'post', data: encodeURIComponent(xmlDocument), /*xmlDocument je string koji sadrži XML dokument računa u UBL 2.1 formatu*/ }).done(function (response) { console.log(response); })
$.ajax({ url: 'app/eizvjestavanje/json?action=TESTIRAJLOGIKU&soapaction=Invoice', method: 'post', data: encodeURIComponent(jsonstring), /*jsonstring je string koji sadrži JSON dokument računa u UBL 2.1 formatu*/ }).done(function (response) { console.log(response); })

Pretraga KPD specifikacija (u funkciji od verzije 78)
Pretrašuje KPD specifikacije uz mogućnost pretrage po : NAME , CODE , SECTOR
Parametar nija case sensitive.
Parametrom limit određuje broj rezultata koji se vračaju (default 30)
$.ajax({ url: 'http://localhost:8449/app/KPDSEARCH?trazipo=NAME&pojam=kosilic&limit=10', method: 'GET', }).done(function (response) { console.log(response); })

Pretraga OZNAKA JEDINICE MJERA (u funkciji od verzije 78)
Pretrašuje prvo pojmove unutar definiranih specifikacija, a ako ne nađe pokušava naći kod.
Parametar "pojam" nija case sensitive.
Parametrom limit određuje broj rezultata koji se vračaju (default 10)
$.ajax({ url: 'http://localhost:8449/app/JMSEARCH?pojam=komad&limit=5', method: 'GET', }).done(function (response) { console.log(response); })

Slanje eRačuna preko FINA API (u funkciji od verzije 78)
Parametar servis određuje kome će se upiti proslijediti servis=B2G ili servis=B2B
*Ako je parametar izostavljen podrazumijeva se defaultni servis configuriran upostafkama Hrfiskalizatora.
Dohvaćanje konfiguracije apija.
$.ajax({ url: 'finaapi/CONFIG', method: 'GET', }).done(function (response) { console.log(response); })
Dohavanje statusa servera FINE GET metodom ECHO.
$.ajax({ url: 'finaapi/ECHO?servis=B2G', method: 'GET', }).done(function (response) { console.log(response); })
Dohavanje liste registriranih korisnika.
$.ajax({ url: 'finaapi/GETRECEIVERLIST?servis=B2G', method: 'GET', }).done(function (response) { console.log(response); })
Dohavanje liste registriranih korisnika. sa uvijetima pretrage.
Parametar field može biti NAZIV ili OIB.
*podržano samo za servis=B2G
Parametar value je vrijednost za pretragu.
Pretraga po NAZIVU podržava djelomičnu pretragu.
Pretraga po OIBU zahtjeva točan OIB.
$.ajax({ url: 'finaapi/GETRECEIVERLIST?servis=B2G&field=NAZIV&value=OPĆINA', method: 'GET', }).done(function (response) { console.log(response); })
$.ajax({ url: 'finaapi/GETRECEIVERLIST?servis=B2G&field=OIB&value=30812410980', method: 'GET', }).done(function (response) { console.log(response); })
Slanje eRačuna prema FINA API servisu POST metodom.

Parametar data sadrži XML dokument u UBL 2.1 formatu
Parametar data mora biti poslan kao _POST parametar
*data mora biti urlencoded.
$.ajax({ url: 'finaapi/INVOICE?servis=B2G', method: 'post', data: encodeURIComponent(xmlDocument), /*xmlDocument je string koji sadrži XML dokument računa u UBL 2.1 formatu*/ }).done(function (response) { console.log(response); })
Dohvat statusa računa.
Parametri :
invoiceid - obavezan parametar, sadrži BROJ računa
godina - obavezan parametar, sadrži GODINU računa
*ako godina nije navedena podrazumijeva se tekuća godina.
$.ajax({ url: 'finaapi/GETINVOICESTATUS?servis=B2G&invoiceid=123-P1-1&godina=2025', method: 'GET', }).done(function (response) { console.log(response); })

Proxy funkcija HrFiskalizatora
Bilo koju stranicu sa interneta možete učitati iz javascripta ili kojeg drugog dijela programa,
bez straha da če vas blokirati CORS politika preglednika.
Podržava HTTP/ i HTTPS/ protokole.
Na taj način možete učitati i javne api-je koji ne podržavaju CORS.,
ili bilo koju drugu stranicu koja je javno dostupna na internetu.
Ukoliko stranica zahtjeva login podatke, oni HrFiskalizatoru možete biti proslijeđeni kroz header parametar "Target-authorization".
U formatu login:password.
Ukoliko želite učitati stranicu https://api.ipify.org/?format=txt
$.ajax({ url: 'HTTPS/api.ipify.org/?format=txt', method: 'GET', }).done(function (response) { console.log(response); })