# Conector de Laboratório

> Envie um relatório laboratorial completo como CSV, HL7 v2 ORU^R01 ou JSON e obtenha Observações laboratoriais com códigos LOINC e intervalos de referência.

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

Um laboratório (ou qualquer pessoa que detenha um relatório laboratorial) envia o relatório completo numa única solicitação e a plataforma transforma cada resultado numa `Observation` laboratorial do 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** com linha de cabeçalho; separadores `,` `;` ou tabulação, vírgula decimal aceite, datas ISO,
`DD.MM.YYYY` ou `DD/MM/YYYY`. Colunas reconhecidas (romeno ou inglês): marcador
(`analiza`, `test`, `marker`, `name`) — ou apenas uma coluna LOINC `code`, caso em que o nome LOINC se torna o marcador —
valor (`rezultat`, `valoare`, `value`, `result`), unidade (`um`, `unitate`, `unit`),
intervalo de referência (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) ou `ref_low`/`ref_high`,
data (`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 ou LF): `OBX-3` identificador (`code^text^LN`
é LOINC; um código local (`^L`, `^99zzz`) ou qualquer outro sistema de codificação é mantido como código próprio do laboratório em
`urn:anpheros:lab-code`), `OBX-5` valor (`NM`, `SN`, ou texto),
`OBX-6` unidade, `OBX-7` intervalo de referência, `OBX-8` flag anormal → `interpretation`, `OBX-11` estado,
`OBX-14` ou `OBR-7` data; `OBR-3`/`MSH-10` tornam-se o ID do relatório em Provenance.

**O laboratório.** Cada resultado nomeia quem o produziu em `performer`, como o HL7 Europe Laboratory Report 2.1.0
exige: a organização para a qual atua (`X-Anpheros-Acting-As`), caso contrário `MSH-4` (instalação de envio) para HL7, ou
`laboratory` em JSON (nível superior ou por item). Um CSV não carrega laboratório; tais resultados validam com um performer em falta,
que é a verdade.

**Relatórios de texto, documentos e datas em falta.** Um relatório de texto enviado uma linha por OBX (`TX`/`FT`, mesmo `OBX-3`)
torna-se um resultado com as linhas unidas. Um documento inteiro em `OBX-5` (`ED`, ou qualquer valor codificado `Base64`) não é
armazenado como resultado; a resposta avisa e o documento pertence a `/documents`. Sem `OBR-7`, os resultados são datados por
`OBR-14` (espécime recebido), com um aviso.

**Horas e fusos horários.** Uma hora v2 sem fuso horário é a hora local do remetente, não UTC. O offset enviado com
`OBX-14`/`OBR-7` (`20260901081000+0300`) é mantido (`2026-09-01T08:10:00+03:00`). Sem um, o offset de `MSH-7` é
usado e um aviso informa; sem offset em qualquer lugar, o resultado mantém apenas a sua data, também com um aviso. Horas CSV
(`01.09.2026 08:10`) não carregam fuso horário, pelo que são armazenadas apenas como datas. Até 17 de outubro de 2026 tais horas eram
rotuladas UTC; resultados importados nessa altura mantêm os seus identificadores e ainda são reconhecidos quando um relatório é enviado novamente.

Resultados HL7 que ainda estão pendentes (OBX-11 `I`), indisponíveis (`X`), eliminados (`D`) ou errados (`W`), e segmentos OBX
sem valor, não se tornam Observações; cada um é nomeado em `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"}]}`.

## O que recebe de volta

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

- Os marcadores são mapeados para **LOINC** quando o relatório fornece um código LOINC ou o nome corresponde à
  terminologia da plataforma (nomes romenos e ingleses e sinónimos comuns). Outros mantêm o código do laboratório em `urn:anpheros:lab-code` com o texto exato do relatório, e são listados em `unmapped`
  para que possa melhorar o mapeamento do seu lado. O código próprio de um laboratório é único apenas em conjunto com o seu laboratório:
  o sistema de origem é registado na Proveniência de cada Observação (`X-Anpheros-Source-System`).
- Os nomes são comparados com nomes e sinónimos LOINC (por exemplo, *Hemoglobin A1c*, *Glycated hemoglobin*,
  *HDL cholesterol*, *LDL-C*). Um nome que corresponda a vários conceitos, ou que contenha um qualificador que o conceito não tem (*urine*, *non-HDL*, *free*, *ratio*…), não é adivinhado: mantém o código do laboratório e é listado em
  `unmapped`. Envie códigos LOINC sempre que o seu sistema os tiver.
- Ureia e nitrogénio ureico (BUN) são medições diferentes: *Ureia* / *Urea* mapeia para ureia (LOINC `3091-6`, ou
  `22664-7` em mmol/L), *BUN* / *Urea nitrogen* / *Azot ureic* para nitrogénio ureico (`3094-0`, ou `14937-7` em mmol/L).
  Os valores nunca são convertidos.
- Colesterol LDL: um nome sem método mapeia para `2089-1`; *calculado* / *calculat* / *Friedewald* para o LDL calculado
  (`13457-7`); *direct* para o ensaio direto (`18262-6`). O método é um qualificador, como *direct* em *Bilirubina
  directa*, que não é bilirrubina total e mantém o código do laboratório.
- Glicose: uma "Glicemia" / "Glucose" simples num relatório de laboratório é mapeada para soro ou plasma (LOINC `2345-7`);
  um nome que diga capilar, picada no dedo ou sangue total ("capilar", "sânge integral") para sangue total (`2339-0`).
  Um código LOINC no relatório tem sempre prioridade.
- Cada linha recebe um identificador estável (`urn:anpheros:lab-import:v2`) construído a partir do que o relatório diz — id do relatório,
  o nome e código no relatório, data, valor e unidade — nunca a partir do código LOINC que a plataforma escolheu, pelo que
  **o reenvio do mesmo relatório ignora linhas já importadas** (`skipped`), mesmo após a melhoria do mapeamento.
  As linhas que diferem em qualquer um destes (outro relatório, outra hora de colheita, outro valor) são mantidas separadas.
  Os resultados importados antes de 14 de outubro de 2026 mantêm o seu identificador original e são reconhecidos pelo nome, data, valor,
  unidade e id do relatório. Sem um id de relatório (CSV), tal correspondência é reportada em `warnings`; envie um id de relatório
  (HL7 `OBR-3`/`MSH-10`, JSON `origin`) para manter relatórios separados.
- Cada Observação carrega Proveniência com `author_type = import`, o seu sistema de origem e o id do relatório;
  os webhooks disparam `resource.created` por Observação; o paciente vê os resultados na sua aplicação e qualquer
  aplicação para a qual consentiu pode lê-los.
- Até 500 linhas por pedido.

Ambos os SDKs: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Um exemplo prático de um relatório CSV e HL7 v2 para Observações FHIR, com marcadores não mapeados e relatórios reenviados: [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir).

Como os dados de laboratório se movem entre laboratórios, clínicas, aplicações e IA, e o que procurar numa API de resultados de laboratório: [API de resultados de laboratório](https://developers.anpheros.com/pt/guides/lab-results-api).