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

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

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

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

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 — veja também o exemplo DiagnosticReport.

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

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 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: 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.

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, é:

{
  "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:

{
  "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:

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 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).

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.

Verifique os resultados antes de os enviar

O validador FHIR R4 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.

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: cada segmento e campo OBX
• Como importar resultados de laboratório para um registo FHIR: o tutorial passo a passo
• Conector de laboratório: a referência do endpoint
• Como normalizar dados médicos: LOINC, UCUM, datas, intervalos e duplicados
• Proveniência de dados médicos explicada
• Sistemas de código FHIR
• Como integrar sistemas clínicos com um backend FHIR
• FHIR vs HL7 v2: diferenças práticas
• HL7 v2 e FHIR para dashboards clínicos: de uma mensagem de laboratório a um tile de dashboard

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