Dokumentacija · API v1

Integracija s IntuitiveFiscal API-jem

Sve što vaša blagajna, web trgovina ili aplikacija treba za fiskalizaciju računa u krajnjoj potrošnji: jedan REST API, JSON, API ključ i potpisani webhooks.

Bazni URL
https://intuitivefiscal.com/v1
Format
JSON, UTF-8
OpenAPI
/v1/openapi.json

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.

  1. Pošaljete račun. POST /v1/invoices s poslovnim prostorom, uređajem, stavkama i iznosima.
  2. 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.
  3. Ispišete račun. S JIR-om i QR kodom iz odgovora, ili koristite gotov PDF.
  4. 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 (.p12 datoteka i lozinka). Privatni ključ čuva se kriptiran i ne napušta servis.
  • Poslovni prostori i naplatni uređaji. Oznake (npr. POSL1 i 1) 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.

HTTP
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", ne 125 ni 125.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 200 i zaglavljem Idempotent-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
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.

201 Created
{
  "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:

  1. 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.
  2. 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.
  3. Kad JIR stigne, dobivate webhook invoice.fiscalized. Možete i povremeno pitati GET /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
curl "https://intuitivefiscal.com/v1/invoices?from=2026-11-01&status=delayed&limit=100" \
  -H "Authorization: Bearer $FISKAL_API_KEY"
200 OK
{
  "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 polja qrPayload.
  • 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

Tijelo
{ "paymentMethod": "G" }

POST /v1/invoices/{id}/changes

Tijelo
{ "paymentMethod": "K", "buyerOib": "69435151530" }

Barem jedno polje je obavezno; "buyerOib": null briše OIB kupca. Oba poziva vraćaju 201 s objektom promjene:

201 Created
{
  "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:

Tijelo (sva polja neobavezna)
{
  "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 dobiva stornedBy.
  • Drugi storno istog računa daje 409 invoice_already_storned. Storno storna i storno odbijenog računa daju 409 invalid_state.
  • Bez polja metadata storno nasljeđuje metadata izvornog računa; "metadata": null izdaje 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 metadata i ima initiatedBy: "admin"; aplikacija za njega saznaje webhookom invoice.storned ili periodičnom provjerom.

Poslovni prostori

GET /v1/premises

Poslovni prostori i naplatni uređaji obveznika, npr. za izbornik u vašoj blagajni.

200 OK
{
  "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

POST na vaš webhook URL
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 2xx unutar 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 id iz tijela (ne po Fisk-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 (app ili admin): 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đeni updatedAt umanjen 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:

Format
Fisk-Signature: t=<unix sekunde>,v1=<hex HMAC-SHA256(t + "." + tijelo, tajna)>
  1. Pročitajte sirovo tijelo zahtjeva, prije parsiranja JSON-a.
  2. Izračunajte HMAC-SHA256 nad t + "." + tijelo tajnom aplikacije (whsec_…).
  3. Usporedite s vrijednostima v1 u vremenski konstantnoj usporedbi.
  4. Odbijte poruke čiji je t udaljen 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.

Node.js
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);
});
PHP
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:

400 Bad Request
{
  "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-Remaining i X-RateLimit-Reset; prekoračenje daje 429 sa Retry-After. Treba li vam više, javite nam se.
  • Stanje servisa: GET /v1/health ne traži API ključ i vraća 200 sa "status": "ok", ili 503 kad 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-Key ne 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_failed i certificate_expired prikazuju 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.

Kontaktirajte nas