POST/v1/invoices/fiscalize

Fiskalizacija računa

Fiskalizirajte gotovinski ili kartični račun i dobijte JIR (Jedinstveni Identifikator Računa) koji mora biti ispisan na računu.

Request

POST /v1/invoices/fiscalizeapplication/json

{
  "invoice_number": "1/1/1",
  "business_unit": "POSLOVNICA1",
  "register_id": "BLAG1",
  "issued_at": "2026-01-03T14:30:00+01:00",
  "payment_method": "card",
  "operator_oib": "12345678901",
  
  "items": [
    {
      "name": "Usluga programiranja",
      "quantity": 1,
      "unit_price": 100.00,
      "tax_rate": 25,
      "kpd": "J62.01.11"
    },
    {
      "name": "Hosting (mjesečni)",
      "quantity": 1,
      "unit_price": 20.00,
      "tax_rate": 25,
      "kpd": "J63.11.12"
    }
  ],

  "buyer": {
    "oib": "98765432109",
    "name": "Firma 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/uređaj`
`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
`items`	array	Stavke računa (min. 1)

Stavke računa (items)

Parametar	Tip	Opis
`name`	string	Naziv proizvoda/usluge
`quantity`	number	Količina
`unit_price`	number	Jedinična cijena (bez PDV-a)
`tax_rate`	number	Stopa PDV-a (25, 13, 5, ili 0)
`kpd`	string	KPD šifra (obavezno za eRačune)

Opcionalni parametri

Parametar	Tip	Opis
`issued_at`	datetime	Vrijeme izdavanja (default: now)
`buyer`	object	Podaci o kupcu (OIB, ime)
`metadata`	object	Vaši custom podaci (ne šalju se Poreznoj)
`subsequent`	boolean	Naknadno slanje (ako nije bilo veze)

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-03T14:30:00+01:00",
  "fiscalized_at": "2026-01-03T14:30:01+01:00",
  
  "amounts": {
    "subtotal": 120.00,
    "tax_25": 30.00,
    "tax_13": 0.00,
    "tax_5": 0.00,
    "total": 150.00,
    "currency": "EUR"
  },

  "qr_code": "https://api.fiskalapi.hr/v1/invoices/inv_abc123/qr",
  "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 na računu!
`zki`	Zaštitni Kod Izdavatelja — hash potpisa
`status`	`fiscalized`, `pending`, `failed`
`qr_code`	URL za QR kod za provjeru na Poreznoj
`pdf_url`	URL za gotov PDF računa

Primjeri koda

Node.js (SDK)

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',
        quantity: 1,
        unit_price: 100.00,
        tax_rate: 25,
        kpd: 'J62.01.11'
      }
    ]
  });

  console.log('JIR:', invoice.jir);
  console.log('PDF:', invoice.pdf_url);
  
} catch (error) {
  if (error.code === 'fiscalization_failed') {
    console.error('Porezna odbila račun:', error.message);
  }
}

Python

from fiskalapi import FiskalAPI
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',
            'quantity': 1,
            'unit_price': 100.00,
            'tax_rate': 25,
            'kpd': 'J62.01.11'
        }]
    )

    print(f'JIR: {invoice.jir}')
    print(f'PDF: {invoice.pdf_url}')

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

cURL

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,
      "kpd": "J62.01.11"
    }]
  }'

Greške

HTTP	Kod	Opis
`400`	`invalid_request`	Neispravan JSON ili nedostaju parametri
`400`	`invalid_oib`	OIB operatera ili kupca nije valjan
`400`	`duplicate_invoice`	Račun s tim brojem već postoji
`422`	`fiscalization_failed`	Porezna odbila račun (detalji u message)
`503`	`porezna_unavailable`	Porezna trenutno nedostupna

Sandbox testiranje

U sandbox okruženju možete koristiti ove OIB-ove za testiranje:

11111111111 — uvijek uspješna fiskalizacija
22222222222 — simulira timeout Porezne
33333333333 — simulira odbijanje računa

Sljedeći koraci

Provjera statusa

GET /v1/invoices/{id}

Poništenje računa

Storniranje fiskaliziranog računa