API dokumentacija

Integrirajte KPD provjeru u vlastiti sustav (ERP, webshop, CRM, izrada računa). Odgovor je isključivo XML. Za složenije upite možete koristiti operatore I (AND) i ILI (OR) unutar polja q. Operator se aktivira samo kad je napisan velikim slovima (I, ILI) ili kad upit izgleda kao kratka lista ključnih riječi (npr. stolica I stol, tiskanje ILI print). Obična riječ „i“ u rečenici (npr. prodaja i montaža) ne aktivira boolean način.

1) Zatražite API ključ

Za API ključ javite se na info@kpdinfo.com.hr ili preko kontakt forme na početnoj stranici. U poruci navedite domenu na kojoj ćete koristiti API.

2) Endpoint

POST https://kpdinfo.com.hr/api/suggest
Content-Type: application/x-www-form-urlencoded

3) Headeri

  • X-API-Key — vaš API ključ
  • X-API-Domain — domena integracije (preporuka za server-to-server)

4) Parametri

Polje Tip Obavezno Opis
q string da Opis stavke ili NKD šifra (npr. "izrada web stranica" ili "62.01").
context string ne auto (zadano), roba, usluga, servis (aliasi za proizvodnja/usluga).
cat string ne Opcionalno sužavanje po kategoriji (npr. it, grad, trg). Ako je upit kratak, kategorija značajno povećava preciznost.
detail string ne Dodatni detalj za veću preciznost (materijal, namjena, način isporuke).

5) XML odgovor

Odgovor uvijek sadrži: ok (1/0), message, error, total_checks, daily_limit, daily_remaining, opcionalni hintresults. Svaki rezultat može sadržavati i reason (obrazloženje) te opcionalno alternatives kada je prepoznat specifičan obrazac (npr. tisak roll-up bannera).

Primjer (skraćeno):
<response>
  <ok>1</ok>
  <message></message>
  <error></error>
  <total_checks>79658</total_checks>
  <results>
    <item>
      <code>62.10.11</code>
      <name>Usluge razvoja softvera</name>
      <score>0.91</score>
      <reason>Kontekst: usluga. Podudaranja u nazivu: ...</reason>
      <alternatives>
        <item>
          <code>...</code>
          <name>...</name>
          <reason>Kada koristiti alternativu...</reason>
        </item>
      </alternatives>
      <nkd>
        <code>62.01</code>
        <name>Računarsko programiranje</name>
      </nkd>
    </item>
  </results>
</response>

6) Error kodovi

  • missing_query — nedostaje parametar q
  • invalid_key — neispravan ili neaktivan API ključ
  • domain_not_allowed — domena nije dopuštena za ključ
  • rate_limited — previše zahtjeva u kratkom roku
  • daily_limit_reached — dostignut dnevni limit (vidi daily_limit i daily_remaining)

7) Limiti (guest / user / API ključ)

  • Guest (bez prijave): 1 upit/dan. Nakon toga API vraća daily_limit_reached i linkove za registraciju/prijavu.
  • Registrirani korisnik: 10 upita/dan (10 kredita). Preostalo se vidi u korisničkom panelu.
  • API ključ: limit po ključu (RPM + dnevni limit) definiran u licenci. U odgovor se uvijek uključuju daily_limit i daily_remaining.

8) Primjer integracije (PHP cURL)

<?php
$url = 'https://kpdinfo.com.hr/api/suggest';
$payload = http_build_query([
  'q' => 'izrada web stranica',
  'context' => 'auto',
  'detail' => 'CMS, održavanje',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/x-www-form-urlencoded',
    'X-API-Key: YOUR_API_KEY',
    'X-API-Domain: example.com',
  ],
]);

$xml = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code !== 200) { die('API greška'); }
$doc = simplexml_load_string($xml);
if ((string)$doc->ok !== '1') { die('API error: ' . (string)$doc->error); }

$best = $doc->results->item[0] ?? null;
if ($best) {
  echo (string)$best->code . ' - ' . (string)$best->name;
}
?>

KPD Info pomaže u brzoj i dosljednoj klasifikaciji. Za službena tumačenja i pisane potvrde nadležan je DZS.