Autentifikacija

FiskalAPI koristi API ključeve za autentifikaciju svih zahtjeva. Svaki HTTP zahtjev mora sadržavati valjani API ključ u Authorization headeru.

Vrste API ključeva

Postoje dvije vrste API ključeva, ovisno o okruženju:

Okruženje	Prefix	Namjena
Sandbox	`sk_sandbox_`	Za testiranje - ne šalje stvarne račune Poreznoj
Production	`sk_live_`	Za produkciju - šalje stvarne račune Poreznoj

Sigurnosno upozorenje

API ključ tretirajte kao lozinku. Nikada ga ne uključujte u client-side kod (JavaScript u browseru, mobilne aplikacije). Sve API pozive radite sa servera.

Slanje API ključa

API ključ šaljete u Authorization headeru koristeći Bearer shemu:

HTTP Header

Authorization: Bearer sk_sandbox_abc123def456...

Base URL-ovi

Ovisno o vrsti ključa, koristite odgovarajući base URL:

Okruženje	Base URL
Sandbox	`https://sandbox.fiskalapi.hr/v1`
Production	`https://api.fiskalapi.hr/v1`

Primjeri koda

cURL

Bash

# Provjera API ključa
curl https://sandbox.fiskalapi.hr/v1/me \
  -H "Authorization: Bearer sk_sandbox_abc123def456..."

# Primjer responsa
{
  "tenant_id": "ten_abc123",
  "name": "Moja Firma d.o.o.",
  "oib": "12345678901",
  "plan": "startup",
  "environment": "sandbox"
}

JavaScript (Node.js)

JavaScript

// Sa službenim SDK-om (preporučeno)
import FiskalAPI from '@fiskalapi/node';

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

// Provjera autentifikacije
const me = await fiskal.me();
console.log('Tenant:', me.name);

// ----------------------------------------
// Bez SDK-a (plain fetch)
const response = await fetch('https://sandbox.fiskalapi.hr/v1/me', {
  headers: {
    'Authorization': `Bearer ${process.env.FISKALAPI_KEY}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

if (!response.ok) {
  throw new Error(data.error.message);
}

console.log('Tenant:', data.name);

Python

# Sa službenim SDK-om (preporučeno)
from fiskalapi import FiskalAPI
import os

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

# Provjera autentifikacije
me = fiskal.me()
print(f"Tenant: {me.name}")

# ----------------------------------------
# Bez SDK-a (requests)
import requests

response = requests.get(
    'https://sandbox.fiskalapi.hr/v1/me',
    headers={
        'Authorization': f"Bearer {os.environ['FISKALAPI_KEY']}",
        'Content-Type': 'application/json',
    }
)

if response.status_code != 200:
    raise Exception(response.json()['error']['message'])

data = response.json()
print(f"Tenant: {data['name']}")

Upravljanje API ključevima

API ključeve možete kreirati i upravljati u dashboardu:

Kreiranje — kreirajte nove ključeve za različite aplikacije ili servise
Imenovanje — dajte ključevima opisna imena (npr. "Production Server", "Staging")
Rotacija — generirajte novi ključ, stari ostaje aktivan 24h za graceful migration
Brisanje — trajno onemogućite ključ (odmah prestaje raditi)
IP whitelist — ograničite pristup samo na određene IP adrese

Greške autentifikacije

Ako autentifikacija ne uspije, API vraća jednu od sljedećih grešaka:

HTTP Status	Kod greške	Opis
`401`	`missing_api_key`	Authorization header nije poslan
`401`	`invalid_api_key`	API ključ nije valjan ili ne postoji
`401`	`api_key_revoked`	API ključ je opozvan/obrisan
`403`	`ip_not_allowed`	IP adresa nije na whitelisti
`403`	`wrong_environment`	Sandbox ključ korišten na production URL-u ili obrnuto

Primjer error responsa

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "Nevažeći API ključ. Provjerite da koristite ispravan ključ.",
    "doc_url": "https://fiskalapi.hr/dokumentacija/autentifikacija"
  }
}

Sigurnosne preporuke

1.Koristite environment varijable

Nikada ne hardkodirajte API ključ u kod. Koristite process.env.FISKALAPI_KEY,os.environ, ili slične mehanizme.

2.Odvojeni ključevi po okruženju

Koristite sandbox ključ za development i staging, a live ključ samo na produkciji. Nikada ne miješajte okruženja.

3.Redovita rotacija ključeva

Rotirajte production ključeve svakih 90 dana. Ako sumnjate na kompromitaciju, odmah generirajte novi ključ.

4.Postavite IP whitelist

Za production ključeve, ograničite pristup samo na IP adrese vaših servera. To sprječava korištenje ukradenog ključa s drugih lokacija.

5.Ne commitajte ključeve u Git

Dodajte .env i slične fajlove u .gitignore. Ako slučajno commitirate ključ, odmah ga rotirajte.

Sljedeći koraci

Fiskalizacija računa

POST /v1/invoices/fiscalize

Slanje eRačuna

POST /v1/einvoices/send