API dokumentacija

Autentikacija

Svi pozivi koriste API ključ u Authorization zaglavlju. Ključ generiraš u portalu (/app → API ključevi); prikaže se jednom, čuvaj ga tajno. Bazni URL: https://fiskalizacija.netlify.app/.

Authorization: Bearer fsk_test_xxxxxxxxxxxx
Content-Type: application/json

POST /v1/racuni — fiskalizacija B2C računa

Fiskalizira račun krajnjem kupcu na CIS Porezne uprave. Broj računa šalješ ti (tvoj slijed). Vraća jir, zki i qr_url za ispis.

Tijelo zahtjeva

{
  "brOznRac": "1",          // broj računa (tvoj slijed)
  "oznPosPr": "WEB1",       // oznaka poslovnog prostora
  "oznNapUr": "1",          // oznaka naplatnog uređaja
  "iznosUkupno": 49.90,     // ukupan iznos
  "nacinPlac": "T",         // G/K/C/T/O (Stripe/kartica → T)
  "pdv": [                  // opcionalno (paušalac izostavi)
    { "stopa": 25, "osnovica": 39.92, "iznos": 9.98 }
  ]
}

Primjer

curl -X POST https://fiskalizacija.netlify.app//api/v1/racuni \
  -H "Authorization: Bearer <api_kljuc>" \
  -H "Idempotency-Key: order-12345" \
  -H "Content-Type: application/json" \
  -d '{"brOznRac":"1","oznPosPr":"WEB1","oznNapUr":"1","iznosUkupno":49.90,"nacinPlac":"T"}'

Odgovor 200

{
  "id": "uuid",
  "jir": "0928a151-863a-...",   // null ako CIS nedostupan (kasnije NakDost)
  "zki": "f67e95480705...",
  "qr_url": "https://porezna.gov.hr/rn?jir=...&datv=...&izn=49.90",
  "status": "fiscalized"
}

GET /v1/racuni/:id — status računa

curl https://fiskalizacija.netlify.app//api/v1/racuni/<id> -H "Authorization: Bearer <api_kljuc>"

Vraća račun (scoped na tvog merchanta): broj, iznos, status, JIR, ZKI, QR.

POST /v1/eracuni — izdavanje B2B eRačuna (Fiskalizacija 2.0)

Izdaje strukturirani eRačun (EN 16931 / UBL 2.1) drugoj tvrtki preko posrednika. Izdavatelj = tvoj merchant.

curl -X POST https://fiskalizacija.netlify.app//api/v1/eracuni \
  -H "Authorization: Bearer <api_kljuc>" \
  -H "Content-Type: application/json" \
  -d '{
    "broj": "ER-1",
    "datumIzdavanja": "2026-01-15",
    "primatelj": { "oib": "12345678903", "naziv": "Kupac d.o.o." },
    "stavke": [
      { "naziv": "Usluga", "kolicina": 2, "cijena": 100, "stopaPdv": 25 }
    ]
  }'

Odgovor 200

{ "id": "uuid", "status": "sent", "providerRef": "..." }

Idempotencija

Pošalji zaglavlje Idempotency-Key (npr. ID narudžbe). Ponovljeni zahtjev s istim ključem vraća isti račun umjesto da fiskalizira dvaput — sigurno za retry.

Webhookovi

Registriraj HTTPS endpoint u portalu (/app → Webhookovi) i pretplati se na događaje. Šaljemo POST s JSON tijelom kad se dogode. Događaji: invoice.fiscalized, invoice.failed, einvoice.sent, einvoice.failed.

Zaglavlja + tijelo

X-Fiskal-Event: invoice.fiscalized
X-Fiskal-Delivery: <uuid isporuke>
X-Fiskal-Signature: sha256=<hmac>

{
  "event": "invoice.fiscalized",
  "created_at": "2026-01-15T10:00:00.000Z",
  "data": { "id": "uuid", "broj_racuna": "1", "jir": "...", "zki": "...", "status": "fiscalized" }
}

Provjeri potpis: HMAC-SHA256 nad sirovim tijelom sa svojim webhook secretom (dobiven jednom pri kreiranju), usporedi s X-Fiskal-Signature. Neuspjele isporuke (ne-2xx / timeout) ponavljamo s backoffom.

Kodovi grešaka

Format greške: { "error": "poruka" }