# Healthcare API: czym jest i jak działa

> Czym jest API opieki zdrowotnej, jak działa pojedyncze wywołanie, na co zwrócić uwagę, a także bezpłatne API FHIR R4 dla opieki zdrowotnej z zgodą pacjenta, pochodzeniem danych i hostingiem w UE — wraz z przykładami i FAQ.

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

**API opieki zdrowotnej to programistyczny interfejs, za pomocą którego oprogramowanie odczytuje i zapisuje dane dotyczące zdrowia — rekordy pacjentów, obserwacje, diagnozy, leki, dokumenty — oraz za pomocą którego autoryzowany jest dostęp do tych danych.** Anpheros Platform API to API opieki zdrowotnej działające na rekordzie HL7 FHIR R4 kontrolowanym przez pacjenta: aplikacje używają go do przechowywania i pobierania danych medycznych, uzyskiwania zgody pacjenta oraz powiadamiania o zmianach.

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

## Jak działa wywołanie API medycznego

Niezależnie od dostawcy, wywołanie API medycznego przechodzi przez te same punkty kontrolne: kto wywołuje, do którego pacjenta i jakich danych może uzyskać dostęp, gdzie dane są przechowywane, kto je zapisał i kto musi wiedzieć o ich zmianie.

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

## Rodzaje API w opiece zdrowotnej

| Rodzaj | Co wymienia | Typowe zastosowanie |
|---|---|---|
| FHIR REST APIs | Zasoby FHIR przez HTTP (`GET /Observation?patient=…`) | nowoczesny standard wymiany danych klinicznych |
| SMART on FHIR / OAuth | autoryzacja dla API FHIR | umożliwienie aplikacjom stron trzecich dostępu do rekordu za zgodą użytkownika |
| HL7 v2 messaging | wiadomości rozdzielane znakiem potoku (`ORU^R01` dla wyników, `ADT` dla przyjęć) | systemy laboratoryjne i szpitalne, często przez interfejsy zamiast HTTP |
| Wymiana dokumentów | dokumenty kliniczne (PDF, CDA, pakiety dokumentów FHIR) | podsumowania, listy wypisowe, skierowania |
| Proprietary REST APIs | specyficzny dla dostawcy JSON | własna aplikacja mobilna lub integracje pojedynczego produktu |

Anpheros łączy pierwsze dwa jako swój rdzeń, akceptuje wyniki laboratoryjne HL7 v2 jako dane wejściowe, przechowuje dokumenty wraz z oryginałami i generuje pakiety dokumentów FHIR (International Patient Summary). Oferuje również prostsze API REST na tych samych danych dla deweloperów, którzy nie chcą pracować bezpośrednio z FHIR.

## Na co zwrócić uwagę w interfejsie API dla opieki zdrowotnej

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

- **Standardowy model danych**, umożliwiający przenoszenie danych między systemami bez niestandardowego mapowania.
- **Autoryzacja kontrolowana przez pacjenta**, a nie tylko poświadczenia kontrolowane przez aplikację.
- **Pochodzenie (Provenance)**: kto zapisał każdą wartość, w czyim imieniu, z jakiego systemu.
- **Historia (History)**: wersje zamiast cichego nadpisywania.
- **Możliwość audytu (Auditability)** odczytów, nie tylko zapisów.
- **Bezpieczne ponawianie prób (idempotencja)** i **przewidywalne błędy**, ponieważ dane medyczne nie mogą być zduplikowane ani utracone.
- **Izolacja** między aplikacjami współdzielącymi tę samą infrastrukturę.
- **Lokalizacja danych (Data residency)** zgodna z lokalizacją pacjentów.

Dalsza część tej strony pokazuje, jak każdy z tych punktów jest realizowany w interfejsie API Anpheros.

## API Anpheros w skrócie

| Powierzchnia | Ścieżka bazowa | Cel |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 typów zasobów; odczyt, wyszukiwanie, tworzenie, aktualizacja, usuwanie, historia, transakcje, `$everything`, `$summary`, `$validate` |
| REST v1 | `/v1` | pacjenci, obserwacje, schorzenia, leki, dokumenty, oś czasu, proweniencja, kontekst AI, import wyników laboratoryjnych, terminologia, webhooks |
| OAuth 2.1 | `/oauth` | strona zgody, tokeny (PKCE), unieważnienie, klucze OpenID Connect |
| Strona pacjenta | `/me` | własne rekordy osoby, kto ma dostęp, dziennik dostępu, cofnięcie |
| Odkrywanie | `/fhir/R4/metadata`, `/fhir/R4/.well-known/smart-configuration`, `/openapi.json` | opisy API czytelne maszynowo |

Adres bazowy: `https://platform.anpheros.com`. Środowisko sandbox i produkcyjne dzielą ten sam adres; klucz decyduje o płaszczyźnie danych.

### Uwierzytelnianie

- **Klucze API** (`sk_test_…`, `sk_live_…`) dla Twoich serwerów; widzą pacjentów, których utworzył Twój projekt.
- **Tokeny dostępu OAuth** (`at_…`) dla aplikacji działającej w imieniu jednego pacjenta na podstawie zgody.

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

### Bezpieczne pisanie

Żądania `POST` akceptują `Idempotency-Key`: ponowione żądanie z tym samym kluczem zwraca oryginalną odpowiedź i niczego nie tworzy. Każde zapisanie otrzymuje `Provenance`; typ autora jest wysyłany w treści (`author_type`) lub w nagłówkach takich jak `X-Anpheros-Author-Type`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id` i `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"}'
```

### Błędy i limity

Endpointy FHIR odpowiadają kodem `OperationOutcome`; pozostałe kodem `{"error": {"type", "message", "field"}}`. Każda odpowiedź zawiera `Anpheros-Request-Id`. Domyślny limit wynosi 600 żądań na minutę na klucz i na adres IP. [Błędy](https://developers.anpheros.com/pl/guides/errors) · [Limity](https://developers.anpheros.com/pl/guides/limits)

### Zdarzenia

Podpisane webhooks dla `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` i `ping`. [Webhooks](https://developers.anpheros.com/pl/guides/webhooks)

## Wybór między FHIR a REST v1

Użyj **FHIR**, gdy już pracujesz z FHIR, potrzebujesz typów zasobów, których `/v1` nie obejmuje (na przykład `Immunization`, `Procedure` lub `CarePlan`), lub wymieniasz dane z innymi systemami FHIR. Użyj **REST v1** dla kodu aplikacji, który potrzebuje płaskiego JSON-a dla typowych przypadków. Oba interfejsy odczytują i zapisują te same zasoby z tymi samymi identyfikatorami, więc projekt może je mieszać. [Medical data API](https://developers.anpheros.com/pl/guides/medical-data-api) szczegółowo opisuje operacje na danych.

## Często zadawane pytania

### Czym jest interfejs API dla ochrony zdrowia?
Programistyczny interfejs, za pomocą którego oprogramowanie odczytuje i zapisuje dane dotyczące zdrowia — rekordy pacjentów, obserwacje, diagnozy, leki i dokumenty — oraz za pomocą którego autoryzowany jest dostęp do tych danych. Nowoczesne interfejsy API dla ochrony zdrowia wykorzystują HL7 FHIR R4 do danych i OAuth 2.0 lub 2.1 z SMART on FHIR do autoryzacji.

### Jaka jest różnica między interfejsem API dla ochrony zdrowia a interfejsem API FHIR?
FHIR to jeden ze standardów, który może być stosowany przez interfejs API dla ochrony zdrowia. Interfejs API FHIR wymienia zasoby FHIR za pośrednictwem REST; interfejs API dla ochrony zdrowia może również akceptować komunikaty HL7 v2, dokumenty lub własne formaty JSON. Anpheros oferuje interfejs API FHIR R4 i prostszy interfejs API REST na tych samych danych.

### Czy istnieje darmowy interfejs API dla ochrony zdrowia dla deweloperów?
Tak. Piaskownica Anpheros jest bezpłatna i samoobsługowa: zaloguj się za pomocą Google, uzyskaj klucz API i pracuj z 30 syntetycznymi pacjentami za pośrednictwem FHIR R4 lub REST. Produkcja zaczyna się od 49 EUR miesięcznie, z pierwszym miesiącem bezpłatnie.

### W jaki sposób pacjenci udzielają zgody na interfejs API dla ochrony zdrowia?
Za pomocą OAuth 2.1 z PKCE: aplikacja kieruje osobę na stronę zgody z zakresami SMART on FHIR; osoba wybiera, co udostępnia i na jak długo, może zobaczyć dziennik dostępu i może cofnąć dostęp w dowolnym momencie.

### Gdzie przechowywane są dane?
W Unii Europejskiej: usługa i jej bazy danych działają w Google Cloud `europe-west4` (Holandia).

### Który interfejs API dla ochrony zdrowia powinienem wybrać?
Porównaj standard danych, kto autoryzuje dostęp, pochodzenie i audyt, rezydencję danych, sposób obsługi ponownych prób i błędów oraz czy można bezpłatnie testować z realistycznymi danymi. [Platforma interfejsu API dla ochrony zdrowia: co zawiera i jak wybrać](https://developers.anpheros.com/pl/guides/healthcare-api-platform) przekształca te kwestie w pytania, które należy zadać każdemu dostawcy.

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

## Powiązane tematy

- [API systemu EHR i API dokumentacji medycznej](https://developers.anpheros.com/pl/guides/ehr-api)
- [Platforma API dla sektora ochrony zdrowia: co zawiera i jak wybrać](https://developers.anpheros.com/pl/guides/healthcare-api-platform)
- [Jak zbudować API dla sektora ochrony zdrowia w TypeScript](https://developers.anpheros.com/pl/guides/healthcare-api-typescript): samouczek krok po kroku z użyciem Express
- [Jak przechowywać dokumentację medyczną przy użyciu FHIR R4](https://developers.anpheros.com/pl/guides/store-medical-records-fhir): samouczek krok po kroku z użyciem curl
- [API dla sektora ochrony zdrowia z uwzględnieniem zgody pacjenta](https://developers.anpheros.com/pl/guides/healthcare-api-patient-consent)
- [Backend SMART on FHIR](https://developers.anpheros.com/pl/guides/smart-on-fhir-backend)
- [API danych medycznych](https://developers.anpheros.com/pl/guides/medical-data-api)
- [Platforma FHIR](https://developers.anpheros.com/pl/guides/fhir)
- [Interoperacyjność danych w ochronie zdrowia](https://developers.anpheros.com/pl/guides/interoperability)
- [Integracje w ochronie zdrowia](https://developers.anpheros.com/pl/guides/healthcare-integrations)
- [Dokumentacja API (OpenAPI)](https://developers.anpheros.com/docs) · [Uwierzytelnianie i OAuth](https://developers.anpheros.com/pl/guides/authentication)