# Mapeamento de HL7 v2 para FHIR

> Mapeamento de segmento para recurso e campo a campo de OBX de HL7 v2 ORU^R01 para FHIR R4, as armadilhas que quebram integrações e um conversor que pode chamar via HTTPS.

Source: https://developers.anpheros.com/pt/guides/hl7-v2-to-fhir-mapping

**Mapear HL7 v2 para FHIR significa transformar cada segmento de uma mensagem v2 delimitada por pipe em recursos FHIR R4: PID num Paciente, OBR num DiagnosticReport (ou ServiceRequest), cada OBX num Observation, com códigos, unidades, intervalos e tempos transportados campo a campo.** A HL7 publica um [guia de implementação V2-para-FHIR](https://hl7.org/fhir/uv/v2mappings/) oficial com mapas de conceitos para os segmentos comuns. Esta página fornece o mapeamento prático para resultados de laboratório (ORU^R01), as armadilhas que quebram integrações reais e um conversor que pode chamar via HTTPS: o conector de laboratório Anpheros.

<!-- visual:v2map-flow -->

## Segmento para recurso

| Segmento HL7 v2 | O que transporta | Recurso FHIR R4 | No conector de laboratório Anpheros |
|---|---|---|---|
| MSH | Separadores, sistema remetente, tipo de mensagem, ID da mensagem | `MessageHeader` (ou provenance) | Separadores lidos do MSH; tipo verificado para ORU^R01; ID da mensagem mantido para rastreabilidade |
| PID | Identificadores do paciente, nome, data de nascimento, sexo | `Patient` | Não utilizado: o paciente é o da URL do pedido, pelo que uma mensagem não pode ser escrita no registo errado |
| PV1 | Visita | `Encounter` | Não utilizado |
| ORC / OBR | Pedido e relatório: ID do preenchedor/colocador, data | `ServiceRequest`, `DiagnosticReport` | OBR-3 (ou OBR-2) é o ID do relatório, OBR-7 a data padrão |
| OBX | Um resultado | `Observation` | Uma Observação de laboratório por OBX |
| NTE | Nota de texto livre | `Observation.note` | Não utilizado |

## Campo OBX campo a campo

| Campo OBX | Elemento FHIR Observation | Notas |
|---|---|---|
| OBX-2 tipo de valor (NM, SN, ST, CWE) | choice of `value[x]` | NM e SN tornam-se `valueQuantity`; texto permanece texto |
| OBX-3 identificador `code^text^system` | `code.coding` | `LN` em OBX-3.3 significa LOINC; outros sistemas são o código local do laboratório |
| OBX-5 valor, OBX-6 unidade | `valueQuantity.value`, `.unit` / `.code` (UCUM) | `<5` e `6,4` devem ser analisados deliberadamente |
| OBX-7 intervalo de referência | `referenceRange.low` / `.high` | `3.5-5.1`, `<200`, `>40` |
| OBX-8 flag de anomalia | `interpretation` | H, L, HH, LL, A, N |
| OBX-11 estado do resultado | `status` | F → final, C → alterado, P → preliminar, I → registado |
| OBX-14 hora da observação | `effectiveDateTime` | os tempos v2 frequentemente não têm fuso horário; FHIR requer um |

## Converter uma mensagem com um pedido

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @oru_r01.hl7
```

A resposta lista quantas Observações foram criadas, quantas foram ignoradas por já terem sido importadas, quais marcadores não puderam ser mapeados e as novas Observações com os seus códigos. Cada uma recebe um identificador estável derivado do relatório, do teste, da hora e do valor, pelo que um laboratório que reenvie a mesma mensagem não cria duplicados.

## Armadilhas que quebram integrações reais

1. **Fusos horários.** `20261002074500` não tem offset; decida explicitamente a zona do remetente.
2. **Códigos locais.** Mantenha o código próprio do laboratório quando não houver LOINC; nunca o elimine.
3. **Reenvios.** Sem um identificador estável por resultado, as tentativas tornam-se duplicados.
4. **Correções.** OBX-11 `C` é uma correção; decida se substitui ou adiciona, e marque o resultado antigo.
5. **Valores não numéricos.** `positive`, `<5`, `6,4` necessitam de regras explícitas, não de uma suposição.

## O que o conector não faz

Aceita resultados laboratoriais ORU^R01 através de HTTPS. Não recebe mensagens ADT ou de ordens, não comunica via MLLP sobre TCP (um motor de interface à frente pode encaminhar), não cria um DiagnosticReport, e não faz a correspondência de pacientes a partir do PID.

## Perguntas frequentes

### Como se mapeia HL7 v2 para FHIR?
Segmento a segmento: PID para Patient, PV1 para Encounter, ORC/OBR para ServiceRequest e DiagnosticReport, OBX para Observation, NTE para notes. O guia de implementação V2-to-FHIR da HL7 define os mapeamentos de conceitos a nível de campo.

### Existe um conversor HL7 v2 para FHIR?
Sim. Motores de interface e bibliotecas de código aberto convertem mensagens; para resultados de laboratório, o conector de laboratório Anpheros converte uma mensagem ORU^R01 em FHIR R4 Observations num único pedido HTTPS e armazena-os no registo do paciente.

### Que tipos de mensagens HL7 v2 o Anpheros aceita?
ORU^R01 resultados de laboratório. Uma mensagem de outro tipo recebe um aviso, e apenas os seus segmentos OBX são lidos; ADT, ordens e outras mensagens não são suportadas.

### Como são representadas as bandeiras anormais do HL7 v2 em FHIR?
OBX-8 torna-se `Observation.interpretation` utilizando os códigos HL7 ObservationInterpretation (H, L, HH, LL, A, N).

<!-- visual:cta-v2map -->

## Relacionado

- [API de resultados de laboratório: HL7 v2, FHIR e LOINC](https://developers.anpheros.com/pt/guides/lab-results-api)
- [FHIR vs HL7 v2: diferenças práticas](https://developers.anpheros.com/pt/guides/fhir-vs-hl7-v2)
- [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir)
- [HL7 v2 e FHIR para painéis clínicos](https://developers.anpheros.com/pt/guides/clinical-dashboard-hl7-fhir)
- [Conector de laboratório](https://developers.anpheros.com/pt/guides/lab-connector)