📘 FISKAL – UPUTE ZA KORIŠTENJE

🧩 Uvod

Program Fiskal bazira se na Raverusevom open‑source modulu za komunikaciju s CIS serverom Porezne uprave. CIS svakom računu dodjeljuje JIR – jedinstveni identifikator koji se mora ispisati na računu.

Program radi u pozadini kao systray ikona i služi kao posrednik između POS sustava i Porezne uprave.

✅ Kratke upute za korisnike

🔍 Kada provjeriti račun?

Nakon svakog fiskaliziranog računa provjerite:

• ima li račun JIR
• je li JIR različit od prethodnog računa

❗ Ako JIR nedostaje

Račun treba ponovno fiskalizirati:

👉 Klik na gumb “Fiskalizacija”

Program će pokrenuti cijeli proces iznova.

🚫 Važno

• ne brišite fiskalizirane račune
• ako se problem ponavlja → kontaktirajte podršku

🔳 QR kod

• obavezan od 2021.
• program ga generira automatski
• prije fiskalizacije koristi ZKI, nakon fiskalizacije JIR
• povremeno ga skenirajte radi provjere

🛠️ TEHNIČKA VERZIJA (za podršku i napredne korisnike)

🔐 Certifikati (.pfx / .p12)

📦 Što su .pfx i .p12 datoteke?

Oba formata su PKCS#12 i sadrže:

• certifikat
• privatni ključ
• lanac certifikata

Razlika je samo u ekstenziji.

📁 Gdje instalirati certifikat?

Preporučeno: 👉 LocalMachine\My

Izbjegavati:

• Desktop
• Downloads
• slanje certifikata mailom bez enkripcije
• lozinke u .txt datotekama

⚙️ PowerShell – preporučeni način za uvoz i izvoz certifikata

PowerShell je pouzdaniji od MMC‑a jer:

• uvijek uvozi certifikat s exportable ključem
• izvoz je pouzdan
• radi i na serverima bez GUI‑ja
• izbjegava MMC bugove

🧰 PowerShell primjer – uvoz i izvoz certifikata:

# Putanja do originalnog .p12 certifikata
$p12Path = "D:\Cert\FISKAL_CERT.p12"

# Lozinka za .p12 certifikat
$p12Password = ConvertTo-SecureString -String "Lozinka123" -Force -AsPlainText

# Uvoz certifikata u LocalMachine\My s exportable ključem
$cert = Import-PfxCertificate -FilePath $p12Path -CertStoreLocation "Cert:\LocalMachine\My" -Password $p12Password -Exportable

# Putanja za izvoz .pfx fajla
$pfxPath = "D:\Cert\FISKAL_EXPORT.pfx"

# Lozinka za novi .pfx fajl
$pfxPassword = ConvertTo-SecureString -String "Lozinka123" -Force -AsPlainText

# Izvoz certifikata u .pfx
Export-PfxCertificate -Cert $cert -FilePath $pfxPath -Password $pfxPassword

⚙️ Osnovno podešavanje programa

• certifikat mora biti instaliran ili spremljen na disk
• nakon pokretanja pojavljuje se systray ikona
• prvi put: desni klik → Namještanja → kartica System
• preporuka: fiskalizirati jedan probni račun

Request / Response datoteke

• request.txt – POS puni
• response.txt – POS čita

⚠️ POS mora obrisati response file nakon čitanja.

Log folder

• nije obavezan
• preporučuje se kod nestabilnih mreža

Timeout

• nestrpljivi: 2–3 s
• strpljivi: 9–10 s

⚠️ manji timeout = veća šansa za grešku

Polling period

• 0 s → .NET watcher
• 1–2 s → mrežni diskovi

Offline mode

• ne šalje podatke na CIS
• vraća samo ZKI
• računi se šalju kad internet proradi

⚠️ račun nije fiskaliziran dok se ne pošalje

Višestruke instance

Program sprječava pokretanje više instanci.

Response file – struktura

Format: JIR;UUID;ZKI;KontrolniBroj

• JIR – 36 znakova
• UUID – 36 znakova
• ZKI – 32 znaka
• kontrolni broj – 20 znakova

❗ Greške u response fileu

1. ZKI postoji, JIR ne → račun se može ispisati, ali ga treba ponovno fiskalizirati
2. nema ni ZKI‑ja → račun se ne smije ispisati

Točan datum i vrijeme

CIS odbija račune s krivim timestampom.

Ostalo

• program je 32‑bitni
• radi na svim Windowsima
• koristi .NET 4.5

📌 FISKALIZACIJA – TEHNIČKI OPIS (za developere i integratore)

1. Priprema okruženja

• brišu se response.txt i tmp_request.txt
• postavljaju se početne vrijednosti (TIP_R, OIB_DJELATNIKA)
• definiraju se putanje za radne datoteke (request.txt, tmp_request.txt, response.txt)

2. Provjera prethodne fiskalizacije

Ako račun već ima JIR, fiskalizacija se ne ponavlja.

3. Generiranje request datoteke

• kreira se privremena datoteka tmp_request.txt
• upisuje se svih 12 redova u fiksnom formatu
• datoteka se zatvara
• radi se atomski RENAME → request.txt
• ako rename ne uspije → radi se retry

Svrha: sprječavanje oštećenih datoteka i problema s antivirusom ili sporim diskom.

4. Čekanje na response datoteku

• do 15 pokušaja
• svaki pokušaj čeka do 4 sekunde
• unutar čekanja radi se polling svakih 10–50 ms
• ako response.txt ne stigne → ide se u sljedeći pokušaj

Svrha: otpornost na spor disk, antivirusne lockove i spor start Raverusa.

5. Otvaranje response datoteke

Ako response.txt postoji:

• pokušava se otvoriti do 20 puta
• između pokušaja kratka pauza
• čita se zadnji neprazni redak

Svrha: rješava antivirusne lockove, BOM i nepotpune zapise.

6. Parsiranje odgovora

Format: JIR;UUID;ZKI

• polja se prepoznaju prema ;
• provjerava se duljina i valjanost
• ako polja nisu ispravna → retry

7. Upis u bazu

Ako je parsiranje uspješno:

• upisuju se JIR, UUID, ZKI
• procedura završava uspješno

Ako nije – ide se u sljedeći retry ciklus.

8. Retry mehanizam

Do 5 kompletnih ciklusa, svaki uključuje:

• brisanje starih datoteka
• generiranje novog requesta
• čekanje responsea
• parsiranje
• upis

Ako svih 5 pokušaja ne uspije → korisnik dobiva jasnu poruku, račun ostaje nefiskaliziran.

Ukupno vrijeme

• jedan ciklus: do 4 sekunde čekanja
• maksimalno: 5 × 4 = 20 sekundi (ovisno o konfiguraciji može biti i do 50 sekundi – ispravno)

Svrha retry mehanizma

Retry rješava:

• antivirusne lockove
• spor disk i Windows caching
• prazne ili nepotpune response datoteke
• neuspjeli rename
• spor start Raverusa
• sporadične greške u komunikaciji

Retry ne produžuje čekanje — resetira cijeli ciklus.

🔧 PROMJENE U FISKALIZACIJI I QR KODU (za developere i integratore)

1. Poboljšanja u fiskalizaciji

🛡 Sprječavanje dvostruke fiskalizacije

Program provjerava postoji li JIR prije slanja. Ako postoji → fiskalizacija se ne ponavlja.

⚙ Stabilno generiranje request datoteke

Umjesto direktnog pisanja u request.txt:

• kreira se privremena datoteka
• upisuje se svih 12 redova
• radi se atomska zamjena (RENAME)

Prednosti:

• nema oštećenih datoteka
• antivirus i spor disk više ne prekidaju proces
• fiskalizacija je pouzdanija

🔁 Napredni retry sustav za čekanje odgovora

• do 15 pokušaja
• svaki pokušaj čeka do 4 sekunde
• kratke pauze između pokušaja

Prednosti:

• radi na sporim računalima
• radi na mobilnom internetu
• radi kad antivirus blokira datoteku

🧱 Retry za file-lock (antivirus fix)

Ako antivirus zaključa response.txt:

• program pokušava otvoriti datoteku do 20 puta
• između pokušaja kratka pauza

Prednosti:

• nema više grešaka “datoteka je u upotrebi”
• fiskalizacija ne puca zbog antivirusa

📤 Pouzdano čitanje odgovora

Novi kod:

• čita sve retke
• uzima zadnji neprazni red
• provjerava strukturu i duljinu
• provjerava JIR, UUID i ZKI

Prednosti:

• nema pogrešnog parsiranja
• radi i s praznim redcima
• radi i ako antivirus doda BOM

🔍 Dinamičko parsiranje

Polja se prepoznaju prema ;, bez fiksnih pozicija.

Prednosti:

• otpornost na promjene formata
• nema krivo izrezanih polja
• nema praznih vrijednosti

🗄 Sigurniji upis u bazu

Upis se radi samo ako su svi podaci valjani.

Prednosti:

• sprječava upis u pogrešan zapis
• stabilniji rad baze

📢 Jasna poruka ako fiskalizacija ne uspije

Ako svih 5 ciklusa padne:

• korisnik dobiva jasnu poruku
• račun ostaje nefiskaliziran
• ništa se ne upisuje u bazu

2. Poboljšanja u generiranju QR koda

🔑 QR kod je valjan tek nakon fiskalizacije

Prije fiskalizacije QR kod koristi ZKI. Nakon fiskalizacije koristi JIR.

🔄 QR kod sada koristi JIR (umjesto ZKI)

Za fiskalizirane račune QR kod koristi:

&jir=

Za nefiskalizirane račune:

&zki=

Prednosti:

• QR kod je potpuno usklađen s pravilima fiskalizacije
• fiskalizirani računi se mogu provjeriti na Poreznoj
• QR kod se automatski prilagođava statusu računa

💶 Format iznosa ostaje nepromijenjen

Primjeri:

Code

5,00

36,75

120,00

📅 Format datuma i vremena ostaje nepromijenjen

Primjer:

Code

04.05.2026_11:44

♻ Automatska regeneracija QR koda

QR kod se generira pri svakom ispisu. Ako je račun naknadno fiskaliziran → QR se automatski regenerira.

Prednosti:

• korisnik ne može ispisati stari QR kod
• QR je uvijek ispravan
• nema ručnog brisanja ili ponovnog generiranja

Sažetak promjena

• fiskalizacija je stabilnija i otpornija
• spriječena dvostruka fiskalizacija
• uveden napredni retry sustav
• upis JIR/UUID/ZKI je sigurniji
• QR kod koristi JIR nakon fiskalizacije
• QR kod se automatski regenerira
• cijeli proces je brži, pouzdaniji i sigurniji