# Zdravotnícke API: čo to je a ako to funguje

> Čo je zdravotnícke API, ako funguje jeden hovor, na čo sa zamerať a bezplatné zdravotnícke API FHIR R4 s pacientovým súhlasom, pôvodom a hostingom v EÚ — s príkladmi a často kladenými otázkami.

Source: https://developers.anpheros.com/sk/guides/healthcare-api

**Zdravotnícke API je programové rozhranie, prostredníctvom ktorého softvér číta a zapisuje zdravotné údaje — záznamy pacienta, pozorovania, diagnózy, lieky, dokumenty — a prostredníctvom ktorého je autorizovaný prístup k týmto údajom.** Anpheros Platform API je zdravotnícke API nad záznamom HL7 FHIR R4 ovládaným pacientom: aplikácie ho používajú na ukladanie a načítavanie lekárskych údajov, na získanie súhlasu pacienta a na upozornenie na zmeny.

<!-- visual: hapi-hero -->

## Ako funguje volanie zdravotníckeho API

Bez ohľadu na dodávateľa, volanie zdravotníckeho API prechádza rovnakými kontrolnými bodmi: kto volá, ktorého pacienta a akých dát sa môže dotknúť, kde sú dáta uložené, kto ich napísal a kto potrebuje vedieť o ich zmene.

<!-- visual: hapi-request -->

## Druhy zdravotníckych API

| Druh | Čo vymieňa | Typické použitie |
|---|---|---|
| FHIR REST API | FHIR zdroje cez HTTP (`GET /Observation?patient=…`) | moderný štandard pre výmenu klinických údajov |
| SMART on FHIR / OAuth | autorizácia pre FHIR API | umožnenie prístupu aplikáciám tretích strán k záznamom s povolením používateľa |
| HL7 v2 messaging | správy oddelené znakom pipe (`ORU^R01` pre výsledky, `ADT` pre prijatia) | laboratórne a nemocničné systémy, často cez rozhrania namiesto HTTP |
| Výmena dokumentov | klinické dokumenty (PDF, CDA, FHIR dokumentové balíky) | súhrny, prepúšťacie správy, odporúčania |
| Vlastné REST API | JSON špecifický pre dodávateľa | vlastná mobilná aplikácia alebo integrácie jedného produktu |

Anpheros kombinuje prvé dva ako svoje jadro, prijíma laboratórne výsledky HL7 v2 ako vstup, ukladá dokumenty s ich originálmi a produkuje FHIR dokumentové balíky (International Patient Summary). Ponúka tiež jednoduchšie REST API nad rovnakými údajmi pre vývojárov, ktorí nechcú pracovať priamo s FHIR.

## Čo hľadať v zdravotníckom API

<!-- visual: hapi-checklist:replace -->

- **Štandardný dátový model**, aby sa dáta mohli presúvať medzi systémami bez vlastného mapovania.
- **Autorizácia, ktorú ovláda pacient**, nielen prihlasovacie údaje, ktoré ovláda aplikácia.
- **Pôvod**: kto zapísal každú hodnotu, v mene koho, z akého systému.
- **História**: verzie namiesto tichého prepísania.
- **Auditovateľnosť** čítaní, nielen zápisov.
- **Bezpečné opätovné pokusy** (idempotencia) a **predvídateľné chyby**, pretože zdravotné údaje sa nesmú duplikovať ani stratiť.
- **Izolácia** medzi aplikáciami, ktoré zdieľajú rovnakú infraštruktúru.
- **Dátová rezidencia** zodpovedajúca miestu, kde sa pacienti nachádzajú.

Zvyšok tejto stránky ukazuje, ako sa každý z týchto bodov prejavuje v Anpheros API.

## Anpheros API v skratke

| Povrch | Základná cesta | Účel |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 typov zdrojov; čítanie, vyhľadávanie, vytváranie, aktualizácia, mazanie, história, transakcie, `$everything`, `$summary`, `$validate` |
| REST v1 | `/v1` | pacienti, pozorovania, stavy, lieky, dokumenty, časová os, pôvod, kontext AI, import laboratórnych výsledkov, terminológia, webhooks |
| OAuth 2.1 | `/oauth` | stránka súhlasu, tokeny (PKCE), zrušenie, OpenID Connect kľúče |
| Stránka pacienta | `/me` | vlastné záznamy osoby, kto má prístup, denník prístupu, zrušiť |
| Objavovanie | `/fhir/R4/metadata`, `/fhir/R4/.well-known/smart-configuration`, `/openapi.json` | strojom čitateľné popisy API |

Základná URL: `https://platform.anpheros.com`. Sandbox a produkcia ju zdieľajú; kľúč rozhoduje o dátovej rovine.

### Autentifikácia

- **API kľúče** (`sk_test_…`, `sk_live_…`) pre vaše servery; vidia pacientov, ktorých váš projekt vytvoril.
- **OAuth prístupové tokeny** (`at_…`) pre aplikáciu konajúcu v mene jedného pacienta na základe súhlasu.

```bash
curl https://platform.anpheros.com/v1/patients -H "Authorization: Bearer $KEY"
```

### Bezpečné písanie

Požiadavky `POST` akceptujú `Idempotency-Key`: opakovaná požiadavka s rovnakým kľúčom vráti pôvodnú odpoveď a nič nevytvorí. Každé písanie dostane `Provenance`; typ autora sa posiela v tele (`author_type`) alebo v hlavičkách ako `X-Anpheros-Author-Type`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id` a `X-Anpheros-On-Behalf-Of`.

```bash
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" \
     -d '{"code": "29463-7", "display": "Body weight", "category": "vital-signs",
          "value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
```

### Chyby a limity

FHIR koncové body odpovedajú s `OperationOutcome`; ostatné s `{"error": {"type", "message", "field"}}`. Každá odpoveď obsahuje `Anpheros-Request-Id`. Predvolený limit je 600 požiadaviek za minútu na kľúč a na IP. [Chyby](https://developers.anpheros.com/sk/guides/errors) · [Limity](https://developers.anpheros.com/sk/guides/limits)

### Udalosti

Podpísané webhooks pre `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` a `ping`. [Webhooks](https://developers.anpheros.com/sk/guides/webhooks)

## Výber medzi FHIR a REST v1

Použite **FHIR**, ak už pracujete s FHIR, potrebujete typy zdrojov, ktoré `/v1` nepokrýva (napríklad `Immunization`, `Procedure` alebo `CarePlan`), alebo si vymieňate dáta s inými FHIR systémami. Použite **REST v1** pre aplikačný kód, ktorý chce ploché JSON pre bežné prípady. Obe čítajú a zapisujú rovnaké zdroje s rovnakými ID, takže projekt ich môže kombinovať. [Medical data API](https://developers.anpheros.com/sk/guides/medical-data-api) podrobne opisuje dátové operácie.

## Často kladené otázky

### Čo je zdravotnícke API?
Programové rozhranie, prostredníctvom ktorého softvér číta a zapisuje zdravotné údaje – záznamy pacientov, pozorovania, diagnózy, lieky a dokumenty – a prostredníctvom ktorého je autorizovaný prístup k týmto údajom. Moderné zdravotnícke API používajú HL7 FHIR R4 pre údaje a OAuth 2.0 alebo 2.1 so SMART on FHIR pre autorizáciu.

### Aký je rozdiel medzi zdravotníckym API a FHIR API?
FHIR je jeden štandard, ktorý môže zdravotnícke API dodržiavať. FHIR API si vymieňa FHIR zdroje cez REST; zdravotnícke API môže tiež prijímať správy HL7 v2, dokumenty alebo proprietárne JSON. Anpheros ponúka FHIR R4 API a jednoduchšie REST API nad rovnakými údajmi.

### Existuje bezplatné zdravotnícke API pre vývojárov?
Áno. Sandbox Anpheros je bezplatný a samoobslužný: prihláste sa pomocou Google, získajte API kľúč a pracujte s 30 syntetickými pacientmi cez FHIR R4 alebo REST. Produkcia začína od 99 € mesačne, pričom prvý mesiac je bezplatný.

### Ako pacienti udeľujú súhlas zdravotníckemu API?
Prostredníctvom OAuth 2.1 s PKCE: aplikácia presmeruje osobu na stránku súhlasu so scopes SMART on FHIR; osoba si vyberie, čo zdieľať a na ako dlho, môže vidieť denník prístupu a môže kedykoľvek odvolať prístup.

### Kde sú uložené údaje?
V Európskej únii: služba a jej databázy bežia v Google Cloud `europe-west4` (Holandsko).

### Ktoré zdravotnícke API by som si mal vybrať?
Porovnajte štandard údajov, kto autorizuje prístup, pôvod a audit, lokalitu údajov, ako sa správajú opätovné pokusy a chyby, a či môžete bezplatne testovať s realistickými údajmi. [Platforma zdravotníckeho API: čo obsahuje a ako si vybrať](https://developers.anpheros.com/sk/guides/healthcare-api-platform) premieňa tieto otázky na otázky, ktoré môžete položiť akémukoľvek predajcovi.

<!-- visual:cta-hapi -->

## Súvisiace

- [EHR API a API pre zdravotné záznamy](https://developers.anpheros.com/sk/guides/ehr-api)
- [Platforma API pre zdravotníctvo: čo obsahuje a ako si vybrať](https://developers.anpheros.com/sk/guides/healthcare-api-platform)
- [Ako vytvoriť API pre zdravotníctvo pomocou TypeScript](https://developers.anpheros.com/sk/guides/healthcare-api-typescript): podrobný návod s Express
- [Ako ukladať zdravotné záznamy pomocou FHIR R4](https://developers.anpheros.com/sk/guides/store-medical-records-fhir): podrobný návod s curl
- [API pre zdravotníctvo s povolením pacienta](https://developers.anpheros.com/sk/guides/healthcare-api-patient-consent)
- [Backend SMART on FHIR](https://developers.anpheros.com/sk/guides/smart-on-fhir-backend)
- [API pre medicínske dáta](https://developers.anpheros.com/sk/guides/medical-data-api)
- [Platforma FHIR](https://developers.anpheros.com/sk/guides/fhir)
- [Interoperabilita zdravotníckych dát](https://developers.anpheros.com/sk/guides/interoperability)
- [Integrácie v zdravotníctve](https://developers.anpheros.com/sk/guides/healthcare-integrations)
- [Referenčná príručka API (OpenAPI)](https://developers.anpheros.com/docs) · [Autentifikácia a OAuth](https://developers.anpheros.com/sk/guides/authentication)