# Centrální evidence exekucí (CEE) – napojení JustEx přes REST API

Zdroje: vývojářská sekce **https://www.ceecr.cz/dev** (Úvod, Změny od 1. 10. 2026, Strukturovaná jména, API reference v4.1.0, Číselníky dokumentů, Práce s cizinci, Testovací data, Changelog, FAQ) – staženo 8. 10. 2026, plný text uložen v `Downloads\CEE_dev_dokumentace_2026-10-08.txt`. Base URL ověřena reálným voláním `/api/v4/executorlist` (8. 10. 2026).

## Stav (aktuální)

- Dokumentace API **4.1.0** kompletně zpracována.
- **Uživatelský účet v CEE založen (9. 10. 2026):** uživatelské jméno `Daniel_Nemec`, e-mail daniel.nemec@bsptechnology.eu. Účet založil spřátelený exekutor jako správce kanceláře – účet je tedy uživatelem jeho exekutorské kanceláře (ne samostatný účet dodavatele).
- **Testovací API klíč + secret obdrženy (9. 10. 2026)** e-mailem od helpdesku CEE (Iva Havlíčková) na žádost odeslanou přímo Danielem. Ostrý klíč zatím nemáme. Hodnoty klíče se do dokumentace **neukládají** – drží je Daniel.
- Účet `Daniel_Nemec` má v CEE roli **„člen exekutorského úřadu“** – člen si klíč na webu sám vygenerovat nemůže (v Nastavení → API přístupy je jen odkaz na helpdesk). Viz kap. 2.1.
- Samostatné testovací prostředí neexistuje: test i produkce běží na stejné URL, rozdíl dělá jen **testovací vs. ostrý klíč**. I testovací klíč se vydává k uživatelskému účtu.
- **Testovací klíč ověřen (9. 10. 2026)** voláním `auth` + `token-info` z prohlížeče:
  - `api_version: "4.1.0"`, `structured_names: true`, `compatibility_mode: false` ✔
  - `user_type: 1` / `user_type_label: "testovací"` – testovací klíč má vlastní typ účtu (ne 9 = exekutor).
  - `executor_office_id: 176` = interní ID úřadu Mgr. Ondřej Svoboda, EÚ č. 184 (shoduje se s `executorlist`) ✔; `user_office_id: 23644`, `user_id: 195088`.
  - `rate_limit.enabled: false` – testovací klíč nemá limit požadavků.
  - `key_valid_till: "2026-10-09T08:39:00+02:00"` – dokumentace pole popisuje jako platnost klíče, ale čas přesně odpovídá odeslání e-mailu s klíčem z helpdesku a `auth` token přesto vydal (platný do 09:22:58). **Pracovní hypotéza (Daniel):** u testovacího klíče jde ve skutečnosti o datum a čas vytvoření klíče. Neověřeno – případně potvrdit u helpdesku.
- **Další krok (mimo tento dokument):** implementace a testy PHP třídy pro CEE se řeší v samostatném vlákně s vlastní dokumentací – tam ověřit, zda testovací klíč (`user_type: 1`) stačí na zápisové metody (`insert` apod.).
- Od **1. 10. 2026 platí jen API 4.1.0** – klíče pro 4.0.1 už nefungují. JustEx implementujeme rovnou na 4.1.0.

## 1. Co je CEE

- Neveřejně zapisovaná, veřejně lustrovatelná evidence exekucí vedená **Exekutorskou komorou ČR** (§ 125 EŘ, vyhl. č. 329/2008 Sb.). Web https://www.ceecr.cz.
- Exekutor **zapisuje** kauzy (povinní, oprávnění, dokumenty, exekuční tituly) a jejich ukončení. Lhůty: zápis do **3 dnů** od vyznačení doložky provedení exekuce; zastavení/skončení do 3 dnů od právní moci.
- Kromě zápisu umí API i **vyhledávání** (placené / FREE / evidenční „record“).
- Oddělený systém od CÚD (viz `claude/CUD_technicka_dokumentace.md`), vlastní API a klíče.
- Helpdesk: **helpdesk@ceecr.cz**, **+420 241 416 418** (Po–Pá 8–16). Ověřený kontakt (9. 10. 2026): **Iva Havlíčková**, Helpdesk CEE – vyřídila vydání testovacího API klíče.

## 2. Přístup a autentizace

### 2.1 Získání přístupu

1. Uživatelský účet na ceecr.cz (registrace zdarma).
2. Účet přepnout do **režimu soudního exekutora** – žádost na helpdesk@ceecr.cz. Kancelář exekutora může mít libovolný počet účtů; **správce kanceláře** spravuje uživatele.
3. **API klíč + secret – dvě cesty** (ověřeno 9. 10. 2026, potvrzeno telefonicky helpdeskem CEE):
   - **a) Správce exekutorského úřadu** vygeneruje klíč přímo na webu (Nastavení → API přístupy) – pro sebe i pro libovolného člena úřadu.
   - **b) Helpdesk** vydá klíč na e-mailovou žádost (helpdesk@ceecr.cz). Takto jsme získali testovací klíč 9. 10. 2026 – v žádosti uvedeno uživ. jméno, e-mail, kancelář a účel (vývoj zápisových metod pro JustEx); klíč přišel e-mailem.
   - Uživatel s rolí **„člen exekutorského úřadu“** si klíč na webu sám vygenerovat **nemůže** (v Nastavení → API přístupy vidí jen odkaz na helpdesk).
   - Zřízení je zdarma.
4. **Testovací klíč** je samostatný klíč – čte oddělené testovací tabulky, dotazy nejsou zpoplatněné.
5. Odběr novinek pro vývojáře exekutorů: požádat helpdesk o zařazení do „seznamu pro exekutory“.

Klíč je vázaný na **konkrétní uživatelský účet** (z něj se strhává kredit). Verzi API určuje klíč, ne URL. → **JustEx ukládá key+secret per uživatel CEE** (klíč se vždy váže na uživatele – telefonicky potvrzeno helpdeskem).

### 2.2 Token

```
GET https://www.ceecr.cz/api/v4/auth?api_key=…&api_secret=…
→ { "data": { "token_value": "…", "valid_for": "<IP>", "valid_till": "YYYY-MM-DD HH:MM:SS" }, "status": 200, "data_source": "regular|test" }
```

- Token je **vázaný na IP adresu**, ze které byl vyžádán (`valid_for` v odpovědi `auth`; z jiné IP chyba 5507) a má omezenou platnost → cachovat, při 5506/5508 obnovit.
- **IP adresu není potřeba nikam registrovat** – žádný whitelist, při žádosti o klíč se IP neřešila. Vazba vzniká až při vydání tokenu. Prakticky: token získaný na jednom stroji (např. vývojářský PC) nefunguje na jiném (server JustEx) – každé místo si volá `auth` samo.
- Token se předává **vždy v query** `?token=…` (i u POST).
- Chybné přihlášení → po N pokusech **blokace IP** (5503). Ošetřit, neopakovat naslepo.
- Žádný klientský certifikát ani podpis.

### 2.3 Kontrola po nasazení – `token-info`

`GET /api/v4/token-info?token=…` musí vrátit `api_version: "4.1.0"`, `structured_names: true`, `user_type: 9` (exekutor), `executor_office_id` ≠ null. Dále `key_valid_till` (platnost **klíče** – hlídat expiraci!), `ttl`, `rate_limit` (`enabled`, `limit`, `remaining`, `reset`). I `token-info` se počítá do rate limitu.

## 3. Prostředí

| | Hodnota |
|---|---|
| Base URL | `https://www.ceecr.cz/api/v4/` (stejná pro test i produkci) |
| Test vs. produkce | rozlišuje **klíč**; odpověď nese `data_source: "test"` / `"regular"` |

JustEx musí `data_source` logovat a v produkci odmítnout odpověď `test` (ochrana proti záměně klíčů).

## 4. Společné formáty a pravidla

- JSON, UTF-8. Těla POST: JSON, `application/x-www-form-urlencoded` nebo skalární části `multipart/form-data`. **Žádné soubory** (souborová část → 5513).
- **Chyby: HTTP je vždy 200**, skutečný stav je v JSON `status` (např. 500) + `data.code` + `data.message` + `data.datetime`. Klient musí vyhodnocovat `status`, ne HTTP kód.
- Klíče jen **snake_case**, rozlišují se velikosti písmen. U `update`, `updatesubject`, `updateeligible`, `updatedocument`, `terminate-*`, `search-eligible` je **neznámý klíč = chyba 5513** a nic se nezmění → posílat přesně dokumentovaná pole.
- „Mód kompatibility“ (camelCase) existuje v nastavení klíče – **nepoužívat**.
- ID (`cause_id`, `subject_id`, `document_id`, `eligible_id`, `enforcement_id`) jsou **krátké alfanumerické hashe, vždy string**.
- **Spisová značka** (EX číslo) – regex `^\d{3}EX(?!0)\d{1,6}\/\d{2}`, např. `999EX123/23`. Při zápisu se posílá rozdělená: `ex_cislo_preffix` (sic, dvě f), `ex_cislo_number`, `ex_cislo_suffix`.
- Data `YYYY-MM-DD` (u některých polí `YYYY-MM-DD HH:ii:ss`).
- Vynulování hodnoty v update metodách: prázdný parametr nebo řetězec `"NULL"`.
- Pole `software_version` u `insert`/`update` – vyplňovat (např. `JustEx x.y.z`).

## 5. Strukturovaná jména (povinné od 4.1.0)

| Typ | Povinné | Volitelné | Zakázané |
|---|---|---|---|
| `subject_type: "F"` | `first_name`, `last_name` | `title_before`, `title_after` | `company_name` |
| `subject_type: "P"` | `company_name` | – | všechna osobní pole |

- **`legal_name` se nesmí posílat** (5513). Neposílat ani objekt `structured_names`.
- `title_after` **bez úvodní čárky** („Ph.D.“) – čárku doplní server.
- Jméno VELKÝMI písmeny server převede na „Jana Nováková“; jinak ponechá.
- Typ osoby (F/P) nelze při update změnit (5515). Neplatná kombinace → 5514.
- Do jména nepatří poznámky (rozvedená, nezletilý, zemřel) – viz FAQ.
- Při čtení zatím zůstávají kompatibilní `jmeno` / `legal_name`; JustEx čte strukturovaná pole, typ osoby bere z `typ_osoby`. U starých záznamů mohou být strukturovaná pole `null`.

## 6. Adresy

Pro povinné i oprávněné platí vždy právě jedna varianta:

| Situace | Posílat |
|---|---|
| Adresa v ČR s kódem RÚIAN (i cizinec) | `address_code` (kód adresního místa) |
| Adresa v ČR bez kódu RÚIAN | `city_code` (kód obce ČÚZK) + `adresa` (text) + `address_note` (důvod) |
| Adresa v zahraničí | `adresa` (text) + `foreign_address` (ISO 3166-1 alpha-2, **ne `CZ`**) |
| Ukončil pobyt v ČR, další neznámý | `adresa` (veřejný text) + `address_note` (interní) + `foreign_address: "XX"` |

- `address_code` + `foreign_address` současně → **400015**.
- `foreigner: 1` jen vypíná validaci RČ/IČO (např. číslo pasu v `rc`), není to adresa ani státní příslušnost.
- **Při `updatesubject`/`updateeligible` zaslaná adresa nahrazuje celou adresu**; chybějící `foreign_address` uložený kód země smaže → posílat adresu vždy kompletně.

## 7. Metody API v4.1.0

Všechny `…/api/v4/<metoda>?token=…`.

### 7.1 Účet a autentizace

| Metoda | Účel |
|---|---|
| GET `auth` | token (kap. 2.2) |
| GET `validatetoken` | platnost tokenu (`valid_for` = zbývající sekundy) |
| GET `token-info` | verze, typ účtu, kancelář, rate limit (kap. 2.3) |
| GET `credit` | kredit; u exekutorů `current_free`, `default_free` (roční FREE dotazy) |
| GET `me` | info o účtu, ceny `price_for_search` / `price_for_detail` |
| GET `mine` | **všechny kauzy úřadu** `{cause_id: "999EX123/20"}`, stránkování `page` (po 1000) |
| GET `myoffice` | kauzy kanceláře (zmíněno v changelogu/přehledu, v referenci 4.1.0 není popsána) |
| GET `colleagues` | uživatelé kanceláře |

### 7.2 Zápis kauzy – POST `insert`

Celá kauza najednou. Hlavní pole:

- `ex_cislo_preffix`, `ex_cislo_number`, `ex_cislo_suffix` – povinné.
- Peněžitá povinnost: alespoň jedno z `one_time_price`, `regular_price`, `monetary_description`; dále `nonmonetary_description`, `current_price_value` (int), `current_price_date`.
- `datum_vlozeni`, `datum_zapisu`, `merged_cause_code`, `merged_date`, `software_version`.
- `subject[]` – povinní: `subject_type`, jméno (kap. 5), `birthdate` (F), `rc` (bez lomítka / ID cizince), `ico` (P), adresa (kap. 6), `gender` (F/M, jinak z RČ), `foreigner`, `execution_order` (soupis movitých věcí 1/0).
- `documents[]` – `id_soudu` (číselník `courtlist`), `spisova_znacka_soudu`, `type` (číselník, kap. 8), `document_vydano`, `popis_dokumentu`.
- `enforcements[]` – **exekuční titul povinný** (od 1. 1. 2022): `reference_number`, `enforcement_type` (kap. 8.2), `issued_at`, `description`, `issuer`.
- `eligible[]` – **oprávněný povinný** (od 25. 10. 2021): jméno, `birthdate`/`ico`, adresa, `foreigner`, `status` (`current`/`former`/`precedent`), `hidden_identity` (1/0).

Odpověď: `cause_id`, `ex_number`, pole `subject_id[]`, `document_id[]`, `eligible_id[]`, `enforcement_id[]` (ve stejném pořadí jako vstup) → **JustEx si všechna ID uloží k záznamům**.

Pozor: existuje-li kauza se stejným EX číslem, může vrátit chybu **4000352**, nebo (dle příkladu) kauzu založit a starou **archivovat** s `data.warning`. Warning vždy logovat a zobrazit.

Chyby: 4000302 (formát EX čísla), 4000XXX (chybí povinné pole), 5513, 5514, 400015.

### 7.3 Doplnění a úpravy

| Metoda | Query | Účel |
|---|---|---|
| POST `addsubjecttocause` | `cause_id` | další povinný (+ volitelně `documents[]` s `subjects`) |
| POST `addeligibletocause` | `cause_id` | další oprávněný |
| POST `insertdocument` | `cause_id` | nový dokument; `subjects` = pole `subject_id` nebo `"all"` |
| POST `insertenforcement` | `cause_id` | nový exekuční titul |
| POST `update` | `cause_id` | kauza – jen měněná pole (whitelist: EX číslo, data, ceny, popisy, `aktivni`, `merged_*`, `software_version`) |
| POST `updatesubject` | `cause_id`, `subject_id` | povinný – jen měněná pole (adresa vždy celá!) |
| POST `updateeligible` | `cause_id`, `eligible_id` | oprávněný (+ `active`, `status`, `hidden_identity`) |
| POST `updatedocument` | `cause_id`, `document_id` | dokument |
| POST `updateenforcement` | `cause_id`, `enforcement_id` | exekuční titul |

Odpovědi update metod: `data.updated` = mapa změněných polí.

### 7.4 Ukončení

| Metoda | Tělo |
|---|---|
| POST `terminate-subject` | `subject_id`, `court_id`, `document_type_id`, `document_issued_at`, (`document_reference_number`, `document_description`) |
| POST `terminate-cause` | `cause_id`, `court_id`, `document_type_id`, `document_issued_at`, (…) |

- Vloží ukončovací dokument; odpověď vrací `auto_close_at` = datum výmazu z CEE.
- Nevyžadují platný RÚIAN.
- **`insertcompletion` je deprecated – nepoužívat.**

### 7.5 Vyhledávání

| Metoda | Poznámka |
|---|---|
| GET `search` | podle `rc` / `ico` (ostatní parametry se pak ignorují), nebo `name` + `birth` / `address`, `person` F/P, `ex_cislo`. Placené; `use_free=true` + `reason` = FREE kredit; `use_free=record` + `reason` = **evidenční dotaz na vlastní kauzu**. |
| GET `detail` | `cause_id` – celá kauza. S `use_free=record` z vlastního úřadu vrací i `eligibles`. Chybějící klíč `eligibles` = bez oprávnění. |
| GET `search-eligible` | `cause_number` – zda povinní z mé kauzy jsou oprávnění jinde. |

Pro kontrolu vlastních záznamů používat **evidenční dotaz** (`use_free=record`), ne placené vyhledávání.

### 7.6 Číselníky

- GET `courtlist` – soudy (`id`, `name`) → `id_soudu` / `court_id`.
- GET `documenttypelist` – typy dokumentů. (`completiontypelist` vrací totéž – nepoužívat.)
- GET `executorlist` – seznam exekutorů (funguje i anonymně).

JustEx: číselníky stahovat a cachovat (např. 1× denně).

### 7.7 Metody mimo referenci 4.1.0 – nepoužívat

`myoffice`, `insertcompletion` a `completiontypelist` jsou zmíněné v přehledu změn / changelogu, ale v API referenci 4.1.0 popsané nejsou. `insertcompletion` je deprecated (náhrada: `terminate-subject` / `terminate-cause`), `completiontypelist` vrací totéž co `documenttypelist`; pro výpis kauz úřadu je zdokumentovaná metoda `mine`. JustEx s nimi nepočítá.

## 8. Číselníky

### 8.1 Typy dokumentů

| ID | Dokument | Účinek |
|---|---|---|
| 1401 | Pravomocná exekuce | dohledatelné v CEE |
| 1402 | Pravomocný odklad exekuce soudem | dohledatelné |
| 1404 | Pravomocný odklad exekuce exekutorem | dohledatelné |
| 1305 | Úmrtí povinného | dohledatelné |
| 1301 | Zánik oprávnění – vyloučení exekutora | ukončí za 15 dní |
| 1302 | Pravomocné zastavení exekuce | ukončí za 15 dní |
| 1303 | Skončeno vymožením | ukončí za 15 dní |
| 1304 | Změna exekutora (§ 44b EŘ) | ukončí za 15 dní |
| 1306 | Pravomocné zastavení – milostivé léto | ukončí za 15 dní |
| 1307 | Zánik oprávnění – spojení k jinému exekutorovi | ukončí za 15 dní |
| 1403 | Pravomocné zastavení exekuce soudem | ukončí za 15 dní |
| 1405 | Pravomocné zastavení exekuce exekutorem | ukončí za 15 dní |
| 1406 | Pravomocné nařízení likvidace dědictví | ukončí za 15 dní |
| 1407 / 1408 | Zastavení soudem / exekutorem – milostivé léto | ukončí za 15 dní |
| 1409 | Spojení exekuce u stejného exekutora | ukončí za 15 dní |
| 1410 | Zastaveno podle § 55 odst. 7–13 EŘ | ukončí za 15 dní |

„Ukončí za 15 dní“ = povinný/kauza zmizí z CEE 15. den od vložení dokumentu.

### 8.2 Typy exekučních titulů (`enforcement_type`)

1201 rozhodnutí soudu · 1202 rozhodnutí soudu/OČTŘ v trestním řízení · 1203 rozhodnutí exekutora · 1204 rozhodčí nález · 1205 vykonatelný zápis · 1206 rozhodnutí ZP · 1207 rozhodnutí SSZ · 1208 rozhodnutí orgánu VS · 1209 ostatní · 1210 cizozemské – rozhodnutí OVM · 1211 cizozemské – rozhodčí nález · 1212 cizozemské – veřejná listina.

## 9. Testování

- Pouze s **testovacím klíčem** (`data_source: "test"`), nezpoplatněno.
- Základní sada: kauzy `999EX123/23`, `999EX456/23`, `999EX789/23` (Jan Novák RČ 8911110252, Maso Uzeniny Novák s.r.o. IČO 60258975 …) – jen historická jména.
- Sada se strukturovanými jmény: kauza `999EX321/26`, např. RČ `8856140007` (Kamila Dvořáková), `7902210008` (JUDr. Radek Bartoš, Ph.D.), IČO `28000005`; cizinky bez RČ (María del Carmen García López, 1983-09-30).
- Otestovat všech 5 metod zapisujících jména: `insert`, `addsubjecttocause`, `addeligibletocause`, `updatesubject`, `updateeligible`.

## 10. Doporučení pro implementaci v JustEx

1. Konfigurace per uživatel CEE (v rámci úřadu): `api_key`, `api_secret`, příznak test/prod; kontrola `token-info` při uložení klíče.
2. Token cache per (klíč, odchozí IP); obnova při 5506/5507/5508; pozor na blokaci IP (5503).
3. Jednotné vyhodnocení odpovědí podle JSON `status` (ne HTTP).
4. Mapování ID z CEE (`cause_id`, `subject_id`, …) do databáze JustEx. Při nesouladu hashů (přečíslování 2022) dohledat přes `mine` nebo evidenční `search?ex_cislo=…&use_free=record`.
5. Hlídat 3denní zákonné lhůty pro zápis a ukončení.
6. Sledovat `key_valid_till` a `rate_limit`.

## 11. Otevřené otázky

### Uzavřené (9. 10. 2026)

- ~~Je kancelář exekutora v CEE v režimu soudního exekutora?~~ → Ano: `token-info` vrací `executor_office_id: 176` (EÚ č. 184) a na webu je dostupné menu „Kauzy“.
- ~~Jaká odchozí IP bude u serveru JustEx?~~ → Nehraje roli: IP se nikde neregistruje, váže se jen k tokenu. JustEx si token vyžádá vždy sám ze svého serveru a při neplatnosti (5506/5507/5508) si vyžádá nový. Jediná podmínka: `auth` a následná volání musí jít ze stejné odchozí IP (pozor jen při více odchozích IP / load balanceru – pak 5507 → nový token).

- ~~Jeden klíč pro více uživatelů úřadu, nebo per uživatel?~~ → **Klíč se vždy váže na konkrétního uživatele** (telefonicky potvrzeno helpdeskem CEE). JustEx proto ukládá klíč + secret per uživatel CEE.

### Stále otevřené

- Hodnota a výchozí nastavení `rate_limit` pro exekutorské klíče.