# Conector de laboratorio

> Envía un informe de laboratorio completo como CSV, HL7 v2 ORU^R01 o JSON y obtén Observaciones de laboratorio con códigos LOINC y rangos de referencia.

Source: https://developers.anpheros.com/es/guides/lab-connector

Un laboratorio (o cualquier persona que posea un informe de laboratorio) envía el informe completo en una solicitud y la
plataforma convierte cada resultado en una `Observation` de laboratorio del paciente:

```
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        (optional; recorded in Provenance)
Idempotency-Key: <report id>          (optional; a retry returns the same answer)
```

## Formatos

**CSV** con fila de encabezado; separadores `,` `;` o tabulación, coma decimal aceptada, fechas ISO,
`DD.MM.YYYY` o `DD/MM/YYYY`. Columnas reconocidas (rumano o inglés): marcador
(`analiza`, `test`, `marker`, `name`) — o solo una columna LOINC `code`, en cuyo caso el nombre LOINC se convierte en el marcador —
valor (`rezultat`, `valoare`, `value`, `result`), unidad (`um`, `unitate`, `unit`),
rango de referencia (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) o `ref_low`/`ref_high`,
fecha (`data`, `recoltare`), LOINC opcional (`loinc`, `code`), nota.

```
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
```

**HL7 v2 ORU^R01** (texto ER7, segmentos separados por CR o LF): `OBX-3` identificador (`code^text^LN`
es LOINC; un código local (`^L`, `^99zzz`) o cualquier otro sistema de codificación se mantiene como el código propio del laboratorio bajo
`urn:anpheros:lab-code`), `OBX-5` valor (`NM`, `SN`, o texto),
`OBX-6` unidad, `OBX-7` rango de referencia, `OBX-8` indicador de anormalidad → `interpretation`, `OBX-11` estado,
`OBX-14` o `OBR-7` fecha; `OBR-3`/`MSH-10` se convierten en el ID del informe en Provenance.

**El laboratorio.** Cada resultado nombra quién lo produjo en `performer`, como requiere el informe de laboratorio HL7 Europe 2.1.0:
la organización para la que actúa (`X-Anpheros-Acting-As`), de lo contrario `MSH-4` (instalación de envío) para HL7, o
`laboratory` en JSON (nivel superior o por elemento). Un CSV no lleva laboratorio; tales resultados se validan con un
ejecutor ausente, que es la verdad.

**Informes de texto, documentos y fechas faltantes.** Un informe de texto enviado una línea por OBX (`TX`/`FT`, mismo `OBX-3`)
se convierte en un resultado con las líneas unidas. Un documento completo en `OBX-5` (`ED`, o cualquier valor codificado `Base64`) no se almacena como resultado; la respuesta advierte y el documento pertenece a `/documents`. Sin `OBR-7`, los resultados se fechan por
`OBR-14` (muestra recibida), con una advertencia.

**Horas y zonas horarias.** Una hora v2 sin zona horaria es la hora local del remitente, no UTC. El desplazamiento enviado con
`OBX-14`/`OBR-7` (`20260901081000+0300`) se mantiene (`2026-09-01T08:10:00+03:00`). Sin uno, se utiliza el desplazamiento de `MSH-7`
y una advertencia lo indica; sin desplazamiento en ninguna parte, el resultado solo conserva su fecha, también con una advertencia. Las horas CSV
(`01.09.2026 08:10`) no llevan zona horaria, por lo que se almacenan solo como fechas. Hasta el 17 de octubre de 2026, dichas horas se etiquetaron como UTC; los resultados importados entonces conservan sus identificadores y siguen siendo reconocidos cuando se vuelve a enviar un informe.

Los resultados de HL7 que aún están pendientes (OBX-11 `I`), no disponibles (`X`), eliminados (`D`) o incorrectos (`W`), y los segmentos OBX
sin valor, no se convierten en Observaciones; cada uno se nombra en `warnings`.

**JSON**: `{"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, "date": "2026-09-01", "code": "3016-3"}]}`.

## Lo que recibe

```json
{"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"}]}
```

- Los marcadores se mapean a **LOINC** cuando el informe proporciona un código LOINC o el nombre coincide con la
  terminología de la plataforma (nombres en rumano e inglés y alias comunes). Otros conservan el código del laboratorio bajo `urn:anpheros:lab-code` con el texto exacto del informe, y se listan en `unmapped`
  para que pueda mejorar el mapeo por su cuenta. El código propio de un laboratorio solo es único junto con su laboratorio:
  el sistema de origen se registra en la Provenance de cada Observación (`X-Anpheros-Source-System`).
- Los nombres se comparan con los nombres y sinónimos de LOINC (por ejemplo, *Hemoglobin A1c*, *Glycated hemoglobin*,
  *HDL cholesterol*, *LDL-C*). Un nombre que coincide con varios conceptos, o que lleva un calificador que el concepto no tiene
  (*urine*, *non-HDL*, *free*, *ratio*…), no se adivina: conserva el código del laboratorio y se lista en
  `unmapped`. Envíe códigos LOINC siempre que su sistema los tenga.
- Urea y nitrógeno de urea (BUN) son mediciones diferentes: *Uree* / *Urea* se mapea a urea (LOINC `3091-6`, o
  `22664-7` en mmol/L), *BUN* / *Urea nitrogen* / *Azot ureic* a nitrógeno de urea (`3094-0`, o `14937-7` en mmol/L).
  Los valores nunca se convierten.
- Colesterol LDL: un nombre sin método se mapea a `2089-1`; *calculated* / *calculat* / *Friedewald* al LDL calculado
  (`13457-7`); *direct* al ensayo directo (`18262-6`). El método es un calificador, como *direct* en *Bilirubina
  directa*, que no es bilirrubina total y conserva el código del laboratorio.
- Glucosa: una "Glicemie" / "Glucose" simple en un informe de laboratorio se mapea a suero o plasma (LOINC `2345-7`);
  un nombre que indica capilar, punción dactilar o sangre total ("capilar", "sânge integral") a sangre total (`2339-0`).
  Un código LOINC en el informe siempre tiene prioridad.
- Cada fila recibe un identificador estable (`urn:anpheros:lab-import:v2`) construido a partir de lo que dice el informe — ID del informe,
  el nombre y código del informe, fecha, valor y unidad — nunca del código LOINC que eligió la plataforma, por lo que
  **reenviar el mismo informe omite las filas ya importadas** (`skipped`), incluso después de que mejore el mapeo.
  Las filas que difieren en alguno de estos (otro informe, otra hora de recolección, otro valor) se mantienen separadas.
  Los resultados importados antes del 14 de octubre de 2026 conservan su identificador original y se reconocen por nombre, fecha, valor,
  unidad e ID de informe. Sin un ID de informe (CSV), dicha coincidencia se informa en `warnings`; envíe un ID de informe
  (HL7 `OBR-3`/`MSH-10`, JSON `origin`) para mantener separados los informes.
- Cada Observación lleva Provenance con `author_type = import`, su sistema de origen y el ID del informe;
  los webhooks se activan `resource.created` por Observación; el paciente ve los resultados en su aplicación y cualquier
  aplicación a la que haya consentido puede leerlos.
- Hasta 500 filas por solicitud.

Ambos SDK: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Un ejemplo práctico de un informe CSV y HL7 v2 a Observaciones FHIR, con marcadores no mapeados e informes reenviados: [Cómo importar resultados de laboratorio a un registro FHIR](https://developers.anpheros.com/es/guides/import-lab-results-fhir).

Cómo se mueven los datos de laboratorio entre laboratorios, clínicas, aplicaciones e IA, y qué buscar en una API de resultados de laboratorio: [API de resultados de laboratorio](https://developers.anpheros.com/es/guides/lab-results-api).