POST/v1/invoices/fiscalize

Fiskalizacija računa

Fiskalizirajte gotovinski ili kartični račun i dobijte JIR (Jedinstveni Identifikator Računa) od Porezne uprave. JIR i ZKI moraju biti ispisani na računu.

Kada trebate fiskalizirati?

Fiskalizacija (F1) je obavezna za sve gotovinske i kartične naplate. Za B2B račune koji se plaćaju virmanom, fiskalizacija nije potrebna — ali od 2026. morate slati eRačune.

Request

POST /v1/invoices/fiscalizeapplication/json

{
  "invoice_number": "1/1/1",
  "business_unit": "POSLOVNICA1",
  "register_id": "BLAG1",
  "issued_at": "2026-01-04T14:30:00+01:00",
  "payment_method": "card",
  "operator_oib": "12345678901",

  "items": [
    {
      "name": "Usluga programiranja",
      "quantity": 8,
      "unit_price": 50.00,
      "tax_rate": 25
    },
    {
      "name": "Hosting (mjesečni)",
      "quantity": 1,
      "unit_price": 20.00,
      "tax_rate": 25
    }
  ],

  "buyer": {
    "oib": "98765432109",
    "name": "Kupac d.o.o."
  },

  "metadata": {
    "internal_id": "INV-2026-0001",
    "project": "Website redesign"
  }
}

Obavezni parametri

Parametar	Tip	Opis
`invoice_number`	string	Broj računa u formatu `broj/prostor/uredaj`
`business_unit`	string	Oznaka poslovnog prostora (registrirano kod Porezne)
`register_id`	string	Oznaka naplatnog uređaja
`payment_method`	enum	`cash` \| `card` \| `other`
`operator_oib`	string	OIB osobe koja izdaje račun (11 znamenki)
`items`	array	Stavke računa (minimalno 1)

Stavke računa (items)

Parametar	Tip	Obavezno	Opis
`name`	string	Da	Naziv proizvoda/usluge
`quantity`	number	Da	Količina (može biti decimalna)
`unit_price`	number	Da	Jedinična cijena bez PDV-a (EUR)
`tax_rate`	number	Da	Stopa PDV-a: 25, 13, 5, ili 0
`discount`	number	Ne	Popust u postotku (0-100)

Opcionalni parametri

Parametar	Tip	Opis
`issued_at`	datetime	Vrijeme izdavanja (ISO 8601). Default: sada
`buyer`	object	Podaci o kupcu (OIB i ime)
`metadata`	object	Vaši custom podaci (ne šalju se Poreznoj)
`subsequent`	boolean	Naknadno slanje (ako nije bilo veze s Poreznom)
`paragon_number`	string	Broj paragon bloka (za naknadno slanje)

Response

Uspješan odgovor (201 Created)

201 Created

{
  "id": "inv_abc123def456",
  "status": "fiscalized",
  "jir": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "zki": "f47ac10b58cc4372a5670e02b2c3d479",
  "invoice_number": "1/1/1",
  "issued_at": "2026-01-04T14:30:00+01:00",
  "fiscalized_at": "2026-01-04T14:30:01+01:00",

  "amounts": {
    "subtotal": 420.00,
    "tax_25": 105.00,
    "tax_13": 0.00,
    "tax_5": 0.00,
    "total": 525.00,
    "currency": "EUR"
  },

  "qr_code": "https://api.fiskalapi.hr/v1/invoices/inv_abc123/qr.png",
  "verification_url": "https://porezna.gov.hr/provjera?jir=a1b2c3d4...",
  "pdf_url": "https://api.fiskalapi.hr/v1/invoices/inv_abc123/pdf",

  "metadata": {
    "internal_id": "INV-2026-0001",
    "project": "Website redesign"
  }
}

Response polja

Polje	Opis
`id`	FiskalAPI interni ID računa
`jir`	Jedinstveni Identifikator Računa — mora biti ispisan na računu!
`zki`	Zaštitni Kod Izdavatelja — hash potpisa, mora biti na računu
`status`	`fiscalized` \| `pending` \| `failed`
`amounts`	Izračunati iznosi po stopama PDV-a
`qr_code`	URL za QR kod (za ispis na računu)
`verification_url`	Link za provjeru računa na Poreznoj
`pdf_url`	URL za preuzimanje PDF računa

Obavezno na računu

Po zakonu, na fiskalnom računu moraju biti ispisani: JIR, ZKI, i QR kod za provjeru. Kupac mora moći skenirati QR i provjeriti račun na Poreznoj.

Primjeri koda

cURL

Bash

curl -X POST https://sandbox.fiskalapi.hr/v1/invoices/fiscalize \
  -H "Authorization: Bearer sk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "1/1/1",
    "business_unit": "POSLOVNICA1",
    "register_id": "BLAG1",
    "payment_method": "card",
    "operator_oib": "12345678901",
    "items": [{
      "name": "Usluga",
      "quantity": 1,
      "unit_price": 100.00,
      "tax_rate": 25
    }]
  }'

JavaScript (Node.js)

JavaScript

import FiskalAPI from '@fiskalapi/node';

const fiskal = new FiskalAPI(process.env.FISKALAPI_KEY);

try {
  const invoice = await fiskal.invoices.fiscalize({
    invoice_number: '1/1/1',
    business_unit: 'POSLOVNICA1',
    register_id: 'BLAG1',
    payment_method: 'card',
    operator_oib: '12345678901',
    items: [
      {
        name: 'Usluga programiranja',
        quantity: 8,
        unit_price: 50.00,
        tax_rate: 25
      },
      {
        name: 'Hosting',
        quantity: 1,
        unit_price: 20.00,
        tax_rate: 25
      }
    ],
    buyer: {
      oib: '98765432109',
      name: 'Kupac d.o.o.'
    }
  });

  console.log('JIR:', invoice.jir);
  console.log('ZKI:', invoice.zki);
  console.log('Ukupno:', invoice.amounts.total, 'EUR');
  console.log('PDF:', invoice.pdf_url);

} catch (error) {
  if (error.code === 'fiscalization_failed') {
    console.error('Porezna odbila račun:', error.message);
  } else if (error.code === 'invalid_oib') {
    console.error('Neispravan OIB:', error.message);
  } else {
    console.error('Greška:', error.message);
  }
}

Python

from fiskalapi import FiskalAPI, FiskalAPIError
import os

fiskal = FiskalAPI(os.environ['FISKALAPI_KEY'])

try:
    invoice = fiskal.invoices.fiscalize(
        invoice_number='1/1/1',
        business_unit='POSLOVNICA1',
        register_id='BLAG1',
        payment_method='card',
        operator_oib='12345678901',
        items=[
            {
                'name': 'Usluga programiranja',
                'quantity': 8,
                'unit_price': 50.00,
                'tax_rate': 25
            },
            {
                'name': 'Hosting',
                'quantity': 1,
                'unit_price': 20.00,
                'tax_rate': 25
            }
        ],
        buyer={
            'oib': '98765432109',
            'name': 'Kupac d.o.o.'
        }
    )

    print(f'JIR: {invoice.jir}')
    print(f'ZKI: {invoice.zki}')
    print(f'Ukupno: {invoice.amounts.total} EUR')
    print(f'PDF: {invoice.pdf_url}')

except FiskalAPIError as e:
    print(f'Greška {e.code}: {e.message}')

Greške

HTTP	Kod	Opis
`400`	`invalid_request`	Neispravan JSON ili nedostaju obavezni parametri
`400`	`invalid_oib`	OIB operatera ili kupca nije valjan (11 znamenki, kontrolna)
`400`	`invalid_tax_rate`	PDV stopa mora biti 25, 13, 5, ili 0
`400`	`duplicate_invoice`	Račun s tim brojem već postoji u tom poslovnom prostoru
`422`	`fiscalization_failed`	Porezna odbila račun (detalji u message)
`503`	`porezna_unavailable`	Porezna trenutno nedostupna — pokušajte ponovno

Primjer error responsa

400 Bad Request

{
  "error": {
    "code": "invalid_oib",
    "message": "OIB operatera '1234567890' nije valjan. OIB mora imati 11 znamenki i ispravnu kontrolnu znamenku.",
    "doc_url": "https://fiskalapi.hr/dokumentacija/fiskalizacija"
  }
}

Sandbox testiranje

U sandbox okruženju možete koristiti ove OIB-ove za simulaciju različitih scenarija:

OIB	Ponašanje
`11111111111`	Uvijek uspješna fiskalizacija
`22222222222`	Simulira timeout Porezne (503)
`33333333333`	Porezna odbija račun (422)
`44444444444`	Simulira spor odgovor (5+ sekundi)

Sljedeći koraci

Provjera statusa računa

GET /v1/invoices/{id}

Storniranje računa

Poništenje fiskaliziranog računa

Slanje eRačuna (B2B)

POST /v1/einvoices/send

Webhooks

Real-time notifikacije