# API de resultados de laboratório: HL7 v2, FHIR e LOINC

> Como os resultados de laboratório viajam como dados HL7 v2 e FHIR, o que um resultado deve conter e como receber relatórios de laboratório num registo FHIR, com um exemplo real.

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

**Uma API de resultados de laboratório entrega resultados de laboratório como dados estruturados — código do teste, valor, unidade, intervalo de referência, estado e hora — em vez de um PDF, para que o software possa armazená-los, compará-los, graficá-los e partilhá-los.** Atualmente, esses dados viajam em três formatos: mensagens HL7 v2 ORU^R01 (ainda a espinha dorsal entre laboratórios e hospitais), recursos HL7 FHIR R4 `Observation` e `DiagnosticReport` (o formato das APIs modernas) e exportações CSV, JSON ou PDF específicas do laboratório. Esta página explica como as peças se encaixam, o que uma boa API de resultados de laboratório deve conter e como receber dados de laboratório no registo FHIR de um paciente com Anpheros.

## Quem troca resultados de laboratório e em que formato

| De → Para | Formato usual hoje | Notas |
|---|---|---|
| Laboratório → sistema hospitalar ou clínico | HL7 v2 ORU^R01 (nos EUA, frequentemente de acordo com o guia HL7 v2.5.1 Laboratory Results Interface) | As requisições seguem na direção oposta como mensagens ORM/OML |
| Laboratório → agência de saúde pública | Relatórios eletrónicos de laboratório HL7 v2, cada vez mais FHIR | Apenas condições reportáveis |
| Sistema clínico → aplicação para o paciente | FHIR R4 através de uma API de acesso ao paciente | Nos EUA, os EHRs certificados expõem os resultados de laboratório como FHIR (US Core); na UE, o European Health Data Space lista os resultados de laboratório entre as suas categorias de dados prioritárias |
| Laboratório → paciente | Relatório em PDF, portal, por vezes CSV | O formato que a maioria dos pacientes realmente recebe |
| Aplicação → modelo de IA | Contexto estruturado construído a partir de Observations | Necessita de códigos e unidades para ser fiável |

A direção importa: um sistema de informação laboratorial (LIS) é a fonte da verdade para um resultado, e cada sistema a jusante mantém uma cópia. O que torna as cópias fidedignas é que cada uma mantém o código, a unidade, o intervalo e a origem do valor.

## O que um resultado de laboratório precisa de transportar

Um resultado que diz apenas "Glicose 126" não pode ser interpretado em segurança. Um resultado completo tem:

- **Um código padrão.** LOINC identifica o analito, a amostra e o método: `2345-7` é glicose em soro ou plasma, `2339-0` é glicose em sangue total. O código próprio do laboratório pode acompanhar.
- **Um valor com unidade.** Idealmente uma unidade UCUM (`mg/dL`, `mmol/L`, `10*3/uL`), para que valores de dois laboratórios possam ser convertidos e comparados.
- **O intervalo de referência** que o laboratório utilizou e uma bandeira de **interpretação** (H, L, N…) quando o laboratório fornece uma.
- **Estado:** preliminar, final, corrigido ou alterado. As correções acontecem; uma API deve permitir ver a nova versão sem perder a antiga.
- **Tempos:** quando a amostra foi recolhida (`effectiveDateTime`) e quando o resultado foi emitido (`issued`).
- **Origem:** qual laboratório o produziu e a que relatório ou pedido pertence.

Em FHIR R4, cada resultado é um `Observation` com `category = laboratory`, e o relatório que os agrupa é um `DiagnosticReport` que lista as Observações em `result`. Exemplos válidos de ambos, com os erros que os validadores reportam com mais frequência, estão nos [exemplos JSON FHIR R4](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result) — veja também o [exemplo DiagnosticReport](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report).

## HL7 v2 e FHIR lado a lado

O mesmo resultado de painel lipídico, como a maioria dos laboratórios o envia hoje e como uma API deveria armazená-lo:

```
OBX|1|NM|2093-3^Cholesterol^LN||212|mg/dL|<200|H|||F|||20261002074500
```

| Campo HL7 v2 | Significado | Elemento de Observação FHIR R4 |
|---|---|---|
| OBX-3 `2093-3^Cholesterol^LN` | Teste, codificado em LOINC | `code.coding` (sistema `http://loinc.org`) |
| OBX-5 `212`, OBX-2 `NM` | Valor numérico | `valueQuantity.value` |
| OBX-6 `mg/dL` | Unidade | `valueQuantity.unit` |
| OBX-7 `<200` | Intervalo de referência | `referenceRange.high` |
| OBX-8 `H` | Indicador de anormalidade | `interpretation` |
| OBX-11 `F` | Resultado final | `status = final` |
| OBX-14 | Hora da observação | `effectiveDateTime` |

A conversão entre os dois é, na sua maioria, um mapeamento de campos. As partes difíceis estão noutro lugar: laboratórios que enviam os seus próprios códigos em vez de LOINC, números escritos como texto (`"6,4"`, `"<5"`), intervalos em várias notações e relatórios que são enviados novamente após um timeout. [Como normalizar dados médicos](https://developers.anpheros.com/pt/guides/normalize-medical-data) aborda esses pontos em detalhe.

## Receber resultados de laboratório num registo FHIR com Anpheros

O Anpheros armazena o registo de cada paciente como HL7 FHIR R4 e tem um [conetor de laboratório](https://developers.anpheros.com/pt/guides/lab-connector): um pedido aceita um relatório completo como HL7 v2, CSV ou JSON e devolve Observações de laboratório com códigos LOINC, intervalos de referência, interpretação e proveniência.

```bash
curl -s -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "X-Anpheros-Source-System: springfield-lis" \
  --data-binary @lipid-panel.hl7
```

Para um painel lipídico de três linhas (colesterol, HDL, triglicerídeos), a resposta, de uma execução local da plataforma, é:

```json
{
  "created": 3, "skipped": 0, "unmapped": [], "warnings": [],
  "observations": [
    {"id": "26ed9219-…", "marker": "Cholesterol", "code": "2093-3", "system": "http://loinc.org",
     "value": 212.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "2633d1d4-…", "marker": "HDL cholesterol", "code": "2085-9", "system": "http://loinc.org",
     "value": 48.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "a02520bb-…", "marker": "Triglyceride", "code": "2571-8", "system": "http://loinc.org",
     "value": 165.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"}
  ]
}
```

Cada resultado armazenado é uma Observação FHIR R4 padrão, legível por qualquer cliente FHIR:

```json
{
  "resourceType": "Observation",
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "2093-3",
                        "display": "Cholesterol [Mass/volume] in Serum or Plasma"}], "text": "Cholesterol"},
  "subject": {"reference": "Patient/4c3062d9-…"},
  "effectiveDateTime": "2026-10-02T07:45:00Z",
  "valueQuantity": {"value": 212.0, "unit": "mg/dL"},
  "interpretation": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation", "code": "H"}]}],
  "referenceRange": [{"high": {"value": 200.0, "unit": "mg/dL"}}]
}
```

Enviar a mesma mensagem novamente não cria nada de novo (`"created": 0, "skipped": 3`): cada linha obtém um identificador estável a partir do ID do relatório, código, data e valor. Marcadores que a plataforma não consegue mapear para LOINC mantêm o código do laboratório e regressam em `unmapped`, para que possa corrigir o mapeamento na origem.

Ler resultados de volta é uma pesquisa FHIR padrão:

```bash
curl -s "https://platform.anpheros.com/fhir/R4/Observation?patient=$PID&category=laboratory&code=http://loinc.org|2093-3" \
  -H "Authorization: Bearer $KEY"
```

Outras formas de entrada e saída dos mesmos dados:

- **FHIR diretamente:** `POST /fhir/R4/Observation`, ou um Bundle de transação com o `DiagnosticReport` e as suas Observações em conjunto.
- **Eventos:** um [webhook](https://developers.anpheros.com/pt/guides/webhooks) `resource.created` por Observação, para que uma clínica ou uma aplicação possa reagir quando os resultados chegam.
- **Para pessoas e IA:** o paciente vê os resultados na sua aplicação; aplicações às quais dão consentimento leem-nos; `POST /v1/context` fornece a um modelo de IA um resumo rotulado pela origem que inclui valores de laboratório recentes.
- **Proveniência:** cada resultado importado regista `author_type = import`, o sistema de origem e o ID do relatório ([proveniência de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-provenance)).

O percurso completo, com um relatório CSV, uma mensagem HL7 v2, marcadores não mapeados e relatórios reenviados num paciente sintético, é o tutorial [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir).

## Verifique os resultados antes de os enviar

O [validador FHIR R4](https://developers.anpheros.com/tools/fhir-validator) gratuito verifica a estrutura de uma Observação e os conjuntos de valores necessários, e com o perfil `eu-lab` também verifica o que um resultado de laboratório deve conter: a categoria `laboratory`, um código LOINC, um sujeito, um estado final-type, uma hora, um valor, uma unidade UCUM e um intervalo de referência. As mesmas verificações são executadas na plataforma através de `POST /fhir/R4/Observation/$validate?profile=eu-lab`.

## Escolher uma API de resultados de laboratório: uma lista de verificação

- Armazena os resultados como Observações FHIR R4 com códigos LOINC, ou como linhas no seu próprio esquema?
- Consegue aceitar os formatos que os seus laboratórios enviam na prática (HL7 v2 na maioria dos hospitais, CSV ou PDF de laboratórios mais pequenos)?
- O que acontece a um marcador que não consegue mapear: é rejeitado, descartado ou mantido com o código do laboratório?
- As tentativas de reenvio são seguras, ou um relatório reenviado cria duplicados?
- Os resultados corrigidos são versionados, com o valor anterior ainda legível?
- A origem de cada valor é registada e visível para o paciente?
- Quem pode ler os resultados, e é isso decidido pelo consentimento do paciente?

## O que o Anpheros não faz

O Anpheros não é um sistema de informação laboratorial nem está ligado a redes laboratoriais comerciais: o laboratório, a clínica ou a aplicação do paciente envia o relatório. Não encaminha pedidos de análises, não lê relatórios em PDF através desta API (a aplicação Anpheros Daily extrai resultados de fotos e PDFs no lado do paciente) e não interpreta resultados clinicamente. As unidades são armazenadas conforme o laboratório as envia; a conversão para códigos UCUM cabe ao remetente, conforme descrito em [Como normalizar dados médicos](https://developers.anpheros.com/pt/guides/normalize-medical-data).

## Perguntas Frequentes

### O que é uma API de resultados de laboratório?
Uma interface que permite ao software enviar ou receber resultados de laboratório como dados estruturados — um teste codificado, um valor com uma unidade, um intervalo de referência, um estado e uma hora — em vez de um documento. As APIs modernas de resultados de laboratório utilizam os recursos Observation e DiagnosticReport do HL7 FHIR R4; a maioria dos laboratórios ainda emite mensagens HL7 v2 ORU^R01.

### Qual sistema de códigos identifica os testes de laboratório?
LOINC. Cada código LOINC nomeia o analito, a amostra e, frequentemente, o método, pelo que `2345-7` (glicose em soro ou plasma) e `2339-0` (glicose em sangue total) são resultados diferentes. As unidades são melhor expressas em UCUM.

### Qual é a diferença entre um Observation e um DiagnosticReport?
Um Observation é um resultado individual, como colesterol 212 mg/dL. Um DiagnosticReport é o relatório como um todo — o painel que foi solicitado, quem o emitiu e quando — e lista os seus Observations em `result`.

### Posso importar mensagens HL7 v2 de laboratório para um servidor FHIR?
Sim. Cada segmento OBX mapeia para um Observation (OBX-3 para `code`, OBX-5 e OBX-6 para `valueQuantity`, OBX-7 para `referenceRange`, OBX-8 para `interpretation`). O conector de laboratório Anpheros faz isto num único pedido e mantém o ID do relatório do laboratório em Provenance.

### Como evito resultados de laboratório duplicados quando um relatório é reenviado?
Atribua a cada resultado um identificador estável derivado do relatório, do teste, da hora e do valor, e ignore as linhas cujo identificador já exista. O conector de laboratório Anpheros faz isto automaticamente e reporta a contagem como `skipped`.

## Relacionados

- [Mapeamento de HL7 v2 para FHIR](https://developers.anpheros.com/pt/guides/hl7-v2-to-fhir-mapping): cada segmento e campo OBX
- [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir): o tutorial passo a passo
- [Conector de laboratório](https://developers.anpheros.com/pt/guides/lab-connector): a referência do endpoint
- [Como normalizar dados médicos](https://developers.anpheros.com/pt/guides/normalize-medical-data): LOINC, UCUM, datas, intervalos e duplicados
- [Proveniência de dados médicos explicada](https://developers.anpheros.com/pt/guides/medical-data-provenance)
- [Sistemas de código FHIR](https://developers.anpheros.com/pt/guides/fhir-code-systems)
- [Como integrar sistemas clínicos com um backend FHIR](https://developers.anpheros.com/pt/guides/integrate-clinic-systems-fhir)
- [FHIR vs HL7 v2: diferenças práticas](https://developers.anpheros.com/pt/guides/fhir-vs-hl7-v2)
- [HL7 v2 e FHIR para dashboards clínicos](https://developers.anpheros.com/pt/guides/clinical-dashboard-hl7-fhir): de uma mensagem de laboratório a um tile de dashboard