KYC.hr API – upute za integraciju

Pregled

KYC.hr API omogućuje da provjeru stranaka pokrenete izravno iz svog sustava (core banking, CRM, web shop, aplikacija za registraciju korisnika), bez ručnog unosa u aplikaciju KYC.hr. Jednim pozivom stranka se provjerava na:

• sankcijskim listama (UN, EU, OFAC, UK i ostale liste koje KYC.hr prati),
• listama politički izloženih osoba (PEP), samo za fizičke osobe,
• listi crnih banaka, ako pošaljete naziv banke stranke,
• negativnim medijskim objavama (adverse media), ako to zatražite.

Rezultat provjere je status podudaranja i popis pronađenih pogodaka. Svaka provjera se sprema i možete je kasnije ponovno dohvatiti ili pregledati u aplikaciji KYC.hr.

Osnovna adresa API-ja: https://api.kyc.hr

Svi zahtjevi i odgovori su u JSON formatu (Content-Type: application/json). Datumi su u ISO 8601 formatu (npr. 2026-10-02T14:35:12Z).

Kako dobiti pristup

1. Ugovorite API paket u aplikaciji KYC.hr. API pretplata je zasebna i neovisna o pretplati na korištenje aplikacije.
2. Nakon aktivacije paketa u aplikaciji KYC.hr, na stranici za API ključeve generirajte svoj ključ.
3. Ključ se prikazuje samo jednom, odmah nakon generiranja. Spremite ga na sigurno mjesto. KYC.hr ne čuva ključ u čitljivom obliku i ne može vam ga ponovno prikazati. Ako ga izgubite, generirajte novi ključ, a stari time prestaje vrijediti.

API ključ ima oblik kyc_live_ iza kojeg slijede 64 znaka. Ključ nikada ne ugrađujte u kod koji se izvršava kod korisnika (preglednik, mobilna aplikacija). API pozivajte isključivo sa svog poslužitelja.

Autentikacija

Svaki zahtjev mora sadržavati API ključ u headeru X-Api-Key:

X-Api-Key: kyc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ako ključ nedostaje, nije ispravan, istekao je ili je pretplata neaktivna, API vraća 401 Unauthorized:

{
  "error": "unauthorized",
  "message": "Provide a valid X-Api-Key header."
}

Nova provjera stranke

POST /v1/screenings

Pokreće provjeru jedne stranke. Provjera traje od jedne do nekoliko sekundi, ovisno o tome koje se provjere izvršavaju.

Parametri zahtjeva

Provjera politički izloženih osoba radi se samo za subjectType = person.

Primjer zahtjeva (curl)

curl -X POST https://api.kyc.hr/v1/screenings \
  -H "X-Api-Key: kyc_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectType": "person",
    "name": "Ivan",
    "surname": "Horvat",
    "dateOfBirth": "1975-04-21",
    "countryCode": "HR",
    "includeAdverseMedia": true,
    "externalReference": "KLIJENT-10045"
  }'

Primjer odgovora (201 Created)

{
  "screeningId": "3f2b8c1e-5d7a-4e9b-9c21-7a6f0d4e8b13",
  "subjectType": "person",
  "name": "Ivan",
  "surname": "Horvat",
  "externalReference": "KLIJENT-10045",
  "createdAt": "2026-10-02T14:35:12Z",
  "durationMs": 1240,
  "matchStatus": "NMTCH",
  "checks": {
    "sanctions":     { "performed": true,  "hit": false, "hitCount": 0 },
    "pep":           { "performed": true,  "hit": false, "hitCount": 0 },
    "bankBlackList": { "performed": false, "hit": false, "hitCount": 0 },
    "adverseMedia":  { "performed": true,  "hit": false, "hitCount": 0 }
  },
  "hits": []
}

Odgovor sadrži i header Location s adresom na kojoj se ista provjera može ponovno dohvatiti.

Polja odgovora

Pogoci (hits)

Svaki pogodak opisuje jedno pronađeno podudaranje. Ovisno o vrsti pogotka, popunjena su različita polja:

Dohvat jedne provjere

GET /v1/screenings/{screeningId}

Vraća spremljenu provjeru u istom obliku kao odgovor na POST /v1/screenings. Dohvatiti možete samo provjere napravljene vašim ključevima. Ako provjera ne postoji, API vraća 404 Not Found.

curl https://api.kyc.hr/v1/screenings/3f2b8c1e-5d7a-4e9b-9c21-7a6f0d4e8b13 \
  -H "X-Api-Key: kyc_live_xxxxxxxx"

Popis provjera

GET /v1/screenings?from=&to=&page=&pageSize=

Svaka stavka popisa sadrži screeningId, subjectType, name, surname, externalReference, createdAt, matchStatus te oznake sanctionsHit, pepHit, bankBlackListHit i adverseMediaHit. Detalje pogodaka dohvatite pozivom za jednu provjeru.

curl "https://api.kyc.hr/v1/screenings?from=2026-10-01&page=1&pageSize=50" \
  -H "X-Api-Key: kyc_live_xxxxxxxx"

Statusi podudaranja

Status podudaranja je rezultat automatske provjere imena i ne zamjenjuje procjenu rizika stranke koju ste dužni provesti prema Zakonu o sprječavanju pranja novca i financiranja terorizma.

Ograničenja i masovne provjere

Da bi API ostao brz i dostupan svim korisnicima, primjenjuju se sljedeća ograničenja:

• najviše 20 zahtjeva u minuti po API ključu,
• najviše 4 provjere istovremeno na razini cijelog API-ja, uz kratki red čekanja,
• mjesečna kvota provjera prema ugovorenom paketu.

Kada se ograničenje prekorači, API vraća 429 Too Many Requests. Kod prekoračenja broja zahtjeva odgovor sadrži header Retry-After s brojem sekundi nakon kojih zahtjev možete ponoviti. Kod prekoračene mjesečne kvote odgovor je:

{
  "error": "quota_exceeded",
  "message": "..."
}

Kako provjeriti veći broj stranaka

Svaka stranka provjerava se zasebnim pozivom, a jedna provjera traje od jedne do nekoliko sekundi. Za masovne provjere (npr. cijela baza klijenata):

• šaljite zahtjeve jedan za drugim, a ne sve odjednom,
• ne šaljite više od 20 zahtjeva u minuti,
• na odgovor 429 pričekajte broj sekundi iz headera Retry-After i ponovite isti zahtjev,
• u externalReference šaljite svoju oznaku stranke, kako biste rezultate lakše povezali sa svojom bazom.

Primjer: C#

using System.Net;
using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.kyc.hr") };
http.DefaultRequestHeaders.Add("X-Api-Key", "kyc_live_xxxxxxxx");

foreach (var stranka in stranke)
{
    while (true)
    {
        var response = await http.PostAsJsonAsync("/v1/screenings", new
        {
            subjectType = "person",
            name = stranka.Ime,
            surname = stranka.Prezime,
            dateOfBirth = stranka.DatumRodjenja,
            externalReference = stranka.BrojKlijenta
        });

        if (response.StatusCode == (HttpStatusCode)429)
        {
            var retryAfter = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(60);
            await Task.Delay(retryAfter);
            continue;
        }

        response.EnsureSuccessStatusCode();
        var rezultat = await response.Content.ReadFromJsonAsync<ScreeningResponse>();
        // spremite rezultat.ScreeningId i rezultat.MatchStatus uz stranku
        break;
    }

    await Task.Delay(TimeSpan.FromSeconds(3)); // najviše 20 zahtjeva u minuti
}

Primjer: JavaScript (Node.js)

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

for (const stranka of stranke) {
  while (true) {
    const response = await fetch("https://api.kyc.hr/v1/screenings", {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.KYC_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        subjectType: "person",
        name: stranka.ime,
        surname: stranka.prezime,
        externalReference: stranka.brojKlijenta
      })
    });

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get("Retry-After") ?? 60);
      await sleep(retryAfter * 1000);
      continue;
    }

    const rezultat = await response.json();
    // spremite rezultat.screeningId i rezultat.matchStatus uz stranku
    break;
  }

  await sleep(3000); // najviše 20 zahtjeva u minuti
}

Kodovi odgovora

Testno okruženje

Za razvoj i testiranje integracije dostupno je zasebno testno okruženje na adresi https://testapi.kyc.hr. Radi jednako kao produkcijski API, ali s testnim podacima i zasebnim testnim ključem. Testni ključ zatražite na support@kyc.hr.