AnpherosAnpheros PlatformDevelopers

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Cum se importă rezultatele de laborator într-un dosar FHIR

Tutorial: importați un raport de laborator ca CSV și ca HL7 v2 ORU^R01 în Observații FHIR R4 cu coduri LOINC și intervale de referință, gestionați markeri nemapați și rapoarte retrimise și urmăriți fiecare rezultat la laboratorul său.

Acest tutorial preia un raport de laborator ca fișier CSV și ca mesaj HL7 v2 ORU^R01, îl importă într-o înregistrare HL7 FHIR R4 a unui pacient cu câte o singură cerere și arată ce primiți înapoi: resurse de laborator Observation cu coduri LOINC, intervale de referință și proveniență. Acesta acoperă, de asemenea, cele două probleme cu care se confruntă orice integrare de laborator: markeri care nu pot fi mapați automat și rapoarte care sunt trimise de două ori. Totul rulează pe sandbox-ul gratuit cu un pacient sintetic.

De ce rezultatele de laborator sunt greu de stocat

Un raport de laborator pare simplu: un marker, o valoare, o unitate, un interval de referință, o dată. În practică, fiecare laborator își numește markerii în felul său ("Hemoglobina glicozilată", "HbA1c", "Glycated haemoglobin"), folosește virgule sau puncte pentru zecimale, scrie intervale ca 4,0-5,6, <5 sau >3.5 și retrimite același raport atunci când ceva eșuează. Stocate ca text liber, aceste rezultate nu pot fi comparate în timp, graficate, partajate cu o altă aplicație sau oferite unui model AI cu încredere.

Un înregistrare FHIR stochează fiecare rezultat ca o resursă Observation cu un cod LOINC, o unitate UCUM, o valoare, un interval de referință și o dată, și păstrează cine l-a trimis într-o resursă Provenance. Conectorul de laborator face această conversie pentru dumneavoastră.

 lab report (CSV, HL7 v2, JSON)
        │  POST /v1/patients/{id}/labs/import
        ▼
 ┌──────────────────────────────────────────────┐
 │ parse rows → map marker to LOINC → parse     │
 │ value, unit, range → stable id per row       │
 └──────────────────────────────────────────────┘
        │
        ▼
 Observation (category laboratory) + Provenance (author_type import, source system, report id)
        │
        ├─► the patient's app and every app they consented to
        └─► webhooks: resource.created per Observation

Înainte de a începe

Aveți nevoie de o cheie sandbox (sk_test_…) de la platform.anpheros.com/dashboard (Obțineți o cheie sandbox). Exemplele folosesc curl; SDK-urile au aceleași apeluri (labs.importCsv, labs.importHl7, labs.importItems).

export BASE=https://platform.anpheros.com
export KEY=sk_test_…
# Elena Ionescu, a synthetic patient with type 2 diabetes
export PID=$(curl -s "$BASE/fhir/R4/Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02" \
  -H "Authorization: Bearer $KEY" | jq -r '.entry[0].resource.id')

Pasul 1: importarea unui raport CSV

Acesta este modul în care un laborator românesc ar putea exporta un raport: punct și virgulă, virgule zecimale, nume de coloane românești și date ca DD.MM.YYYY. Conectorul recunoaște nume de coloane românești și englezești.

cat > report.csv <<'EOF'
Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,9;%;4,0-5,6;01.10.2026
Glicemie;131;mg/dL;70-100;01.10.2026
TSH;2,1;mUI/L;0,4-4,0;01.10.2026
Marker foarte rar;12;U/L;0-20;01.10.2026
EOF

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" -H "X-Anpheros-Source-System: labx" \
     -H "Idempotency-Key: report-2026-10-01-elena" --data-binary @report.csv

Răspunsul (201):

{"created": 4, "skipped": 0, "unmapped": ["Marker foarte rar"], "warnings": [],
 "observations": [
  {"id": "ff0bbb44-…", "marker": "Hemoglobina glicozilata (HbA1c)", "code": "4548-4", "system": "http://loinc.org", "value": 6.9, "unit": "%", "date": "2026-10-01"},
  {"id": "ebe5522f-…", "marker": "Glicemie", "code": "2345-7", "system": "http://loinc.org", "value": 131.0, "unit": "mg/dL", "date": "2026-10-01"},
  {"id": "bace44a8-…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org", "value": 2.1, "unit": "mUI/L", "date": "2026-10-01"},
  {"id": "26fd2270-…", "marker": "Marker foarte rar", "code": "marker_foarte_rar", "system": "urn:anpheros:lab-code", "value": 12.0, "unit": "U/L", "date": "2026-10-01"}]}

HbA1c, glucoza și TSH au fost mapate la LOINC din denumirile lor. Virgulele zecimale au devenit numere, iar intervalele au devenit referenceRange. O linie a revenit în unmapped. Aceasta este încă stocată, sub codul propriu al laboratorului (urn:anpheros:lab-code) cu textul exact din raport, astfel încât nimic nu se pierde.

Pasul 2: gestionarea marcatorilor nemapați

Unele nume necesită o decizie. „Glicemie” este un exemplu bun: LOINC are un cod pentru glucoza din ser sau plasmă (2345-7, o probă venoasă prelevată într-un laborator) și altul pentru glucoza din sânge integral (2339-0, de exemplu, o înțepătură în deget). Pe un raport de laborator, un simplu „Glicemie” este mapat la ser sau plasmă. Un nume care spune „capilar”, „capilară” sau „sânge integral” este mapat la sânge integral:

{"created": 1, "skipped": 0, "unmapped": [], "warnings": [],
 "observations": [{"id": "00480a6d-…", "marker": "Glicemie capilara", "code": "2339-0", "system": "http://loinc.org", "value": 140.0, "unit": "mg/dL", "date": "2026-10-02"}]}

Pentru marcatorii pe care conectorul nu îi recunoaște, căutați codul:

curl "$BASE/v1/terminology/loinc?q=glucose" -H "Authorization: Bearer $KEY"

{"data": [
  {"system": "http://loinc.org", "code": "2339-0", "display": "Glucose [Mass/volume] in Blood", "display_ro": "Glicemie (sânge)", "category": "laboratory", "unit": "mg/dL"},
  {"system": "http://loinc.org", "code": "2345-7", "display": "Glucose [Mass/volume] in Serum or Plasma", "display_ro": "Glicemie (ser)", "category": "laboratory", "unit": "mg/dL"}],
 "total": 2}

Apoi trimiteți codul într-o coloană LOINC. Un cod din raport primează întotdeauna în fața numelui. Păstrați această mapare pe laborator de partea dvs. și adăugați coloana la fiecare raport de la acesta:

Analiza;Rezultat;UM;Interval de referinta;Data;LOINC
Glicemie;99;mg/dL;70-100;04.10.2026;2339-0

Marcatorii pe care LOINC nu îi acoperă deloc, cum ar fi „Marker foarte rar” inventat, pot rămâne sub codul laboratorului. Aceștia sunt afișați pacientului și incluși în fișa medicală. Nu pot fi comparați cu rezultatele altor laboratoare.

Pasul 3: trimiteți același raport de două ori

Laboratoarele retransmit rapoarte. Fiecare rând primește un identificator stabil construit din ID-ul raportului, codul, data și valoarea, astfel încât o a doua importare a aceluiași raport nu creează nimic:

{"created": 0, "skipped": 4, "unmapped": ["Marker foarte rar"], "warnings": [], "observations": []}

Rândurile care s-au modificat, o valoare corectată de exemplu, sunt importate ca noi rezultate. Antetul Idempotency-Key adaugă o a doua garanție: o reîncercare de rețea cu aceeași cheie returnează primul răspuns neschimbat.

Pasul 4: importarea unui mesaj HL7 v2 ORU^R01

Majoritatea sistemelor informatice de laborator folosesc HL7 v2. Trimiteți mesajul așa cum este (text ER7, segmente separate prin CR sau LF):

MSH|^~\&|LABX|LAB1|ANPHEROS|EHR|202610010930||ORU^R01|MSG00077|P|2.5.1
PID|1||12345||Ionescu^Elena||19850903|F
OBR|1||R-77|24331-1^Lipid panel^LN|||202610010800
OBX|1|NM|2093-3^Cholesterol [Mass/volume] in Serum or Plasma^LN||212|mg/dL|<200|H|||F|||202610010800
OBX|2|NM|2085-9^HDL Cholesterol^LN||52|mg/dL|>40|N|||F|||202610010800

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: x-application/hl7-v2+er7" --data-binary @oru.hl7

{"created": 2, "skipped": 0, "unmapped": [], "warnings": [],
 "observations": [
  {"id": "b562045b-…", "marker": "Cholesterol [Mass/volume] in Serum or Plasma", "code": "2093-3", "system": "http://loinc.org", "value": 212.0, "unit": "mg/dL", "date": "2026-10-01T08:00:00Z"},
  {"id": "9b3274e4-…", "marker": "HDL Cholesterol", "code": "2085-9", "system": "http://loinc.org", "value": 52.0, "unit": "mg/dL", "date": "2026-10-01T08:00:00Z"}]}

OBX-3 cu sistemul de codificare LN este utilizat direct ca LOINC. OBX-7 devine intervalul de referință, iar OBX-8 (H, N) interpretarea. OBR-3 (R-77) este păstrat ca ID-ul raportului în provenance. Pacientul este cel din URL: segmentul PID nu este utilizat pentru a găsi un pacient, deci un PID greșit nu poate atașa rezultate altei persoane.

Aveți deja rezultate parsate? Trimiteți JSON: {"date": "2026-10-01", "origin": "report-77", "items": [{"marker": "Ferritin", "value": 38, "unit": "ng/mL", "ref_low": 15, "ref_high": 150}]}. Ferritin este mapat la LOINC 2276-4.

Pasul 5: citirea rezultatelor ca FHIR

curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date&_count=1" \
     -H "Authorization: Bearer $KEY"

HbA1c importat, așa cum este stocat:

{
  "resourceType": "Observation",
  "id": "62b1b0c0-…",
  "meta": {"versionId": "1", "lastUpdated": "2026-10-12T20:05:57.011Z"},
  "identifier": [{"system": "urn:anpheros:lab-import", "value": "c52d3cd6449291d34f6bef1516d0ac05"}],
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c/Hemoglobin.total in Blood"}],
           "text": "Hemoglobina glicozilata (HbA1c)"},
  "subject": {"reference": "Patient/…"},
  "effectiveDateTime": "2026-10-01",
  "valueQuantity": {"value": 6.9, "unit": "%"},
  "referenceRange": [{"low": {"value": 4.0, "unit": "%"}, "high": {"value": 5.6, "unit": "%"}}]
}

Afisajul LOINC este numele standard în limba engleză. code.text păstrează formularea proprie a laboratorului, astfel încât pacientul să vadă în continuare ce a fost pe raportul pe hârtie. Pentru mai multe informații despre resurse și căutare, consultați ghidul platforma FHIR și sistemele de coduri FHIR.

Pasul 6: verificați cine a trimis-o

curl "$BASE/v1/patients/$PID/provenance/Observation/62b1b0c0-…" -H "Authorization: Bearer $KEY"

{"data": [{"version": 1, "activity": "CREATE", "recorded": "2026-10-12T20:05:57.011000Z",
           "author_type": "import", "author": "proj_…", "source_system": "labx", "origin_id": null,
           "fhir": "Provenance/f15c4fee-…"}], "total": 1}

author_type: import și source_system: labx rămân cu valoarea. Când o aplicație AI citește ulterior acest rezultat prin API-ul de context, acesta este etichetat [import/labx], astfel încât modelul să poată distinge un rezultat de laborator de o valoare introdusă de pacient.

Ce urmează

Întrebări frecvente

Ce formate de rapoarte de laborator pot fi importate în FHIR?

CSV cu un rând de antet (acceptă virgulă, punct și virgulă sau tabulator, virgulă zecimală), mesaje HL7 v2 ORU^R01 și JSON. Rapoartele PDF pot fi stocate ca documente; valorile extrase din acestea indică înapoi către document.

Ce se întâmplă cu markerii fără un cod LOINC?

Aceștia sunt stocați sub codul propriu al laboratorului, cu textul exact din raport și listați în unmapped. Adăugați o coloană LOINC pentru acel laborator și aceștia vor fi mapați. Un cod din raport are întotdeauna prioritate față de nume.

Este sigur să retrimiteți un raport?

Da. Fiecare rând are un identificator stabil construit din raport, cod, dată și valoare, astfel încât rândurile deja importate sunt omise; rândurile modificate sunt importate ca rezultate noi.

Poate un laborator să importe rezultate pentru orice pacient?

Nu. Un laborator importă în pacienții proiectului său creat sau ale căror înregistrări persoana i le-a partajat prin OAuth. Alți pacienți nu există pentru acesta (404).

Conexe

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Product updates by email

New features, guides and the end of the beta. One email a month at most.

Send me occasional Anpheros Platform updates by email (new features, API changes, guides). I'll confirm by email and can unsubscribe in one click from any email. Privacy