Połączenie z laboratorium: jak raport laboratoryjny w formacie HL7 v2, CSV lub JSON staje się obserwacjami FHIR w jednym zapytaniu

Laboratorium ma jedno zadanie w ramach integracji: umieścić wynik badania w karcie pacjenta bez przepisywania, bez utraty zakresu referencyjnego i bez tworzenia formatu, którego nikt inny nie czyta. Łącznik laboratoryjny Anpheros pobiera wynik w formacie, w jakim laboratorium już go produkuje, czyli HL7 v2, CSV lub JSON, i zamienia każdy wynik na obserwację FHIR (Observation) z kodem LOINC, jednostką, zakresem referencyjnym, datą i nazwą laboratorium jako wykonawcy. Niniejszy przewodnik stanowi umowę.

Wersja techniczna dla programistów: Łącznik laboratoryjny · API wyników laboratoryjnych na developers.anpheros.com, z żądaniami, odpowiedziami i limitami. Ta strona to wersja w języku potocznym.

Jedno żądanie

POST /v1/patients/{patient_id}/labs/import
Authorization: Bearer <project key>
Content-Type: text/csv | x-application/hl7-v2+er7 | application/json
X-Anpheros-Source-System: labx        (opcjonalne; zapisywane w Provenance)
Idempotency-Key: <report id>          (opcjonalne; ponowienie żądania zwraca tę samą odpowiedź)

Odpowiedź informuje, co się wydarzyło:

{"created": 3, "skipped": 0, "unmapped": ["Marker bardzo rzadki"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org",
                   "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}

Formaty

HL7 v2 ORU^R01, jako tekst ER7. OBX-3 to identyfikator (code^text^LN to LOINC; lokalny kod jest zachowywany jako własny kod laboratorium), OBX-5 to wartość, OBX-6 to jednostka, OBX-7 to zakres referencyjny, OBX-8 to flaga nieprawidłowości (staje się interpretation), OBX-11 to status, OBX-14 lub OBR-7 to data. MSH-4 nazywa placówkę wysyłającą, która staje się wykonawcą; OBR-3 i MSH-10 stają się identyfikatorem raportu w Provenance. Wyniki oczekujące, usunięte lub błędne (I, X, D, W) oraz segmenty OBX bez wartości nie stają się Obserwacjami i są wymienione w warnings.

CSV z wierszem nagłówka; separatory , ; lub tabulator, akceptowana przecinek dziesiętny, daty w formacie ISO, DD.MM.RRRR lub DD/MM/RRRR. Rozpoznawane kolumny w języku rumuńskim lub angielskim: marker, wartość, jednostka, zakres referencyjny (70-100, <5, >3.5) lub ref_low/ref_high, data, opcjonalny kod LOINC, uwaga. CSV nie zawiera informacji o laboratorium, więc wykonawca jest brakujący, chyba że wyślesz X-Anpheros-Acting-As.

Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,4;%;4,0-5,6;01.09.2026
TSH;2,1;mUI/L;0,4-4,0;01.09.2026

JSON gdy masz już dane strukturalne: {"date": "2026-09-01", "origin": "report-77", "laboratory": "Synevo", "items": [{"marker": "TSH", "value": 2.1, "unit": "mUI/L", "ref_low": 0.4, "ref_high": 4.0, "code": "3016-3"}]}.

Obowiązujące zasady mapowania

• LOINC, gdy podano, w przeciwnym razie według nazwy. Nazwy są dopasowywane do nazw i synonimów LOINC w języku rumuńskim i angielskim. Nazwa, która pasuje do kilku koncepcji lub zawiera kwalifikator, którego koncepcja nie posiada (mocz, non-HDL, wolny, stosunek), nie jest zgadywana: zachowuje kod laboratorium pod urn:anpheros:lab-code i pojawia się w unmapped, dzięki czemu możesz ulepszyć mapowanie po swojej stronie. Wysyłaj kody LOINC, gdy tylko je posiadasz.
• Wartości nigdy nie są konwertowane. Mocznika i azotu mocznika to różne kody; LDL bezpośredni i LDL obliczony to różne kody; glukoza z surowicy i z krwi kapilarnej to różne kody. Łącznik wybiera właściwy na podstawie nazwy i metody, a liczbę pozostawia bez zmian.
• Czasy zachowują swoją strefę. Czas v2 z przesunięciem jest zachowywany; bez niego używane jest przesunięcie z MSH-7 z ostrzeżeniem; bez żadnego przesunięcia zapisywana jest tylko data. Czasy CSV nie zawierają strefy i są zapisywane jako daty.
• Idempotentność. Ponowne wysłanie tego samego raportu z tym samym Idempotency-Key spowoduje otrzymanie tej samej odpowiedzi i brak duplikatów.
• Provenance dla każdego wyniku: system źródłowy, identyfikator raportu i wykonawca, zgodnie z wymaganiami HL7 Europe Laboratory Report.

Co widzi pacjent

Wyniki pojawiają się w karcie pacjenta, a jeśli korzysta z Anpheros Daily, na jego telefonie w miarę ich nadejścia, wraz z zakresem referencyjnym i trendem z poprzednich raportów. Nic do skanowania, nic do przepisywania. Jeśli wynik jest nieprawidłowy, pacjent widzi flagę; aplikacja jej nie interpretuje.

Testowanie

Piaskownica jest bezpłatna, a syntetyczni pacjenci mają już historię badań laboratoryjnych. Wyślij raport do jednego z nich i odczytaj go ponownie:

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" --data-binary @report.csv
curl "$BASE/fhir/R4/Observation?patient=$PID&category=laboratory&_sort=-date" -H "Authorization: Bearer $KEY"

Pełna specyfikacja, w tym uwagi dotyczące zgodności z HL7 Europe, znajduje się na stronie developers.anpheros.com/guides/lab-connector.

Najczęstsze pytania

Czy musimy zmieniać to, co produkuje nasz LIS?

Nie. Wyślij komunikat ORU^R01 lub eksport CSV w obecnej formie. Jeśli możesz dodać kody LOINC, zrób to; w przeciwnym razie łącznik mapuje według nazwy i informuje, czego nie udało się zmapować.

Co z wynikami, których nie można zmapować?

Są one przechowywane z własnym kodem laboratorium i dokładnym tekstem z raportu, więc nic nie jest tracone, i są wymienione w unmapped, abyś mógł dodać kod LOINC następnym razem.

Czy zakresy referencyjne i flagi nieprawidłowości są zachowywane?

Tak: zakres trafia do referenceRange, flaga do interpretation, jednostka jest przechowywana jako UCUM, a wartość nigdy nie jest konwertowana.

Czy laboratorium może wysyłać wyniki dla pacjenta, którego nie stworzyło?

Tylko za zgodą osoby, lub jako organizacja, dla której działa projekt, z użyciem X-Anpheros-Acting-As. Projekt widzi pacjentów, których stworzył; wszystko inne wymaga zgody.

Czy integracja jest płatna?

Piaskownica jest bezpłatna. Produkcja zaczyna się od 49 € miesięcznie na organizację, z pierwszym miesiącem bezpłatnie; zobacz cennik.