# Jak zintegrować systemy kliniczne z backendem FHIR

> Samouczek: połącz system EMR kliniki z rekordami FHIR R4 pacjentów — katalog lekarzy, dopasowanie według numeru rekordu, wizyta jako jedna transakcja z lekarzem jako autorem, wyniki badań laboratoryjnych, dane od innych dostawców i webhooki.

Source: https://developers.anpheros.com/pl/guides/integrate-clinic-systems-fhir

**Ten samouczek łączy oprogramowanie kliniki (system EMR, system zarządzania praktyką lub narzędzie do rezerwacji) z rekordami HL7 FHIR R4 pacjentów w Anpheros: klinika i jej lekarze są zarejestrowani w katalogu, pacjenci są dopasowywani według numeru rekordu kliniki, wizyta jest zapisywana jako jedna transakcja z lekarzem wskazanym jako autor, a klinika dowiaduje się o danych dodawanych przez innych dostawców.** Każde zapytanie jest `curl` kierowane do darmowego środowiska sandbox, a odpowiedzi pochodzą z platformy.

Integracja działa na serwerze kliniki, z kluczem API projektu dla pacjentów, których klinika rejestruje, oraz, dla osób posiadających już rekord Anpheros, z udzielonym przez nich upoważnieniem OAuth.

## Co się do czego mapuje

| W systemie kliniki | W FHIR R4 |
|---|---|
| klinika, jej oddziały | `Organization` |
| lekarz lub pielęgniarka | `Practitioner` |
| ta osoba pracująca w tej klinice, ze specjalizacją | `PractitionerRole` |
| karta pacjenta i jej numer | `Patient` z `identifier` w systemie kliniki |
| wizyta | `Encounter` |
| parametry życiowe, wyniki zmierzone podczas wizyty | `Observation` powiązane z `Encounter` |
| diagnoza | `Condition` (ICD-10), z `verificationStatus` tymczasowa lub potwierdzona |
| recepta, bieżące leczenie | `MedicationStatement` (ATC) |
| list, karta wypisu, skan | `DocumentReference` z plikiem |
| wyniki laboratoryjne | [łącznik laboratoryjny](https://developers.anpheros.com/pl/guides/lab-connector), do `Observation` |

## Krok 1: rejestracja kliniki i jej lekarzy

Zasoby katalogowe nie zawierają pacjentów. Inne projekty w tym samym środowisku mogą je odczytywać, dzięki czemu inni świadczeniodawcy pacjenta widzą, kto co napisał, ale tylko Twój projekt może je modyfikować.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json")

curl -X POST $BASE/Organization "${H[@]}" -d '{"resourceType": "Organization", "active": true, "name": "Clinica Cardio Nord",
  "identifier": [{"system": "https://clinic.example/org", "value": "CCN"}]}'

curl -X POST $BASE/Practitioner "${H[@]}" -d '{"resourceType": "Practitioner", "active": true,
  "name": [{"family": "Popescu", "given": ["Ana"], "prefix": ["Dr."]}]}'

curl -X POST $BASE/PractitionerRole "${H[@]}" -d '{"resourceType": "PractitionerRole", "active": true,
  "practitioner": {"reference": "Practitioner/'$PRACTITIONER'"},
  "organization": {"reference": "Organization/'$ORG'"},
  "code": [{"text": "Cardiologist"}]}'
```

Zachowaj zwrócone identyfikatory obok rekordów personelu. Gdy ktoś odchodzi, ustaw jego `PractitionerRole` na `"active": false`; jego wcześniejsze wpisy zachowują jego imię, a on nie może już działać za pośrednictwem Twojego systemu.

## Krok 2: dopasowanie pacjentów

Dla pacjentów rejestrowanych przez klinikę, utwórz `Patient` z numerem rekordu kliniki jako identyfikatorem:

```bash
curl -X POST $BASE/Patient "${H[@]}" -d '{"resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-20981"}],
  "name": [{"family": "Dinu", "given": ["Andrei"]}], "gender": "male", "birthDate": "1968-11-05"}'
```

Od tego momentu wyszukuj pacjenta według tego numeru, nigdy według imienia i daty urodzenia:

```bash
curl "$BASE/Patient?identifier=https://clinic.example/mrn|MRN-20981" -H "Authorization: Bearer $KEY"
```

**Gdy osoba posiada już rekord w Anpheros**, ze swojej własnej aplikacji lub od innego dostawcy, klinika nie tworzy drugiego rekordu. Prosi osobę o dostęp za pomocą OAuth, z tabletu przy recepcji lub linku wysłanego przed wizytą, używając **poufnej** aplikacji (serwer kliniki przechowuje sekret). Osoba wybiera swój rekord i czas, przez jaki klinika może mieć do niego dostęp. Kroki opisano w [Jak zaimplementować zgodę pacjenta z SMART on FHIR](https://developers.anpheros.com/pl/guides/smart-on-fhir-backend); pole `patient` tokenu to identyfikator do przechowywania w pliku.

## Krok 3: zapis wizyty jako jedna transakcja

Wizyta generuje kilka zasobów, które do siebie należą. Wyślij je w ramach `transaction`, aby zostały zapisane od razu lub wcale, i określ, kto pracuje: `X-Anpheros-Acting-As` określa rolę lekarza. Staje się ona autorem w Provenance, jest zapisywana w logu dostępu i jest wyświetlana pacjentowi pod nazwiskiem.

```bash
curl -X POST $BASE "${H[@]}" \
  -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
  -H "X-Anpheros-Author-Type: practitioner" \
  -H "X-Anpheros-Source-System: ccn-emr" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:aa000000-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Encounter", "status": "finished",
       "class": {"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB", "display": "ambulatory"},
       "subject": {"reference": "Patient/'$PID'"},
       "serviceProvider": {"reference": "Organization/'$ORG'"},
       "participant": [{"individual": {"reference": "PractitionerRole/'$ROLE'"}}],
       "period": {"start": "2026-10-09T10:00:00Z", "end": "2026-10-09T10:30:00Z"}},
     "request": {"method": "POST", "url": "Encounter"}},
    {"resource": {"resourceType": "Observation", "status": "final",
       "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
       "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4", "display": "Heart rate"}]},
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-09T10:10:00Z",
       "valueQuantity": {"value": 92, "unit": "/min", "system": "http://unitsofmeasure.org", "code": "/min"}},
     "request": {"method": "POST", "url": "Observation"}},
    {"resource": {"resourceType": "Condition",
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
       "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "provisional"}]},
       "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I48.0", "display": "Paroxysmal atrial fibrillation"}]}},
     "request": {"method": "POST", "url": "Condition"}}
  ]}'
```

`transaction-response` zawiera `201 Created` dla Encounter, Observation i Condition. Observation i Condition wskazują teraz na rzeczywiste `Encounter/0ca25459-…`. Provenance każdego z nich określa rolę lekarza, klinikę i system źródłowy:

```json
"agent": [{"who": {"reference": "PractitionerRole/e6d8c227-…",
                   "identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "practitioner"}},
           "onBehalfOf": {"reference": "Organization/c3a56a4b-…", "display": "Clinica Cardio Nord"}}],
"entity": [{"role": "source", "what": {"identifier": {"system": "ccn-emr"}}}]
```

Diagnoza jest `provisional` do momentu jej potwierdzenia. Zaktualizuj ją do `confirmed` później, a historia zachowa obie wersje. Znaczenie każdego pola jest wyjaśnione w [Wyjaśnienie pochodzenia danych medycznych](https://developers.anpheros.com/pl/guides/medical-data-provenance).

## Krok 4: Wyniki laboratoryjne i dokumenty

Wyniki z własnego laboratorium kliniki lub przyniesione przez pacjenta raporty przechodzą przez konektor laboratorium w jednym żądaniu na raport:

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: x-application/hl7-v2+er7" -H "X-Anpheros-Source-System: ccn-lab" --data-binary @oru.hl7
```

Listy i podsumowania wypisu to dokumenty: utwórz `DocumentReference` poprzez `/v1/patients/{id}/documents` i prześlij plik PDF. Oryginalny plik nigdy nie jest modyfikowany, a wyodrębnione z niego wartości wskazują na niego. Zobacz [Jak zaimportować wyniki laboratoryjne do rekordu FHIR](https://developers.anpheros.com/pl/guides/import-lab-results-fhir) i [API danych medycznych](https://developers.anpheros.com/pl/guides/medical-data-api).

## Krok 5: odczytaj, co napisali inni dostawcy, i trzymaj się swojej roli

Za zgodą pacjenta klinika odczytuje cały rekord w ramach swoich zakresów, w tym to, co dodały inne kliniki, laboratoria i sam pacjent. Może zmieniać tylko to, co sama napisała. Aktualizacja lub usunięcie zasobu innej organizacji skutkuje odpowiedzią `403`, a oryginał pozostaje niezmieniony. Aby poprawić coś, co napisał inny dostawca, napisz własny zasób (na przykład nowy `Condition` ze swoją oceną) i pozwól, aby rekord zawierał oba, każdy ze swoim autorem.

Przed wizytą `GET $BASE/Patient/$PID/$summary` udostępnia Międzynarodowe Podsumowanie Pacjenta (International Patient Summary) dotyczące problemów, leków, alergii i ostatnich parametrów życiowych, pochodzących ze wszystkich źródeł.

## Krok 6: Informacje o nowych danych

Zarejestruj webhook raz dla projektu kliniki:

```bash
curl -X POST https://platform.anpheros.com/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://ccn.example/anpheros/hook", "events": ["resource.created", "resource.updated", "consent.revoked"]}'
```

Gdy inny projekt zapisze dane do rekordu, do którego Twoja klinika ma dostęp, zdarzenie poinformuje o tym za pomocą `data.external: true` oraz źródła, dzięki czemu Twoje EMR może wyświetlić komunikat "nowe wyniki z innego laboratorium" bez konieczności ciągłego odpytywania. Zdarzenie `consent.revoked` oznacza, że osoba wycofała dostęp kliniki: przestań synchronizować ten rekord. Podpisy, ponawianie prób i ładunki (payloads) są omówione w sekcji [Webhooks](https://developers.anpheros.com/pl/guides/webhooks).

## Co widzi pacjent

Pacjent widzi wizytę, tętno i wstępną diagnozę w swojej karcie, każdą oznaczoną jako dodaną przez Dr. Ana Popescu z Clinica Cardio Nord. W swoich połączeniach aplikacja kliniki wymienia każdy dostęp, podając nazwisko, gdy działał lekarz. Ta przejrzystość sprawia, że pacjenci chętnie udzielają dostępu kolejnej klinice.

## Lista kontrolna przed uruchomieniem

- [ ] Zarejestrowano organizacje, praktyków i role praktyków; osoby odchodzące ustawione jako nieaktywne
- [ ] Pacjenci dopasowywani za pomocą identyfikatora kliniki, nigdy po nazwisku
- [ ] Istniejące rekordy dostępne poprzez zgodę OAuth, bez duplikowania
- [ ] Każde żądanie od personelu klinicznego zawiera `X-Anpheros-Acting-As`
- [ ] Wizyty zapisywane jako transakcje; diagnozy z odpowiednim statusem weryfikacji
- [ ] System źródłowy ustawiony przy każdym zapisie; raporty laboratoryjne przez konektor
- [ ] Punkt końcowy webhook weryfikujący podpisy; obsługa `consent.revoked`
- [ ] Projekt produkcyjny z podpisaną umową DPA (klucze `sk_live_…`); zobacz [Cennik](https://developers.anpheros.com/pl/guides/pricing)

## Najczęściej zadawane pytania

### Czy Anpheros posiada gotowy konektor do mojego systemu EMR?
Nie. Nie ma gotowych konektorów do konkretnych systemów EMR ani laboratoryjnych; integracja jest budowana w oparciu o FHIR R4 i API REST, zazwyczaj jako mała usługa obok systemu EMR. Wiadomości laboratoryjne HL7 v2 są akceptowane w obecnej formie.

### Czy lekarz może pracować dla dwóch przychodni?
Tak. Jeden `Practitioner` może mieć `PractitionerRole` w każdej organizacji. Rola określona w `X-Anpheros-Acting-As` decyduje, dla której przychodni jest rejestrowany każdy wpis.

### Co się dzieje, gdy pacjent odwoła dostęp przychodni?
Wywołania przychodni dla tego rekordu zwracają `401`, a wysyłany jest webhook `consent.revoked`. To, co przychodnia zapisała, pozostaje w rekordzie pacjenta wraz z jego pochodzeniem; przychodnia po prostu nie może już go odczytać ani zmienić.

## Powiązane

- [Integracje w opiece zdrowotnej](https://developers.anpheros.com/pl/guides/healthcare-integrations): wszystkie wzorce integracji w skrócie
- [Wyjaśnienie pochodzenia danych medycznych](https://developers.anpheros.com/pl/guides/medical-data-provenance)
- [Jak zaimplementować zgodę pacjenta za pomocą SMART on FHIR](https://developers.anpheros.com/pl/guides/smart-on-fhir-backend)
- [Jak zaimportować wyniki laboratoryjne do rekordu FHIR](https://developers.anpheros.com/pl/guides/import-lab-results-fhir)
- [Interoperacyjność danych w opiece zdrowotnej](https://developers.anpheros.com/pl/guides/interoperability)