Toto aplikačné rozhranie umožňuje integrovať služby Sokordia iSpis do Vášho vlastného softvéru, napr. lustráciu v centrálnych registroch exekúcií do vášho rozhodovacieho procesu.

API je založené na HTTPS GET/POST. Na jeho používanie musíte:

• Pristupovať iba cez zabezpečený protokol HTTPS.
• Byť v systéme zaregistrovaný.
• Autentizovať sa povolenou metódou.

1. Zadaním prihlasovacieho e-mailu a hesla v query parametroch email/password.
2. Pomocou HTTP Basic autentizácie, kedy login a heslo sú zasielané v štandardnej hlavičke Authorization.
3. Pomocou OAuth 2.0 autentizácie: prístupový token získate cez endpoint /oauth/token zadaním loginu a hesla; získaný token potom uveďte v hlavičke Authorization: Bearer .

   TOKEN=$(curl -s -X POST https://ispis.cz/oauth/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=(email)&client_secret=(password)' | jq -r .access_token) && curl -s https://ispis.cz/api/... -H "Authorization: Bearer $TOKEN"

Pre produkčný prístup odporúčame založiť si špeciálny účet s oprávnením len k danej službe a použiť autentizáciu OAuth 2.0. Pre obmedzenie prístupu k API na konkrétne IP adresy, prípadne pre nastavenie ďalších parametrov prístupu, nás neváhajte kontaktovať.

Jednotlivé dopyty

Aplikačné rozhranie je možné použiť na on-line dopyty alebo na hromadné (dávkové) lustrácie. Pri jednotlivých dopytoch si vystačíte s funkciou lustraceSearchSubject, ktorej zadáte osobu a typ lustrácie a výsledok lustrácie je okamžite vrátený ako pole dvojíc kľúčov a hodnôt, napr. kľúč CEEPocet s hodnotou 0.

Hromadné (dávkové) spracovanie

Pri hromadných (dávkových) lustráciách je potrebné založiť dávku na lustráciu a následne sa periodicky dopytovať na stav spracovania.

Pri zakladaní sa volá funkcia lustraceCreateBatch, ktorej sa zadáva pole (množina) osôb a typ lustrácie a vo výsledku je vrátený systémom vytvorený identifikátor dávky, napr. 20150101.100. Následne funkciou lustraceBatchDetails je možné sa periodicky dopytovať na stav spracovania dávky alebo po dokončení stiahnuť všetky výsledky.

Vstupné parametre a formát výstupov lustrácií

Na vstupe je typicky zadávaná osoba, a to pomocou mena, priezviska a dátumu narodenia alebo rodného čísla alebo IČO. Pri niektorých registroch je možné uviesť na vstupe aj iný údaj (napr. spisovú značku pri dopyte na detail spisovej značky, číslo dokladu pri dopyte na platnosť dokladu a pod.).

Typ lustrácie je jeden z predkonfigurovaných zoznamov registrov, do ktorých sa chcete dopytovať. Ich prehľad je uvedený v lustračnom formulári na stránke Lustrácie, napr. Zakladni, CEE či ExeSR. Ak chcete len jeden register, je možné ako typ lustrácie uviesť kód toho registra (pozri zoznam registrov). V prípade potreby Vám môžeme vytvoriť typ lustrácie (kombináciu registrov) na mieru.

Popis konkrétnych položiek, ktoré sa môžu vo výstupe objaviť, je uvedený v dokumentácii registrov, do ktorých ste sa dopytovali.

Prehľad a popis všetkých dostupných funkcií REST API (prípady, pohľadávky, platby, lustrácie, ...) nájdete v dokumentácii API.

Vstupné parametre:

• profile - typ lustrácie (napr. "CEE", "ISIR", "Devel", ...).
• Jmeno, Prijmeni, Narozen, RC, IC, ... - zmysluplná podmnožina definujúca osobu.

Výstupné hodnoty:

• batchId: naše ID pridelené lustrácii (uvedené aj v sekcii Vyúčtovanie a pod.).
• done: pri jednotlivých lustráciách vždy 1.
• warnings: prípadné chyby na zobrazenie používateľovi.
• files: zoznam názvov príloh k výstupu lustrácie.
• detail: zoznam dvojíc kľúčov a hodnôt s vlastným výsledkom lustrácie.
• costCents: cena vykonaného dopytu v centoch vrátane DPH. Do ceny nie je započítaná prípadná zmluvná paušálna cena služby (typicky pri exekútorských úradoch).
• balanceCents: stav kreditu v centoch vrátane DPH po zaúčtovaní ceny dopytu.
• code: len ak lustrácia neprebehla (napr. insufficient_credit: odpoveď je 200 s costCents: 0, prázdnym files a dôvodom vo warnings).

Príklad

curl -o output.json 'https://ispis.cz/api/lustraceSearchSubject?username=...&password=...&profile=Devel&Jmeno=Jan&Prijmeni=Svoboda&Narozen=14.6.1983'

{
  "batchId": "20151123.5",
  "detail": {
    "CasLustrace": "2014-11-23T22:29:59",
    "Complex_JSON": "[{"Date":"2014-11-23"},{"Time":"22:29:59"}]",
    "Devel": "test",
    "Jmeno": "Jan",
    "Narozen": "1981-03-14",
    "Osloveni": "Svobodo",
    "Prijmeni": "Svoboda"
  },
  "done": 1,
  "files": [],
  "warnings": null,
  "costCents": 3025,
  "balanceCents": 1241075
}

Vlastný výstup je teda v poli detail. Zoznam konkrétnych položiek, ktoré sa tam môžu objaviť, je uvedený v dokumentácii registrov, do ktorých ste sa dopytovali.

Z historických dôvodov sú kľúče končiace na JSON uvedené ako textové hodnoty vo formáte JSON.

Výstup z poľa detail odporúčame u Vás ukladať opäť ako zoznam dvojíc kľúčov a hodnôt (alebo ako JSON).

Na vývoj a testovanie API lustrácií je možné použiť register Devel, ktorý je zadarmo.

Pri zadaní fyzickej osoby na vstupe tento register vráti priezvisko osoby vo forme na oslovenie a tiež štruktúru Complex_JSON.

Pri zadaní právnickej osoby (IČO) vráti jeden PDF dokument.