# NacistLekovyZaznam — Funkční SOAP klient pro IS eRecept SÚKL

## Status
**OVĚŘENO FUNKČNÍ** — 5. dubna 2026
Odpověď serveru: `HTTP 200`, velikost: ~227 KB reálných dat
Schéma ověřeno proti: `Cuer2Schema.xsd` verze `202501A` (dokumentace SÚKL 2025-04-24)

---

## Co tato operace dělá

`NacistLekovyZaznam` je SOAP operace IS eRecept (SÚKL), která vrátí kompletní **lékový záznam pacienta** — tedy seznam všech předpisů a výdejů léků napříč všemi lékaři a lékárnami v ČR za zadané období.

Typické použití: lékař si před konzultací zobrazí, co pacient aktuálně bere, co mu bylo předepsáno a vydáno v lékárně.

---

## Klíčové informace (těžce dohledané)

### Endpoint (produkce)
```
https://lekar-soap.erecept.sukl.cz/cuer/Lekar2
```
> **Pozor:** Endpoint má na konci číslici `2` — tj. `/cuer/Lekar2`, nikoli `/cuer/Lekar`.
> Tato operace **není** dostupná na starším endpointu `/cuer/Lekar`.
> Poprvé zdokumentováno v: `eRecept_lekovy_zaznam_1v3.docx` (dokumentace SÚKL ze dne 2024-01-18).

### Endpoint (testovací prostředí)
```
https://lekar-soap.test-erecept.sukl.cz/cuer/Lekar2
```

### SOAPAction
```
"NacistLekovyZaznam"
```

### XML namespace
```
http://www.sukl.cz/erp/201912
```
> Namespace pochází z prosince 2019 a **nemění se** ani v novějších verzích rozhraní.
> Verze rozhraní se předává v elementu `<Verze>` uvnitř zprávy, ne změnou namespace.
> SÚKL zachovává zpětnou kompatibilitu — namespace zůstává `201912` i pro verze `202401A`, `202501A` atd.

---

## Další operace dostupné na stejném endpointu `/cuer/Lekar2`

Dle `CUERLekarService.wsdl` (2025-04-24) jsou na tomto endpointu celkem **4 operace**:

| Operace | SOAPAction | Popis |
|---|---|---|
| `NacistLekovyZaznam` | `NacistLekovyZaznam` | ✅ lékový záznam pacienta |
| `OverDuplicity` | `OverDuplicity` | kontrola duplicitních předpisů |
| `ZjistitPoznamkyHvlp` | `ZjistitPoznamkyHvlp` | poznámky k HVLP přípravkům |
| `GetAppInfo` | `GetAppInfo` | info o verzi API |
| `AppPing` | `AppPing` | test spojení |

---

## Autentizace (dvojitá)

IS eRecept vyžaduje **dvě vrstvy** autentizace současně:

### 1. Klientský certifikát (TLS mutual auth)
- Soubor: `AMBSUKL214235369G_31DEC2024.pfx` (certifikát lékaře vydaný SÚKL)
- Formát: PKCS#12 (`.pfx`)
- Knihovna: `requests-pkcs12` → `Pkcs12Adapter`
- Platnost certifikátu: do 31. 12. 2024 (při expiraci je nutné zažádat SÚKL o nový)

### 2. HTTP Basic Auth
- Uživatel: UUID lékaře (přiděluje SÚKL, jednoznačný v celé ČR)
- Heslo: osobní heslo lékaře do portálu eRecept

---

## Struktura SOAP dotazu

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <NacistLekovyZaznamLekarDotaz xmlns="http://www.sukl.cz/erp/201912">

      <Doklad>
        <Pristupujici>
          <Uzivatel>E08C89C6-2B1A-4EBA-8ED9-4E3E63618379</Uzivatel>  <!-- UUID lékaře, povinný -->
          <Pracoviste>00214235367</Pracoviste>                         <!-- IČP pracoviště, povinný -->
        </Pristupujici>
        <PocetZnakuATC>7</PocetZnakuATC>    <!-- POUZE hodnoty 5 nebo 7 (enum!), povinný -->
        <PocetMesicu>60</PocetMesicu>        <!-- max 99, VOLITELNÝ -->
        <Pacient>
          <Totoznost>
            <Jmeno>
              <Prijmeni>Buzalka</Prijmeni>
              <Jmena>Vladimír</Jmena>
            </Jmeno>
            <DatumNarozeni>1973-09-20</DatumNarozeni>
          </Totoznost>
        </Pacient>
        <!-- Zastupce — volitelný, pouze pokud dotazuje zastupující lékař -->
        <!-- <Zastupce>
          <DruhDokladu>OP</DruhDokladu>     1–2 znaky, volitelný -->
        <!--   <CisloDokladu>123456789</CisloDokladu>  1–9 znaků, volitelný -->
        <!-- </Zastupce> -->
      </Doklad>

      <Zprava>
        <ID_Zpravy>dabda2ad-df61-41db-bd46-a969eced026b</ID_Zpravy>  <!-- UUID, generovat pro každý dotaz -->
        <Verze>202501A</Verze>                                         <!-- aktuální verze protokolu -->
        <Odeslano>2026-04-05T10:00:00+00:00</Odeslano>                <!-- UTC timestamp -->
        <SW_Klienta>MEDICUS_____</SW_Klienta>                         <!-- identifikátor SW, přesně 12 znaků -->
      </Zprava>

    </NacistLekovyZaznamLekarDotaz>
  </soapenv:Body>
</soapenv:Envelope>
```

### Parametry dotazu (ověřeno proti Cuer2Schema.xsd verze 202501A)

| Element | Povinný | Omezení | Poznámka |
|---|---|---|---|
| `Uzivatel` | ✅ ano | UUID formát | UUID lékaře přidělené SÚKL |
| `Pracoviste` | ✅ ano | — | IČP pracoviště lékaře |
| `PocetZnakuATC` | ✅ ano | **pouze 5 nebo 7** | enum — jiné hodnoty server odmítne |
| `PocetMesicu` | ❌ volitelný | max 99 | počet měsíců do minulosti |
| `Prijmeni` | ✅ ano | — | příjmení pacienta |
| `Jmena` | ✅ ano | — | jméno/jména pacienta |
| `DatumNarozeni` | ✅ ano | `YYYY-MM-DD` | datum narození pacienta |
| `Zastupce` | ❌ volitelný | — | pouze pro zastupujícího lékaře |
| `ID_Zpravy` | ✅ ano | UUID formát | nové UUID pro každý dotaz |
| `Verze` | ✅ ano | — | aktuálně `202501A` |
| `Odeslano` | ✅ ano | ISO 8601 | čas odeslání s časovou zónou |
| `SW_Klienta` | ✅ ano | přesně 12 znaků | doplnit mezerami zleva nebo zprava |

---

## Struktura odpovědi (ověřeno proti Cuer2Schema.xsd verze 202501A)

```
NacistLekovyZaznamOdpoved
├── Doklad
│   ├── Pacient                       potvrzení identity pacienta
│   │   ├── Jmeno (Prijmeni, Jmena)   volitelný
│   │   └── DatumNarozeni             volitelný
│   │
│   ├── PredepisujiciSeznam           volitelný — lékaři kteří předepisovali
│   │   └── Predepisujici[]
│   │       ├── Lekar                 Kod (UUID) + Jmeno — volitelný
│   │       ├── ICZ                   8 číslic — volitelný
│   │       ├── ICP                   8 číslic — povinný
│   │       ├── PZS                   volitelný
│   │       │   ├── Nazev             max 200 znaků
│   │       │   ├── Telefon           max 20 znaků — volitelný
│   │       │   └── Adresa
│   │       └── Telefon               max 20 znaků — volitelný
│   │
│   ├── VydavajiciSeznam              volitelný — lékárníci kteří vydávali
│   │   └── Vydavajici[]
│   │       ├── Lekarnik              Kod (UUID) + Jmeno
│   │       └── PZS                   Nazev + Adresa
│   │
│   ├── PredpisSeznam                 volitelný — všechny předpisy
│   │   └── Predpis[]
│   │       ├── ID_LP_Predpis         UUID předpisu — povinný
│   │       ├── KodPredepisujiciho    odkaz do PredepisujiciSeznam — povinný
│   │       ├── DatumVystaveni        datum vystavení
│   │       ├── Mnozstvi              int, 1–9999
│   │       ├── Navod                 max 80 znaků (dávkování)
│   │       ├── Opakovani             int — volitelný
│   │       ├── HVLPReg               volitelný (registrovaný HVLP)
│   │       ├── HVLPNereg             volitelný (neregistrovaný HVLP)
│   │       ├── IPLP                  volitelný (individuálně připravovaný LP)
│   │       ├── INN                   volitelný (generický název)
│   │       └── ModryPruh             boolean — volitelný
│   │
│   ├── VydejSeznam                   volitelný — výdeje z lékáren
│   │   └── Vydej[]
│   │       ├── ID_LP_Vydej           UUID výdeje
│   │       ├── ID_LP_Predpis         UUID předpisu — volitelný (odkaz na předpis)
│   │       ├── KodVydavajiciho       odkaz do VydavajiciSeznam — povinný
│   │       ├── DatumVydeje           datum výdeje
│   │       ├── Mnozstvi              decimal, 0.01–9999.99
│   │       ├── Navod                 max 80 znaků
│   │       ├── Exspirace             datum — volitelný
│   │       ├── Sarze                 max 50 znaků
│   │       ├── SerioveCislo          max 20 znaků — volitelný
│   │       ├── Pozn                  max 1000 znaků — volitelný
│   │       ├── HVLPReg               volitelný
│   │       ├── HVLPNereg             volitelný
│   │       └── IPLP                  volitelný
│   │
│   └── DuplicitaSeznam               volitelný — detekované duplicity výdejů
│       └── Duplicita[]
│           └── ID_LP[]
│               ├── ID_LP_Vydej       UUID — volitelný
│               └── ID_LP_Predpis     UUID — volitelný
│
└── Zprava
    ├── ID_Zpravy                     echo zpět
    ├── Verze
    ├── Odeslano
    └── ...
```

> **Poznámka k odkazům:** `KodPredepisujiciho` v předpisu odpovídá `Lekar.Kod` v `PredepisujiciSeznam`.
> Stejně tak `KodVydavajiciho` odpovídá `Lekarnik.Kod` v `VydavajiciSeznam`.
> Struktura je záměrně normalizovaná — lékaři a lékárny jsou uloženi jednou, předpisy a výdeje se na ně odkazují.

Reálná velikost odpovědi: **~227 KB** (pacient s 60měsíční historií).

---

## HTTP hlavičky

```python
headers = {
    "Content-Type": 'text/xml; charset="UTF-8"',
    "SOAPAction": '"NacistLekovyZaznam"',   # uvozovky jsou součástí hodnoty!
    "User-Agent": "Medicus"
}
```

---

## Závislosti (Python)

```
requests
requests-pkcs12
```

Instalace:
```bash
pip install requests requests-pkcs12
```

---

## Jak dohledat správný endpoint (postup pro budoucí operace)

Endpoint `/cuer/Lekar2` byl dohledán tímto postupem:

1. Prohledání veškeré dokumentace SÚKL (2017–2025) fulltext hledáním výrazu `soap:address`
2. Klíčový dokument: `eRecept_lekovy_zaznam_1v3.docx` (2024-01-18):
   > *"Pro webové služby, které používá lékař a klinický farmaceut je nová verze rozhraní 202401A (původní 201912A): `https://lekar-soap.erecept.sukl.cz/cuer/Lekar2`"*
3. Ověřeno živým voláním — HTTP 200, reálná data

### Mapa endpointů IS eRecept (produkce)

| Endpoint | Určen pro | Operace |
|---|---|---|
| `https://lekar-soap.erecept.sukl.cz/cuer/Lekar` | lékař | CUER operace (předpis, zrušení…) |
| `https://lekar-soap.erecept.sukl.cz/cuer/Lekar2` | lékař | **NacistLekovyZaznam**, OverDuplicity, ZjistitPoznamkyHvlp |
| `https://lekar-soap.erecept.sukl.cz/rlpo/Lekar` | lékař | RLPO operace |
| `https://lekarnik-soap.erecept.sukl.cz/cuer/Lekarnik` | lékárník | CUER operace (výdej…) |
| `https://lekarnik-soap.erecept.sukl.cz/cuer/Lekarnik2` | lékárník | nové CUER operace lékárníka |
| `https://cuer-soap.erecept.sukl.cz/` | lékárna, ZP | doplatky, limity pojištěnce |

---

## Ztotožnění pacienta a chybové kódy

Zdroj: živé volání `NacistCiselnikChyb` na `https://lekar-soap.erecept.sukl.cz/cuer/Lekar` — ověřeno 5. 4. 2026.

### Jak funguje ztotožnění pacienta (Registr obyvatel)

Server každý dotaz porovná s **Registrem obyvatel (ROB)**. Lze použít dvě sady údajů:

| Sada | Prvky | Poznámka |
|---|---|---|
| **A — jméno** | Prijmeni + Jmena + DatumNarozeni | základní, stačí pokud je pacient jednoznačný |
| **B — doklad** | DruhDokladu + CisloDokladu | jednoznačné vždy, řeší jmenovce |

Obě sady lze kombinovat. Pokud jsou uvedeny obě, musí být konzistentní (jinak C017).

### Hodnoty DruhDokladu

| Hodnota | Doklad |
|---|---|
| `ID` | občanský průkaz |
| `P` | cestovní pas |

`CisloDokladu` — pouze číslice, max 9 znaků.

### Chybové kódy — ztotožnění pacienta (skupina C)

| Kód | Popis | Co udělat |
|---|---|---|
| **C010** | Jméno + příjmení + datum narození nenalezeno v ROB | Zkontrolovat překlep, záměnu jména a příjmení |
| **C011** | Druh a číslo dokladu nenalezeno v ROB | Zkontrolovat číslo a platnost dokladu |
| **C012** | Adresa neodpovídá — více jmenovců se stejným jménem a datem | Doplnit `DruhDokladu` + `CisloDokladu` |
| **C014** | Není uvedeno ani jméno/datum, ani číslo dokladu | Doplnit alespoň jednu sadu |
| **C015** | Více jmenovců v ROB, nelze dohledat adresu | Doplnit adresu **nebo** číslo dokladu |
| **C016** | Pacient mladší 33 dní | Předpis uložen, ale nebude v lékovém záznamu |
| **C017** | Jméno/datum neodpovídá osobě nalezené dle čísla dokladu | Opravit jméno nebo ho neuvádět |
| **C018** | Nelze dohledat, chybí adresa | Doplnit adresu nebo číslo dokladu |
| **C019** | Datum narození v budoucnosti | Opravit datum |
| **C020** | Chybí jméno, příjmení nebo datum narození | Doplnit kompletní sadu A |
| **C022** | Pacient dle ROB již zemřel | — |

### Chybové kódy — upozornění (uloženo, ale bez záznamu)

| Kód | Popis |
|---|---|
| **C023** | Předpis uložen, ale kvůli chybě ztotožnění nebude v lékovém záznamu |
| **C024** | Registr LP prohledán, pacient nenalezen v ROB (možný cizinec) |
| **C025** | Výdej uložen, ale kvůli chybě ztotožnění nebude v lékovém záznamu |

### Chybové kódy — doklad totožnosti

| Kód | Popis |
|---|---|
| **L076** | Neznámý druh dokladu — povoleno pouze `ID` (občanský průkaz) nebo `P` (cestovní pas) |

### Chybové kódy — systémové

| Kód | Popis |
|---|---|
| **I005** | Registr obyvatel nedostupný (mimo kontrolu SÚKL) — zkusit znovu |
| **I007** | Chyba dotazu na ROB — vstupní data nemají správný formát |

### Proč Medicus žádá o občanský průkaz

Typický scénář: lékař pošle dotaz pouze se jménem + datem narození. Pokud existuje více jmenovců v ROB, server vrátí **C015**. Medicus tento kód rozpozná a zobrazí dialog *"zadejte číslo občanského průkazu"*. Lékař zadá číslo, Medicus pošle dotaz znovu s `DruhDokladu=ID` + `CisloDokladu=...` → server vrátí jednoznačný výsledek.

### Skript s občankou

`NacistLekovyZaznam_FUNKCNI_OBCANKA.py` — varianta s `DruhDokladu` + `CisloDokladu` v dotazu.

---

## Soubory skriptů

| Skript | Popis |
|---|---|
| `NacistLekovyZaznam_FUNKCNI.py` | základní dotaz — jméno + datum narození |
| `NacistLekovyZaznam_FUNKCNI_OBCANKA.py` | dotaz s číslem občanského průkazu |
| `NacistCiselnikChyb.py` | stáhne kompletní číselník chybových kódů ze serveru |

---

## Zdroje dokumentace SÚKL

| Soubor | Datum | Obsah |
|---|---|---|
| `eRecept_lekovy_zaznam_1v1.docx` | 2020-05-28 | původní popis lékového záznamu |
| `eRecept_lekovy_zaznam_1v3.docx` | 2024-01-18 | endpointy Lekar2/Lekarnik2, verze 202401A |
| `CUERLekarService.wsdl` | 2025-04-24 | nejnovější definice rozhraní, seznam operací |
| `Cuer2Schema.xsd` | 2025-04-24 | kompletní XSD schéma dotazu i odpovědi, verze 202501A |
| `CuerSchema.xsd` | 2025-04-24 | sdílené typy (Zprava, Pristupujici, adresy…) |