Propojení laboratoře: jak se laboratorní zpráva ve formátu HL7 v2, CSV nebo JSON stane FHIR Observations jedním požadavkem

Laboratoř má při integraci jednu úlohu: dostat zprávu do záznamu pacienta bez přepisování, bez ztráty referenčního rozsahu a bez vymýšlení formátu, kterému nikdo jiný nerozumí. Konektor laboratoře Anpheros přijímá zprávu tak, jak ji laboratoř již produkuje, ve formátu HL7 v2, CSV nebo JSON, a převádí každý výsledek na FHIR Observation s kódem LOINC, jednotkou, referenčním rozsahem, datem a názvem laboratoře jako provádějícího subjektu. Tato příručka je smlouvou.

Technická verze pro vývojáře: Konektor laboratoře · API pro výsledky laboratoře na developers.anpheros.com, s požadavky, odpověďmi a limity. Tato stránka je verze v běžné řeči.

Jeden požadavek

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        (volitelné; zaznamenáno v Provenance)
Idempotency-Key: <report id>          (volitelné; opakovaný požadavek vrátí stejnou odpověď)

Odpověď říká, co se stalo:

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

Formáty

HL7 v2 ORU^R01, jako text ER7. OBX-3 je identifikátor (code^text^LN je LOINC; lokální kód je zachován jako vlastní kód laboratoře), OBX-5 hodnota, OBX-6 jednotka, OBX-7 referenční rozsah, OBX-8 abnormální příznak (stane se interpretation), OBX-11 stav, OBX-14 nebo OBR-7 datum. MSH-4 pojmenovává odesílající zařízení, které se stává provádějícím subjektem; OBR-3 a MSH-10 se stávají ID zprávy v Provenance. Výsledky čekající na zpracování, smazané nebo nesprávné (I, X, D, W) a segmenty OBX bez hodnoty se nestávají Observations a jsou pojmenovány ve warnings.

CSV s řádkem záhlaví; oddělovače , ; nebo tabulátor, desetinná čárka přijímána, data ISO, DD.MM.YYYY nebo DD/MM/YYYY. Rozpoznané sloupce v rumunštině nebo angličtině: marker, hodnota, jednotka, referenční rozsah (70-100, <5, >3.5) nebo ref_low/ref_high, datum, volitelný kód LOINC, poznámka. CSV nenese informaci o laboratoři, takže provádějící subjekt chybí, pokud nepošlete 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 pokud již máte strukturovaná data: {"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"}]}.

Pravidla mapování, na kterých záleží

• LOINC, pokud je uveden, jinak podle názvu. Názvy jsou porovnávány s názvy LOINC a synonymy v rumunštině a angličtině. Název, který odpovídá několika konceptům, nebo nese kvalifikátor, který koncept nemá (moč, ne-HDL, volný, poměr), se nehádá: zachová si vlastní kód laboratoře pod urn:anpheros:lab-code a objeví se v unmapped, takže si mapování můžete na své straně vylepšit. Posílejte kódy LOINC, kdykoli je máte.
• Hodnoty se nikdy nepřevádějí. Močovina a dusík močoviny jsou různé kódy; přímá LDL a vypočtená LDL jsou různé kódy; glukóza ze séra a z kapilární krve jsou různé kódy. Konektor vybere správný kód podle názvu a metody a ponechá číslo beze změny.
• Časy si zachovávají svou zónu. Čas v2 s posunem je zachován; bez něj se použije posun z MSH-7 s varováním; pokud není nikde, uloží se pouze datum. Časy v CSV neobsahují zónu a ukládají se jako data.
• Idempotentní. Pošlete stejnou zprávu dvakrát se stejným Idempotency-Key a dostanete stejnou odpověď a žádné duplikáty.
• Provenance u každého výsledku: zdrojový systém, ID zprávy a provádějící subjekt, jak vyžaduje HL7 Europe Laboratory Report.

Co vidí pacient

Výsledky se objeví v záznamu osoby a pokud používají Anpheros Daily, tak i na jejich telefonu, jakmile dorazí, s referenčním rozsahem a trendem z předchozích zpráv. Nic k naskenování, nic k přepsání. Pokud je výsledek abnormální, osoba vidí příznak; aplikace jej neinterpretuje.

Testování

Sandbox je zdarma a syntetičtí pacienti již mají historii laboratorních testů. Pošlete zprávu jednomu z nich a přečtěte si ji zpět:

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"

Úplná specifikace, včetně poznámek o shodě s HL7 Europe, je na developers.anpheros.com/guides/lab-connector.

Časté otázky

Musíme změnit to, co produkuje náš LIS?

Ne. Pošlete zprávu ORU^R01 nebo export CSV tak, jak jsou. Pokud můžete přidat kódy LOINC, udělejte to; jinak konektor mapuje podle názvu a řekne vám, co nemohl namapovat.

Co výsledky, které nemůžete namapovat?

Jsou uloženy s vlastním kódem laboratoře a přesným textem ze zprávy, takže se nic neztratí, a jsou uvedeny v unmapped, takže můžete příště přidat kód LOINC.

Jsou zachovány referenční rozsahy a abnormální příznaky?

Ano: rozsah jde do referenceRange, příznak do interpretation, jednotka je uložena jako UCUM a hodnota se nikdy nepřevádí.

Může laboratoř posílat výsledky pro pacienta, kterého nevytvořila?

Pouze s jeho souhlasem, nebo jako organizace, za kterou projekt jedná, s X-Anpheros-Acting-As. Projekt vidí pacienty, které vytvořil; vše ostatní vyžaduje oprávnění.

Je integrace zpoplatněna?

Sandbox je zdarma. Produkční provoz začíná na 49 € měsíčně za organizaci, s prvním měsícem zdarma; viz ceny.