Pregled
IntuitiveFiscal preuzima Fiskalizaciju 1 (račune u krajnjoj potrošnji, CIS specifikacija v2.7). Vaša aplikacija šalje podatke računa, a servis dodjeljuje redni broj, računa ZKI privatnim ključem vašeg FINA certifikata, potpisuje poruku, dohvaća JIR od Porezne uprave i brine o naknadnoj dostavi kad CIS ne odgovara.
-
Pošaljete račun.
POST /v1/invoicess poslovnim prostorom, uređajem, stavkama i iznosima. - Dobijete broj, ZKI i (gotovo uvijek) JIR. Servis račun trajno spremi prije slanja CIS-u, pa broj i ZKI imate i kad je CIS nedostupan.
- Ispišete račun. S JIR-om i QR kodom iz odgovora, ili koristite gotov PDF.
- Webhook javlja ostalo. Ako JIR stigne naknadno, ili se dogodi nešto što treba vašu pažnju, servis to javlja potpisanim webhookom.
Broj računa nikad ne šaljete vi. Servis ga dodjeljuje atomski, po
poslovnom prostoru i naplatnom uređaju, bez rupa i duplikata. Zahtjev s poljem za
broj računa odbija se s 400.
Prije početka
Za integraciju trebate pristup administratorskom sučelju i sljedeće postavke:
- Tenant (obveznik). Vaš OIB, podatak jeste li u sustavu PDV-a i oznaka slijednosti (po poslovnom prostoru ili po naplatnom uređaju). Tenant otvaramo mi; za pristup nam se javite.
-
FINA certifikat. Učitavate ga u sučelju (
.p12datoteka i lozinka). Privatni ključ čuva se kriptiran i ne napušta servis. -
Poslovni prostori i naplatni uređaji. Oznake (npr.
POSL1i1) koje šaljete u svakom računu. - Aplikacija i API ključ. U sučelju izradite aplikaciju za svoj sustav i za nju API ključ. Ključ se prikazuje samo jednom.
- Webhook URL (preporučeno). HTTPS adresa na koju šaljemo događaje, i tajna za provjeru potpisa.
Autentikacija
Svaki zahtjev prema /v1 nosi API ključ u zaglavlju
Authorization. Ključ određuje aplikaciju, a time i obveznika: OIB ili
tenant nikad se ne šalju u tijelu zahtjeva.
Authorization: Bearer fsk_test_Ab3dE9_…
| Prefiks ključa | Okolina |
|---|---|
fsk_test_ |
Testna: računi idu na demo CIS Porezne uprave s FINA demo certifikatom i nemaju pravni učinak. Koristite je za razvoj i testiranje. |
fsk_live_ |
Produkcijska: stvarni fiskalizirani računi. |
Testni ključ nikad ne šalje na produkcijski CIS niti obrnuto. Neispravan, opozvan ili
nepostojeći ključ daje 401 unauthorized. Ključ čuvajte isključivo na
serveru; nikad ga ne ugrađujte u web stranicu ili mobilnu aplikaciju koju korisnici
mogu otvoriti. Ako sumnjate da je ključ procurio, opozovite ga u sučelju; opoziv je
trenutan.
Konvencije
-
Iznosi su decimalni stringovi, nikad brojevi s pomičnim zarezom:
"125.00", ne125ni125.0. Iznosi su u eurima. Isto vrijedi za količine ("1","0.250") i stope PDV-a ("25.00"). - Vremena su ISO 8601. Datum i vrijeme izdavanja postavlja servis prema zoni Europe/Zagreb.
- ID-jevi su UUID (v7, vremenski sortirani).
-
Nepoznata polja se odbijaju s
400 validation_failed, umjesto da se tiho zanemare. Tipovi se ne pretvaraju: broj na mjestu stringa je greška. -
Polje
metadata(do 50 ključeva) je vaše: spremamo ga uz račun i vraćamo nepromijenjeno u odgovorima i webhookovima. Zgodno za ID narudžbe ili blagajnika u vašem sustavu.
Idempotentnost
Zahtjevi koji izdaju račun (POST /v1/invoices i
POST /v1/invoices/{id}/storno) obavezno nose zaglavlje
Idempotency-Key: jedinstvenu vrijednost koju generirate vi, od 1 do 200
vidljivih ASCII znakova, npr. UUID ili ID narudžbe.
-
Ponovite li zahtjev s istim ključem i istim tijelom, servis ne izdaje novi račun
nego vraća postojeći, sa statusom
200i zaglavljemIdempotent-Replayed: true. - Isti ključ s drugačijim tijelom daje
409 idempotency_conflict. - Ključ vrijedi unutar vaše aplikacije; druge aplikacije ga ne vide.
Pravilo: ključ spremite prije slanja zahtjeva. Ako zahtjev pukne na mreži ili istekne, ponovite ga s istim ključem. Tako nikad ne nastane dvostruki račun, a ni račun koji je izdan, a vi za njega ne znate.
Izdavanje računa
POST /v1/invoices
Izdaje i fiskalizira račun. Servis u jednoj transakciji dodjeljuje broj, računa ZKI i sprema račun, a zatim odmah šalje poruku CIS-u i čeka odgovor nekoliko sekundi.
curl https://intuitivefiscal.com/v1/invoices \
-H "Authorization: Bearer $FISKAL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: narudzba-A-1042" \
-d '{
"premises": "POSL1",
"device": "1",
"operatorOib": "12345678903",
"paymentMethod": "K",
"items": [
{ "name": "Kava", "quantity": "2", "unitPrice": "2.00", "vatRate": "25.00" },
{ "name": "Usluga", "quantity": "1", "unitPrice": "96.00", "vatRate": "25.00" }
],
"totals": {
"vat": [{ "rate": "25.00", "base": "100.00", "amount": "25.00" }],
"total": "125.00"
},
"metadata": { "orderId": "A-1042" }
}'
Polja zahtjeva
| Polje | Opis |
|---|---|
premises obavezno |
Oznaka poslovnog prostora, 1 do 20 slova i znamenki. Mora postojati i biti aktivan. |
device obavezno |
Oznaka naplatnog uređaja u tom prostoru, samo znamenke. |
operatorOib obavezno |
OIB operatera (blagajnika) koji izdaje račun. |
paymentMethod obavezno |
G gotovina, K kartice, T transakcijski
račun, O ostalo.
|
buyerOib |
OIB kupca ili null. Ne smije se slati uz način plaćanja
T.
|
items[] obavezno |
1 do 500 stavki. Stavke služe za PDF; CIS dobiva samo zbirne iznose po stopama. |
name |
Naziv stavke, 1 do 200 znakova. |
quantity |
Količina kao string, različita od nule, do 3 decimale. Može biti negativna (npr. povrat ambalaže). |
unitPrice |
Jedinična cijena bez PDV-a, do 4 decimale. |
vatRate |
Stopa PDV-a, npr. "25.00". Obavezna ako ste u sustavu PDV-a, i za
nju mora postojati redak u totals.vat. Ako niste u sustavu PDV-a,
izostavite je ili pošaljite null.
|
totals.vat[] |
Rekapitulacija PDV-a po stopama: rate, base (osnovica)
i amount (iznos poreza). Svaka stopa najviše jednom. Prazno ili
izostavljeno ako niste u sustavu PDV-a.
|
totals.total obavezno |
Ukupni iznos računa s dvije decimale. |
metadata |
Slobodni JSON objekt (do 50 ključeva) ili null. |
Provjera iznosa: zbroj quantity × unitPrice svih
stavki plus zbroj totals.vat[].amount mora odgovarati
totals.total, uz toleranciju od 0,01 €. Inače dobivate
400 validation_failed s opisom razlike.
Odgovor
201 Created s objektom računa. Odgovor je
201 i kad CIS nije odgovorio na vrijeme; tada je jir
null, a status delayed.
{
"id": "0193a6f2-7c4e-7b21-9d3a-5e8f1c2b4a60",
"number": "17/POSL1/1",
"premises": "POSL1",
"device": "1",
"year": 2026,
"sequenceNumber": 17,
"issuedAt": "2026-11-18T11:47:12+01:00",
"zki": "e4d909c290d0fb1ca068ffaddf22cbd0",
"jir": "4f2d8a1c-5b6e-4c7d-8e9f-0a1b2c3d4e5f",
"status": "fiscalized",
"nakDost": false,
"issuedWithoutJir": false,
"deliveryDeadline": null,
"fiscalizedAt": "2026-11-18T10:47:13.000Z",
"paymentMethod": "K",
"operatorOib": "12345678903",
"buyerOib": null,
"items": [ … ],
"totals": { "vat": [ … ], "total": "125.00" },
"metadata": { "orderId": "A-1042" },
"stornoOf": null,
"stornedBy": null,
"initiatedBy": "app",
"lastError": null,
"createdAt": "2026-11-18T10:47:12.000Z",
"updatedAt": "2026-11-18T10:47:13.000Z",
"qrPayload": "https://porezna.gov.hr/rn?jir=4f2d8a1c-…&datv=20261118_1147&izn=12500",
"qrUrl": "/v1/invoices/0193a6f2-7c4e-7b21-9d3a-5e8f1c2b4a60/qr.png",
"pdfUrl": "/v1/invoices/0193a6f2-7c4e-7b21-9d3a-5e8f1c2b4a60/pdf"
}
Odgovor može trajati nekoliko sekundi jer čeka CIS. Postavite vremensko ograničenje
klijenta na najmanje 15 sekundi, a nakon isteka ponovite zahtjev s istim
Idempotency-Key.
Objekt računa
Isti oblik vraćaju izdavanje, storno, dohvat, lista i webhookovi.
| Polje | Opis |
|---|---|
id |
ID računa u servisu. |
number |
Broj računa za ispis: broj/prostor/uređaj, npr.
17/POSL1/1. Brojevi kreću od 1 svake kalendarske godine.
|
year, sequenceNumber |
Godina i redni broj u slijedu. |
issuedAt |
Datum i vrijeme izdavanja (poslano CIS-u). |
zki |
Zaštitni kod izdavatelja, 32 heksadecimalna znaka. Uvijek prisutan. |
jir |
Jedinstveni identifikator računa od Porezne uprave, ili null dok ga
nema.
|
status |
Vidi statuse. |
issuedWithoutJir |
true ako ste dobili odgovor bez JIR-a; račun se tada ispisuje samo
sa ZKI-jem.
|
nakDost |
Je li račun (naknadno) dostavljen s oznakom naknadne dostave. |
deliveryDeadline |
Zakonski rok naknadne dostave za račun izdan bez JIR-a. |
fiscalizedAt |
Kad je dobiven JIR. |
stornoOf, stornedBy |
Veza između izvornog i storno računa. |
initiatedBy |
Tko je izdao račun: app (vaša aplikacija preko API-ja) ili
admin (storno izdan iz administratorskog sučelja).
|
updatedAt |
Zadnja promjena stanja: JIR, storno, fiskalizirana promjena. Koristi se s
updatedSince.
|
lastError |
Zadnja greška slanja, ako je ima. |
qrPayload |
Sadržaj QR koda (URL Porezne uprave) za aplikacije koje same crtaju račun. |
qrUrl, pdfUrl |
Relativne putanje do QR koda i PDF-a (traže API ključ). |
Statusi i naknadna dostava
| Status | Značenje |
|---|---|
pending |
Spremljen, ZKI izračunat, čeka slanje. |
sending |
Upravo se šalje CIS-u. |
fiscalized |
JIR dobiven. Konačno stanje. |
delayed |
CIS nije odgovorio; servis ponavlja slanje kao naknadnu dostavu dok ne dobije JIR. |
rejected |
CIS je vratio poslovnu grešku (opis u lastError). Ne ponavlja se
automatski; treba ručna provjera.
|
Kad JIR ne stigne odmah
Ako CIS ne odgovori unutar nekoliko sekundi, dobivate račun s brojem i ZKI-jem, ali bez JIR-a. To je zakonom predviđen slučaj:
- Ispišite i izdajte račun kupcu sa ZKI-jem. QR kod u tom slučaju sadrži ZKI umjesto JIR-a i već je ispravan.
- Servis sam ponavlja slanje s oznakom naknadne dostave (nakon 1, 2, 5 i 10 minuta, zatim svakih 15 minuta) dok ne dobije JIR, unutar zakonskog roka.
-
Kad JIR stigne, dobivate webhook
invoice.fiscalized. Možete i povremeno pitatiGET /v1/invoices/{id}.
Ako ispad CIS-a potraje, servis otvara incident i obavještava vlasnike obveznika
e-poštom i webhookom incident.opened. Ne morate ništa poduzimati osim ako
račun završi kao rejected.
Dohvat i lista računa
GET /v1/invoices/{id}
Račun s dodatnim poljima attempts (svaki pokušaj slanja CIS-u: vrijeme,
uspjeh, greške) i changes (promjene nakon izdavanja).
GET /v1/invoices
Lista računa, od najnovijeg prema starijima, s paginacijom kursorom.
| Parametar | Opis |
|---|---|
from, to |
Datumi GGGG-MM-DD (uključivo), prema vremenu u Zagrebu. |
status |
Jedan od statusa. |
premises, device |
Oznaka prostora i uređaja. |
updatedSince |
ISO 8601 trenutak. Vraća samo račune promijenjene nakon njega, od najstarije promjene prema najnovijoj. Vidi usklađivanje stanja. |
limit |
1 do 200, zadano 50. |
cursor |
Vrijednost nextCursor iz prethodne stranice. |
curl "https://intuitivefiscal.com/v1/invoices?from=2026-11-01&status=delayed&limit=100" \
-H "Authorization: Bearer $FISKAL_API_KEY"
{
"items": [ { "id": "…", "number": "17/POSL1/1", … } ],
"nextCursor": "WyIyMDI2LTExLTE4VDEwOjQ3OjEyLjAwMFoiLCIwMTkzYTZm…"
}
nextCursor je null na zadnjoj stranici.
QR kod i PDF
QR kod i PDF generiraju se iz spremljenih podataka računa, pa uvijek odgovaraju onome što je poslano Poreznoj upravi.
| Putanja | Vraća |
|---|---|
GET /v1/invoices/{id}/qr.png |
PNG; parametar ?size= određuje širinu u pikselima (zadano 512).
|
GET /v1/invoices/{id}/qr.svg |
SVG, za ispis u bilo kojoj veličini. |
GET /v1/invoices/{id}/pdf |
PDF računa; ?format=a4 ili ?format=receipt (termalni
80 mm). Bez parametra koristi se zadani format iz postavki obveznika.
|
-
Ove putanje traže API ključ, pa ih ne stavljajte izravno u
<img src>na stranici koju vidi kupac. Preuzmite datoteku na svom serveru i poslužite je dalje, ili sami nacrtajte QR iz poljaqrPayload. - Na ispisu QR kod mora biti najmanje 2 × 2 cm, s praznim rubom od najmanje 2 mm i bez loga u kodu.
- PDF prikazuje račun točno onako kako je izdan: račun izdan bez JIR-a ostaje bez JIR-a, a kasnija promjena načina plaćanja ga ne mijenja.
Promjene nakon izdavanja
Način plaćanja i OIB kupca mogu se promijeniti na već izdanom računu, ali samo istog dana kad je račun izdan, do 23:50. Za sve ostalo, i za promjene nakon tog roka, izdajte storno i novi račun.
POST
/v1/invoices/{id}/payment-method
{ "paymentMethod": "G" }
POST /v1/invoices/{id}/changes
{ "paymentMethod": "K", "buyerOib": "69435151530" }
Barem jedno polje je obavezno; "buyerOib": null briše OIB kupca. Oba
poziva vraćaju 201 s objektom promjene:
{
"id": "0193a6f8-…",
"invoiceId": "0193a6f2-7c4e-7b21-9d3a-5e8f1c2b4a60",
"kind": "data",
"status": "done",
"previous": { "paymentMethod": "K", "buyerOib": null },
"new": { "paymentMethod": "K", "buyerOib": "69435151530" },
"createdAt": "2026-11-18T11:02:40.000Z",
"doneAt": "2026-11-18T11:02:41.000Z",
"lastError": null,
"initiatedBy": "app"
}
Statusi promjene su pending, sending, done,
rejected i expired. Ako promjena ne prođe odmah, servis je
ponavlja do ponoći. Ishod javlja webhook invoice.changed ili
invoice.change_failed. Promjena na računu koji još čeka JIR prima se i
šalje čim račun dobije JIR. Nakon roka dobivate 409 change_window_closed.
Istodobno može čekati samo jedna promjena istog računa: dok je prethodna u statusu
pending ili sending, nova dobiva
409 invalid_state. Isto vrijedi za promjenu storniranog računa i storno
računa.
Promjenu može pokrenuti i vlasnik tenanta iz administratorskog sučelja. Tada stiže
isti webhook s initiatedBy: "admin".
Storno
POST /v1/invoices/{id}/storno
Izdaje novi račun s istim stavkama i negativnim iznosima. Storno dobiva vlastiti broj,
ZKI i JIR i prolazi isti tok kao svaki račun, uključujući naknadnu dostavu. Obavezan
je Idempotency-Key.
Tijelo je neobavezno; bez njega sve je kao na izvornom računu:
{
"device": "2",
"operatorOib": "12345678903",
"paymentMethod": "G",
"metadata": { "reason": "povrat robe" }
}
- Storno se izdaje na istom poslovnom prostoru kao izvorni račun.
-
Odgovor je novi račun s poljem
stornoOf; izvorni račun dobivastornedBy. -
Drugi storno istog računa daje
409 invoice_already_storned. Storno storna i storno odbijenog računa daju409 invalid_state. -
Bez polja
metadatastorno nasljeđujemetadataizvornog računa;"metadata": nullizdaje storno bez metapodataka. - Djelomični storno (samo dio stavki) nije podržan: stornirajte i izdajte novi račun.
-
Storno može izdati i vlasnik tenanta iz administratorskog sučelja. Takav storno
pripada aplikaciji izvornog računa, nasljeđuje njegov
metadatai imainitiatedBy: "admin"; aplikacija za njega saznaje webhookominvoice.stornedili periodičnom provjerom.
Poslovni prostori
GET /v1/premises
Poslovni prostori i naplatni uređaji obveznika, npr. za izbornik u vašoj blagajni.
{
"items": [
{
"premises": "POSL1",
"active": true,
"devices": [
{ "device": "1", "active": true },
{ "device": "2", "active": true }
]
}
]
}
Webhooks
Webhook javlja vašoj aplikaciji promjenu koju niste dobili u sinkronom odgovoru, prije svega JIR dobiven naknadnom dostavom. URL i tajnu postavljate u sučelju, za svaku aplikaciju posebno. URL mora biti javna HTTPS adresa.
| Događaj | Kada | data |
|---|---|---|
invoice.fiscalized |
Račun je dobio JIR (šalje se i kad je JIR stigao u sinkronom odgovoru). | invoice |
invoice.delayed |
Prvi pokušaj nije uspio; račun ide u naknadnu dostavu. | invoice |
invoice.rejected |
CIS je vratio poslovnu grešku. | invoice, error |
invoice.changed |
Promjena načina plaćanja ili podataka je fiskalizirana. | invoice, change |
invoice.change_failed |
CIS je odbio promjenu, ili nije prošla do ponoći. |
invoice, change, reason (rejected
ili expired)
|
invoice.storned |
Storno račun je fiskaliziran. | original, storno |
incident.opened |
Računi ne prolaze već 30 minuta. |
incidentId, openedAt, waiting,
generalOutage
|
incident.closed |
Svi računi iz incidenta su dostavljeni. |
incidentId, openedAt, closedAt,
delivered, rejected
|
certificate.expiring |
FINA certifikat istječe za 30, 14 ili 3 dana. | certificate, daysLeft, threshold |
webhook.test |
Testni događaj poslan iz sučelja. | message |
Isporuka
Content-Type: application/json
User-Agent: Fiskal-Webhooks/1.0
Fisk-Event: invoice.fiscalized
Fisk-Delivery: 0193a6f2-9e11-7c55-b2d4-6a7b8c9d0e1f
Fisk-Signature: t=1795517233,v1=5f1c0a…e93b
{
"id": "0193a6f2-9d02-7a10-8c3e-1f2a3b4c5d6e",
"event": "invoice.fiscalized",
"createdAt": "2026-11-18T10:47:13.000Z",
"data": {
"invoice": { "id": "0193a6f2-…", "number": "17/POSL1/1", "jir": "4f2d8a1c-…", … }
}
}
-
Uspjeh je bilo koji odgovor
2xxunutar 10 sekundi. Preusmjeravanja (3xx) se ne prate i smatraju se neuspjehom. - Neuspjela isporuka ponavlja se nakon 1 min, 5 min, 30 min, 2 h, 6 h i 24 h, a zatim se označava kao neuspjela. U sučelju je vidite i možete je ponovno poslati.
-
Isporuka je „barem jednom”: isti događaj može stići više puta. Deduplicirajte po
polju
idiz tijela (ne poFisk-Delivery). -
Redoslijed nije zajamčen. Za trenutno stanje oslonite se na sadržaj događaja ili
GET /v1/invoices/{id}. - Odgovorite brzo (npr.
204), a obradu napravite asinkrono. -
Događaji o računu nose i
initiatedBy(appiliadmin): kod promjena tko je zatražio promjenu, inače tko je izdao račun. Storno i promjene iz administratorskog sučelja javljaju se aplikaciji izvornog računa istim događajima. - Webhook URL je neobavezan; bez njega stanje usklađujete samo provjerom.
Usklađivanje stanja u aplikaciji
- Servis je glavni izvor fiskalnog stanja (broj, JIR, status, način plaćanja, OIB kupca, storno), a vaša aplikacija poslovnog stanja (narudžba, termin, plaćeno).
- Držite lokalnu kopiju fiskalnog stanja i ažurirajte je samo iz odgovora API-ja, webhookova i periodične provjere. Ekrani neka čitaju lokalnu kopiju.
-
Webhook je obavijest: na svaki događaj dohvatite
GET /v1/invoices/{id}i prepišite kopiju. Redoslijed i duplikati tada ne utječu na rezultat. -
Periodično pozovite
GET /v1/invoices?updatedSince=…: svakih 5 minuta bez webhooka, ili svakih sat vremena uz webhook. Pošaljite zadnji viđeniupdatedAtumanjen za nekoliko minuta; preklapanje je bezopasno, a hvata i promjene koje su postale vidljive s malim zakašnjenjem. - Storno iz sučelja ne mora značiti otkazanu narudžbu (može slijediti ispravan novi račun). Označite zapis kao „račun storniran, potrebna akcija” umjesto da ga automatski otkažete.
Provjera potpisa
Zaglavlje Fisk-Signature ima oblik:
Fisk-Signature: t=<unix sekunde>,v1=<hex HMAC-SHA256(t + "." + tijelo, tajna)>
- Pročitajte sirovo tijelo zahtjeva, prije parsiranja JSON-a.
-
Izračunajte HMAC-SHA256 nad
t + "." + tijelotajnom aplikacije (whsec_…). - Usporedite s vrijednostima
v1u vremenski konstantnoj usporedbi. -
Odbijte poruke čiji je
tudaljen više od 5 minuta od vašeg vremena.
Nakon rotacije tajne zaglavlje 24 sata nosi dva potpisa v1 (novom i
starom tajnom). Poruku prihvatite ako bilo koji odgovara.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyFiskSignature(secret, header, rawBody, toleranceSec = 300) {
const parts = (header ?? '').split(',').map((p) => p.trim().split('='));
const t = Number(parts.find(([k]) => k === 't')?.[1]);
const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!Number.isInteger(t) || sigs.length === 0) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
return sigs.some((s) => {
const got = Buffer.from(s, 'hex');
return got.length === expected.length && timingSafeEqual(got, expected);
});
}
// Express: tijelo mora ostati sirovo
app.post('/webhooks/fiskal', express.raw({ type: 'application/json' }), (req, res) => {
const body = req.body.toString('utf8');
if (!verifyFiskSignature(process.env.FISKAL_WEBHOOK_SECRET, req.get('Fisk-Signature'), body)) {
return res.sendStatus(400);
}
const event = JSON.parse(body);
// … obrada, deduplikacija po event.id
res.sendStatus(204);
});
function verifyFiskSignature(string $secret, string $header, string $rawBody, int $tolerance = 300): bool
{
$t = null;
$sigs = [];
foreach (explode(',', $header) as $part) {
[$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
if ($k === 't' && ctype_digit($v)) $t = (int) $v;
if ($k === 'v1') $sigs[] = $v;
}
if ($t === null || !$sigs || abs(time() - $t) > $tolerance) return false;
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($sigs as $s) {
if (hash_equals($expected, $s)) return true;
}
return false;
}
$body = file_get_contents('php://input');
if (!verifyFiskSignature(getenv('FISKAL_WEBHOOK_SECRET'), $_SERVER['HTTP_FISK_SIGNATURE'] ?? '', $body)) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
http_response_code(204);
Greške
Sve greške imaju isti oblik:
{
"error": {
"code": "validation_failed",
"message": "items[0].vatRate je obavezan za obveznika PDV-a.",
"details": { "problems": ["items[0].vatRate je obavezan za obveznika PDV-a."] }
}
}
Logiku gradite na polju code; message je opis za ljude i
može se mijenjati. details je neobavezan i ovisi o grešci.
| HTTP | Kod | Značenje i što napraviti |
|---|---|---|
| 400 | validation_failed |
Tijelo ili parametri nisu ispravni (format, OIB, zbroj iznosa, nepostojeći
prostor ili uređaj, nedostaje Idempotency-Key). Ispravite zahtjev;
ponavljanje ne pomaže.
|
| 400 | bad_request |
Zahtjev se ne može pročitati, npr. neispravan JSON. |
| 401 | unauthorized |
Nedostaje, neispravan ili opozvan API ključ. |
| 403 | forbidden |
Obveznik nije aktivan. |
| 404 | not_found |
Račun ne postoji ili ne pripada vašem obvezniku. |
| 409 | idempotency_conflict |
Isti Idempotency-Key s drugačijim tijelom.
details.invoiceId pokazuje postojeći račun.
|
| 409 | certificate_missing |
Obveznik nema aktivan FINA certifikat. Učitajte ga u sučelju. |
| 409 | certificate_expired |
Certifikat je istekao. Učitajte novi u sučelju. |
| 409 | change_window_closed |
Rok za promjenu je prošao. Izdajte storno i novi račun. |
| 409 | invoice_already_storned |
Račun je već storniran. |
| 409 | invalid_state |
Radnja nije dopuštena u trenutnom stanju računa (npr. storno odbijenog računa). |
| 429 | rate_limited |
Previše zahtjeva. Pričekajte koliko kaže zaglavlje Retry-After.
|
| 500 | internal_error |
Greška servisa. Ponovite s istim Idempotency-Key. |
Ograničenja i stanje servisa
-
Rate limit: 60 zahtjeva u minuti po API ključu. Odgovori nose
zaglavlja
X-RateLimit-Limit,X-RateLimit-RemainingiX-RateLimit-Reset; prekoračenje daje429saRetry-After. Treba li vam više, javite nam se. -
Stanje servisa:
GET /v1/healthne traži API ključ i vraća200sa"status": "ok", ili503kad servis ili veza prema CIS-u imaju problem. -
OpenAPI: strojno čitljiva specifikacija svih ruta je na
/v1/openapi.json; iz nje možete generirati klijenta ili je uvesti u Postman.
Prelazak u produkciju
Prije prvog stvarnog računa provjerite na testnoj okolini:
- Račun s JIR-om ispisuje se s brojem, ZKI-jem, JIR-om i QR kodom.
-
Račun bez JIR-a (
status: delayed) ispisuje se sa ZKI-jem, a JIR stiže webhookom. - Ponovljeni zahtjev s istim
Idempotency-Keyne stvara novi račun. -
Webhook provjerava potpis, odbija stare poruke i deduplicira po
id. - Storno i promjena načina plaćanja rade iz vaše aplikacije.
-
Greške
validation_failedicertificate_expiredprikazuju se korisniku razumljivo.
Zatim u sučelju izradite produkcijski ključ (fsk_live_), učitajte
produkcijski FINA certifikat i zamijenite ključ u konfiguraciji. Kod se ne mijenja.
Zapeli ste?
Pišite nam s ID-jem računa i kodom greške, pa ćemo pogledati pokušaje slanja i odgovore CIS-a.