REST API - Dokumentace pro vývojáře

V případě jakýckoliv dotazů nás neváhejte kontaktovat.

Toto aplikační rozhraní umožňuje integrovat službu Lustrace do Vašeho vlastního software. Můžete tak integrovat např. lustraci v Centrální evidenci exekucí či Centrálnom registri exekúcií do vašeho rozhodovacího procesu.

API je založeno na HTTPS GET/POST protokolu. K jeho používání musíte:

  • Přistupovat pouze přes zabezpečený protokol HTTPS.
  • Být v systému zaregistrován.
  • Autentizovat se zadáním přihlašovacího loginu a hesla.

Obecný popis API

Jednotlivé dotazy

Aplikační rozhraní je možno použít k on-line dotazům nebo k hromadným (dávkovým) lustracím. U jednotlivých dotazů si vystačíte s funkcí lustraceSearchSubject, které zadáte osobu a typ lustrace a výsledek lustrace je okamžitě vrácen jako pole dvojic klíčů a hodnot, např. klíč CEEPocet s hodnotou 0.

Hromadné (dávkové) zpracování

U hromadných (dávkových) lustrací je potřeba založit dávku k lustraci a následně se periodicky dotazovat na stav zpracování.

Při zakládání se volá funkce lustraceCreateBatch zadává pole (množina) osob a typ lustrace a ve výsledku je vrácen systémem vytvořený identifikátor dávky, např. 20150101.100. Následně funkcí lustraceBatchDetails je možno se periodicky dotazovat na stav zpracování dávky či po dokončení stáhnout všechny výsledky.

Vstupní parametry a formát výstupů lustrací

Na vstupu je typicky zadávaná osoba, a to pomocí jména, příjmení, data narození nebo rodného čísla nebo IČ. U některých rejstříků je možno uvést na vstupu i jiný údaj (např. spisovou značku při dotazu na detail spisové značky, číslo dokladu při dotazu na platnost dokladu apod.).

Typ lustrace je jeden z předkonfigurovaných seznamů rejstříků, do kterých se chcete dotázat. Jejich přehled je uveden v lustračním formuláři na stránce Lustrace, např. Zakladni, CEE či CRE. Platí, že pokud chcete jen jeden rejstřík, lze jako typ lustrace uvést kód toho rejstříku (viz Další rejstříky). V případě potřeby Vám můžete vytvořit typ lustrace (kombinaci rejstříků) na míru.

Popis konkrétních položek, které se můžou ve výstupu objevit, jsou uvedeny v dokumentaci rejstříků, do kterých jste se dotazovali.

Popis funkcí API

api/lustraceSearchSubject - jednotlivá on-line lustrace

Vstupní parametry:

  • username, password: autentizace.
  • profile: typ lustrace (např. "CEE", "CRE", "Devel",...).
  • Jmeno, Prijmeni,Narozen, RC,IC,...: smysluplná podmnožina definující osobu.

Výstupní hodnoty:

  • batchId: naše ID přidělené lustraci (uvedeno i v sekci Vyúčtování apod.).
  • done: u jednotlivých lustací vždy 1.
  • warnings: případné chyby pro zobrazení uživateli.
  • files: seznam názvů příloh k výstupu lustrace.
  • detail: seznam dvojic klíčů a hodnot s vlastním výsledkem lustrace.
  • html: kopie výstupních hodnot naformátovaných jako HTML fragment.
  • costCents: cena provedeného dotazu v haléřích včetně DPH. Do ceny není započítána případná smluvní paušální cena služby (typicky u EÚ).
  • balanceCents: stav kreditu v haléřích včetně DPH po zaúčtování ceny dotazu.

Příklad

curl -o vystup.json 'https://ispis.cz/api/lustraceSearchSubject?username=...&password=...&profile=Devel&Jmeno=Jan&Prijmeni=Novák&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": "Nováku",
    "Prijmeni": "Novák"
  },
  "done": 1,
  "files": [],
  "warnings": null,
  "html": "<table className='detail no-border' border=0><tbody className='no-border-x no-border-y'><tr><th align="left" valign="top">Jméno</th><td>Jan</td><td valign="bottom"></td></tr><tr><th align="left" valign="top">Příjmení</th><td>Novák</td><td valign="bottom"></td></tr><tr><th align="left" valign="top">Narozen</th><td>1981-03-14</td><td valign="bottom"></td></tr><tr><th align="left" valign="top">Devel</th><td>test</td><td valign="bottom"></td></tr><tr><th align="left" valign="top">Osloveni</th><td>Nováku</td><td valign="bottom"></td></tr><tr><th align="left" valign="top">Čas lustrace</th><td>2014-11-23T22:29:59</td><td valign="bottom"></td></tr><tr><th align="left" valign="top">Complex_JSON</th><td colSpan=2><table className='no-border'><thead className='no-border'><tr><th>Date</th><th>Time</th><th></th></tr></thead><tbody className='no-border-x no-border-y'>
<tr><td>2014-11-23</td><td></td><td></td></tr><tr><td></td><td>22:29:59</td><td></td></tr></tbody></table></td></tr></tbody></table>
"
}

Vlastní výstup je tedy v poli detail. Seznam konkrétních položek, které se můžou ve výstupu objevit, jsou uvedeny v dokumentaci rejstříků, do kterých jste se dotazovali.

Z historických důvodů jsou klíče končící na JSON uvedeny jako textové hodnoty v JSON formátě.

Výstup z pole detail doporučujeme u Vás ukládat opět jako seznam dvojic klíčů a hodnot (či jako JSON).

api/lustraceCreateBatch - vytvoření hromadné lustrace

Vstupní parametry:

  • username, password: autentizace.
  • profile: typ lustrace.
  • batchName: nepovinný název dávky (bude uveden např. v historii lustrací, ve Vyúčtování apod.)
  • inputJson: seznam osob k lustraci v JSON formátě, např. [{"IC":"29190088"}]

Výstupní hodnoty:

  • batchId: naše ID přidělené lustraci, pro další dotazování na stav a stažení výsledků.

Na vstupu můžete u osoby zadat položku ID neboRefNo obsahující Váš identifikátor osoby, resp. dotazu. Tento identifikátor bude vrácen ve výsledcích dotazu, což Vám usnadní zpětné párování vrácených výsledků.

Tuto funkci je vhodné volat pomocí POST metody, obzvláště u většího počtu lustrovaných subjektů.

Ukázka použití funkcí pro hromadné lustrace je uvedena v následující JavaScriptovém souboru:

api/lustraceBatchDetails - stažení výsledků hromadné lustrace

Vstupní parametry:

  • username, password: autentizace.
  • batchId: ID lustrace vrácené v předešlém kroku.

Výstupní hodnoty:

  • done: 1, pokud je dávka zpracována,null pokud ještě není.
  • warnings: případné chyby pro zobrazení uživateli.
  • subjects: seznam výsledků lustrace.
  • costCents: po dokončení lustrace dávky obsahuje cenu lustrace v haléřích včetně DPH. Do ceny není započítána případná smluvní paušální cena služby (typicky u EÚ).
  • balanceCents: stav kreditu v haléřích včetně DPH po zaúčtování ceny dotazu.

Tuto funkci je potřeba volat opakovaně v intervalu nanejvýš jednou za 10 sekund, dokud nebude v položce done uvedena hodnota1. Do té doby se dávka zpracovává - buď čeká ve frontě nebo jsou zadané osoby postupně lustrovány.

Pokud je dávka zpracována, jsou výsledky uloženy v seznamusubjects - po jednom výsledku pro každou osobu na vstupu. Výsledek je opět ve tvaru pole klíčů a hodnot, shodně s výstupem funkce lustraceSearchSubject.

Ukázka použití funkcí pro hromadné lustrace je uvedena v následující JavaScriptovém souboru:

api/lustraceDownload - stažení přílohy

Některé rejstříky na výstupu generují PDF soubory s přílohou, např. el. podepsaný výpis z katastru nemovitostí apod.

Informace o přiložených souborech je u jednotlivých lustrací v poli files nebo u hromadných lustrací v poliPrilohy jako mezerou oddělený seznam názvů souborů.

Vstupní parametry:

  • username, password: autentizace.
  • batchId: ID lustrace vrácené v předešlém kroku.
  • lineno: pořadové číslo osoby v inputJson
    • (číslováno od nuly, 0 u jednotlivých lustrací).
  • name: název souboru z pole filesnebo Prilohy.

Výstupní hodnoty:

Tato funkce na výstupu vrací přímo binární obsah PDF souboru.

Testovací rozhraní

Pro vývoj a testování API lustrací je možno použít rejstříkDevel, který je zdarma.

Při zadání fyzické osoby na vstupu tento rejstřík vrátí příjmení osoby ve formě pro oslovení a také strukturu Complex_JSON.

Při zadání právnické osoby (IČ) vrátí jeden PDF dokument.