API dokumentacija

v1 API za provjeru službenih certificiranih informacijskih posrednika (OIB/GLN).

Swagger / OpenAPI

Osnove

API je namijenjen developerskim integracijama. Nakon registracije račun mora aktivirati administrator, nakon čega se generira API ključ. API podržava dva formata odgovora: XML (zadano) i JSON (samo ako pošaljete Accept: application/json).

Base URL

https://provjera-posrednika.com.hr/api/v1

Savjet: koristite HTTPS.

Autentikacija

API ključ šalje se u headeru:

X-API-Key: VAS_API_KLJUC

Ključ radi samo na domenama/originima koje je administrator odobrio (allowlist).

Endpointi

1) Provjera posrednika

Vraća status i popis usluga za OIB ili GLN.

GET /check?oib=85821130368

GET /check?gln=3851234567890

POST /check (JSON body)

2) Popis posrednika

Vraća cijeli popis (za cache i lokalno filtriranje).

GET /intermediaries

3) Status ključa i kvota (opcionalno)

Pomoćni endpointi za monitoring i debugging integracije.

GET /keys

GET /stats

Response format

Zadan format je XML. JSON se dobiva isključivo kada klijent pošalje Accept: application/json. U oba slučaja polja su semantički ista.

Primjer (curl) – XML

curl -s \
  -H "X-API-Key: VAS_API_KLJUC" \
  "https://provjera-posrednika.com.hr/api/v1/check?oib=85821130368"

Primjer (curl) – JSON

curl -s \
  -H "X-API-Key: VAS_API_KLJUC" \
  -H "Accept: application/json" \
  "https://provjera-posrednika.com.hr/api/v1/check?oib=85821130368"

Primjer (POST) – JSON body

curl -s \
  -H "X-API-Key: VAS_API_KLJUC" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"idType":"OIB","identifier":"85821130368"}' \
  "https://provjera-posrednika.com.hr/api/v1/check"

Primjeri integracije

Browser (JavaScript)

Browser integracije su dozvoljene samo s odobrenim Origin domenama. Ključ šaljete u headeru.

async function provjeriOib(oib) {
  const res = await fetch('https://provjera-posrednika.com.hr/api/v1/check?oib=' + encodeURIComponent(oib), {
    method: 'GET',
    headers: {
      'X-API-Key': 'VAS_API_KLJUC',
      'Accept': 'application/json'
    },
    // za browser: Origin će biti automatski postavljen
  });

  if (!res.ok) {
    // po potrebi: fallback poruka korisniku
    throw new Error('Provjera nije uspjela');
  }

  const data = await res.json();
  return data;
}

Server (PHP)

Server-side integracije su preporučene za veći promet. U primjeru se traži JSON radi jednostavnog parsiranja.

$oib = '85821130368';

$ch = curl_init('https://provjera-posrednika.com.hr/api/v1/check?oib=' . rawurlencode($oib));
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: VAS_API_KLJUC',
    'Accept: application/json',
  ],
  CURLOPT_TIMEOUT => 10,
]);

$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($code !== 200 || !$body) {
  throw new RuntimeException('Provjera nije uspjela');
}

$data = json_decode($body, true);

// Primjeri:
// - certificirani posrednik: $data['certified'] === true
// - web stranica (ako je dostupna): $data['broker']['website']
// - usluge: $data['broker']['services']['eracun'] / ['eizvjestavanje'] / ['mps']

Allowed origins (allowlist)

Kada se API koristi iz browsera, zahtjev sadrži Origin header. API će vratiti CORS header samo ako je origin odobren za taj ključ. Ako origin nije na allowlisti, integracija neće raditi.

Domena se odobrava u admin panelu nakon registracije.
Zahtjev za promjenu domene podnosi se u korisničkom panelu; administrator odobrava ili odbija.
Podržavamo isključivo točne (exact) origin vrijednosti, bez wildcards.

Rate-limit i kvote

U produkciji je uključena zaštita stabilnosti usluge:

Quota: 5000/day po ključu (hard reset prema Europe/Zagreb).
Browser limit: dodatno stroži limit za browser integracije, te per-origin limit.
Rate-limit: ograničenje po ključu i IP adresi (minute bucket).

Ako dobijete 429, smanjite učestalost poziva ili uvedite cache. Za veće potrebe kontaktirajte podršku.

Error codes

HTTP	Značenje	Primjer
`400`	Neispravan unos (npr. OIB nije valjan ili nedostaje parametar).	`{"error":"Invalid OIB."}`
`401`	Nedostaje ili je neispravan API ključ.	`{"error":"Unauthorized."}`
`403`	Zabranjeno (npr. origin nije odobren).	`{"error":"Forbidden."}`
`429`	Prekoračena kvota ili rate-limit.	`{"error":"Quota exceeded."}`
`500`	Privremeni problem. Pokušajte ponovno kasnije.	`{"error":"Service unavailable."}`

Napomene

OIB mora imati točno 11 znamenki i proći MOD11-10 provjeru.
Za integracije preporučujemo local cache (npr. 24h) uz periodičnu provjeru promjena u službenom popisu.
Ovaj API ne vraća interne tehničke detalje u slučaju greške.