Toto aplikační rozhraní umožňuje integrovat služby Sokordia iSpis do Vašeho vlastního software, např. lustraci v centrálních evidencích exekucí do vašeho rozhodovacího procesu.

API je založeno na HTTPS GET/POST. 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 povolenou metodou.

1. Zadáním přihlašovacího e-mailu a hesla v query parametrech email/password.
2. Pomocí HTTP Basic autentizace, kdy login a heslo jsou zasílány ve standardní hlavičce Authorization.
3. Pomocí OAuth 2.0 autentizace: přístupový token získáte přes endpoint /oauth/token zadáním loginu a hesla; získaný token pak uveďte v hlavičce 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"

Pro produkční přístup doporučujeme založit si speciální účet s oprávněním jen k dané službě a použít autentizaci OAuth 2.0. Pro omezení přístupu k API na konkrétní IP adresy, případně pro nastavení dalších parametrů přístupu, nás neváhejte kontaktovat.

Single queries

The API can be used for on-line queries or for bulk (batch) screenings. For single queries the lustraceSearchSubject function is enough: you pass a person and a screening profile, and the result is returned immediately as a list of key/value pairs, e.g. the key CEEPocet with the value 0.

Bulk (batch) processing

For bulk screenings you create a batch and then poll its processing status periodically.

The batch is created with lustraceCreateBatch, which takes an array (set) of persons and a screening profile and returns a batch identifier generated by the system, e.g. 20150101.100. With lustraceBatchDetails you can then poll the processing status of the batch and, once it is finished, download all results.

Input parameters and output format

The input is typically a person, given by first name, surname and date of birth, or by the personal identification number, or by the company ID. Some registers accept other inputs as well (e.g. a file number for a file detail, or a document number for a document validity check).

The screening profile is one of the preconfigured lists of registers you want to query. They are listed in the screening form on the Screening page, e.g. Zakladni,CEE or ExeSR. If you want a single register, its code can be used as the profile (see the list of registers). On request we can create a custom profile (a combination of registers) for you.

The particular keys that may appear in the output are described in the documentation of the registers you queried.

The overview and description of all available REST API functions (cases, claims, payments, screening, ...) is in the API documentation.

Input parameters:

• profile – screening profile (e.g. "CEE", "ISIR", "Devel", ...).
• Jmeno, Prijmeni, Narozen, RC, IC, ... – a meaningful subset identifying the person.

Output values:

• batchId: our ID assigned to the screening (also shown in Billing etc.).
• done: always 1 for single screenings.
• warnings: errors, if any, to be shown to the user.
• files: names of the attachments of the screening output.
• detail: list of key/value pairs with the screening result itself.
• costCents: price of the query in hundredths (hellers / cents) including VAT. A contractual flat fee for the service (typically for bailiff offices) is not included.
• balanceCents: credit balance in hundredths including VAT after the query has been charged.

Example

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
}

The output itself is in the detail field. The particular keys that may appear there are described in the documentation of the registers you queried.

For historical reasons, keys ending in JSON are given as text values in JSON format.

We recommend storing the detail field on your side again as a list of key/value pairs (or as JSON).

For development and testing of the screening API you can use theDevel register, which is free of charge.

For a natural person on input, this register returns the surname in the vocative form and a Complex_JSON structure.

For a legal entity (company ID) it returns one PDF document.