Conector de laborator: cum un raport de laborator în HL7 v2, CSV sau JSON devine Observații FHIR într-o singură cerere

Un laborator are o singură sarcină într-o integrare: să introducă raportul în dosarul pacientului fără a tasta din nou, fără a pierde intervalul de referință și fără a inventa un format pe care nimeni altcineva nu-l citește. Conectorul de laborator Anpheros preia raportul așa cum îl produce deja laboratorul, HL7 v2, CSV sau JSON, și transformă fiecare rezultat într-o Observation FHIR cu un cod LOINC, o unitate, un interval de referință, o dată și laboratorul numit ca și executant. Acest ghid este contractul.

Versiune tehnică pentru dezvoltatori: Conector de laborator · API rezultate laborator pe developers.anpheros.com, cu cereri, răspunsuri și limite. Această pagină este versiunea în limbaj simplu.

O singură cerere

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        (opțional; înregistrat în Provenance)
Idempotency-Key: <report id>          (opțional; o reîncercare returnează același răspuns)

Răspunsul spune ce s-a întâmplat:

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

Formate

HL7 v2 ORU^R01, ca text ER7. OBX-3 este identificatorul (code^text^LN este LOINC; un cod local este păstrat ca propriul cod al laboratorului), OBX-5 valoarea, OBX-6 unitatea, OBX-7 intervalul de referință, OBX-8 indicatorul de anormalitate (devine interpretation), OBX-11 starea, OBX-14 sau OBR-7 data. MSH-4 numește unitatea de trimitere, care devine executantul; OBR-3 și MSH-10 devin ID-ul raportului în Provenance. Rezultatele în așteptare, șterse sau greșite (I, X, D, W) și segmentele OBX fără valoare nu devin Observații și sunt numite în warnings.

CSV cu un rând de antet; separatori , ; sau tab, virgulă zecimală acceptată, date ISO, DD.MM.YYYY sau DD/MM/YYYY. Coloane recunoscute în română sau engleză: marker, valoare, unitate, interval de referință (70-100, <5, >3.5) sau ref_low/ref_high, dată, cod LOINC opțional, notă. Un CSV nu transportă un laborator, deci executantul lipsește, cu excepția cazului în care trimiteți 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 când aveți deja date structurate: {"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"}]}.

Reguli de mapare importante

• LOINC când este furnizat, altfel după nume. Numele sunt comparate cu numele și sinonimele LOINC în română și engleză. Un nume care se potrivește mai multor concepte sau poartă un calificativ pe care conceptul nu îl are (urină, non-HDL, liber, raport) nu este ghicit: păstrează codul laboratorului sub urn:anpheros:lab-code și apare în unmapped, astfel încât să puteți îmbunătăți maparea pe partea dvs. Trimiteți coduri LOINC ori de câte ori le aveți.
• Valorile nu sunt niciodată convertite. Ureea și azotul ureic sunt coduri diferite; LDL direct și LDL calculat sunt coduri diferite; glucoza din ser și din sânge capilar sunt coduri diferite. Conectorul alege codul corect din nume și metodă și lasă numărul neschimbat.
• Orele își păstrează zona. O oră v2 cu un offset este păstrată; fără unul, se folosește offsetul din MSH-7 cu o avertizare; fără niciunul nicăieri, se stochează doar data. Orele CSV nu poartă zonă și sunt stocate ca date.
• Idempotență. Trimiteți același raport de două ori cu același Idempotency-Key și veți primi același răspuns și nicio duplicare.
• Provenance pe fiecare rezultat: sistemul sursă, ID-ul raportului și executantul, așa cum cere HL7 Europe Laboratory Report.

Ce vede pacientul

Rezultatele apar în dosarul persoanei și, dacă folosesc Anpheros Daily, pe telefonul lor pe măsură ce sosesc, cu intervalul de referință și tendința față de rapoartele anterioare. Nimic de scanat, nimic de tastat din nou. Dacă un rezultat este anormal, persoana vede indicatorul; aplicația nu îl interpretează.

Testare

Sandbox-ul este gratuit și pacienții sintetici au deja istoric de analize. Trimiteți un raport unuia dintre ei și citiți-l înapoi:

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"

Specificația completă, inclusiv notele de conformitate HL7 Europe, se găsește la developers.anpheros.com/guides/lab-connector.

Întrebări frecvente

Trebuie să schimbăm ce produce LIS-ul nostru?

Nu. Trimiteți mesajul ORU^R01 sau exportul CSV așa cum sunt. Dacă puteți adăuga coduri LOINC, faceți-o; altfel, conectorul mapează după nume și vă spune ce nu a putut mapa.

Ce se întâmplă cu rezultatele pe care nu le puteți mapa?

Sunt stocate cu propriul cod al laboratorului și textul exact din raport, astfel încât nimic să nu se piardă, și listate în unmapped, astfel încât să puteți adăuga un cod LOINC data viitoare.

Sunt păstrate intervalele de referință și indicatorii de anormalitate?

Da: intervalul merge la referenceRange, indicatorul la interpretation, unitatea este stocată ca UCUM, iar valoarea nu este niciodată convertită.

Poate un laborator să trimită rezultate pentru un pacient pe care nu l-a creat?

Doar sub consimțământul persoanei sau ca organizație pentru care proiectul acționează cu X-Anpheros-Acting-As. Un proiect vede pacienții pe care i-a creat; tot restul necesită o autorizație.

Există un cost pentru integrare?

Sandbox-ul este gratuit. Producția începe de la 49 € pe lună per organizație, cu prima lună gratuită; consultați prețuri.