API dokumentacija

Developer API (v1) za provjeru informacijskog posrednika za eRačun – samo uz API ključ.

OpenAPI / Swagger
Specifikacija: openapi.yaml · Preporuka: koristi Swagger UI u vlastitom okruženju za pregled i testiranje.

1) Osnove

API je namijenjen integracijama (ERP, računovodstveni softver, B2B portali, middleware). Pristup je moguć isključivo uz važeći API ključ kreiran u panelu. Ključ je dodatno ograničen na domenu (Origin/Referer) kako bi se smanjila zloupotreba u browser scenarijima.

Base URL
/api/v1
Svi endpointi su verzionirani pod /api/v1.
Autentikacija
Header: X-API-Key: <KEY>
Alternativno: ?api_key=<KEY>
Bez ključa API vraća 401.

2) Domena i CORS

Ako je ključ zaključan na domenu, browser zahtjevi moraju dolaziti s dopuštenog Origin ili Referer. Server-to-server pozivi (iz backenda) tipično nemaju Origin; u tom slučaju i dalje je potreban valjani API ključ, a preporuka je pozivati API iz backenda (ključ držati u ENV varijablama).

3) Standardni response format

Svi v1 endpointi vraćaju konzistentan JSON “envelope”: 

{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "request_id": "…",
    "timestamp": "2026-01-23T10:15:30Z",
    "version": "v1"
  }
}
U slučaju greške, success je false, a error je objekt s poljima code, message i request_id. request_id je isti kao u meta.request_id i u headeru X-Request-Id (korisno za debug i podršku).

3.1) Rate limit i kvote

API ima zaštitu od zloupotrebe: rate limit (po API ključu i IP-u) te dnevne kvote. U slučaju prekoračenja, API vraća 429.

4) Endpointi

GET /api/v1/check
Provjera po OIB-u ili GLN-u. Vraća 200 uz polje found (true/false). Dostupno je i slanje putem POST s JSON bodyjem: {"idType":"OIB","identifier":"..."}.
Query parametri
  • type: OIB ili GLN (default: OIB)
  • id: identifikator (samo znamenke)
  • Alternativno: oib ili gln (GET), ili idType + identifier (GET/POST JSON)
Primjer (cURL)
curl -H "X-API-Key: <KEY>" \
  "/api/v1/check?type=OIB&id=12345678901"
GET /api/v1/intermediaries
Paginirani popis certificiranih posrednika (filtri i sortiranje).
Query parametri
  • q: pretraga po nazivu
  • service: eracun, eizvjestavanje, mps, ams
  • sort: name ili oib
  • order: asc ili desc
  • page: broj stranice (min 1)
  • per_page: 1–100 (default 50)
Primjer (cURL)
curl -H "X-API-Key: <KEY>" \
  "/api/v1/intermediaries?service=eracun&q=račun&page=1&per_page=25"
GET /api/v1/stats
Informativni pregled kvota i potrošnje za trenutni API ključ (sigurno za izlaganje vlasniku ključa).
curl -H "X-API-Key: <KEY>" \
  "/api/v1/stats"

5) Anti-abuse i preporuke

  • Cache: ne provjeravaj isti OIB iznova u kratkom periodu (TTL 24h ili više, ovisno o riziku).
  • Backoff: kod 429 uspori i ponovi kasnije (npr. 10s → 30s → 60s).
  • Sigurnost: nikada ne logiraj API ključ; koristi maskiranje i rotaciju ključa.
Važno
Ovaj API je za integracije i ne zamjenjuje interne poslovne procedure (odobravanje/odbijanje, arhiviranje, odgovornosti).