Conetor de laboratório: como um relatório de laboratório em HL7 v2, CSV ou JSON se torna Observações FHIR num só pedido

Um laboratório tem uma única tarefa numa integração: colocar o relatório no registo do paciente sem retipar, sem perder o intervalo de referência e sem inventar um formato que mais ninguém lê. O conector de laboratório Anpheros recebe o relatório tal como o laboratório já o produz, em HL7 v2, CSV ou JSON, e transforma cada resultado numa Observation FHIR com um código LOINC, uma unidade, um intervalo de referência, uma data e o nome do laboratório como executante. Este guia é o contrato.

Versão técnica para programadores: Conector de laboratório · API de resultados de laboratório em developers.anpheros.com, com pedidos, respostas e limites. Esta página é a versão em linguagem simples.

Um pedido

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        (opcional; registado em Provenance)
Idempotency-Key: <report id>          (opcional; uma nova tentativa devolve a mesma resposta)

A resposta diz o que aconteceu:

{"created": 3, "skipped": 0, "unmapped": ["Marcador muito raro"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org",
                   "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}

Formatos

HL7 v2 ORU^R01, como texto ER7. OBX-3 é o identificador (code^text^LN é LOINC; um código local é mantido como código próprio do laboratório), OBX-5 o valor, OBX-6 a unidade, OBX-7 o intervalo de referência, OBX-8 o indicador de anormalidade (torna-se interpretation), OBX-11 o estado, OBX-14 ou OBR-7 a data. MSH-4 nomeia a unidade emissora, que se torna o executante; OBR-3 e MSH-10 tornam-se o ID do relatório em Provenance. Resultados pendentes, eliminados ou incorretos (I, X, D, W) e segmentos OBX sem valor não se tornam Observações e são nomeados em warnings.

CSV com uma linha de cabeçalho; separadores , ; ou tabulação, vírgula decimal aceite, datas ISO, DD.MM.YYYY ou DD/MM/YYYY. Colunas reconhecidas em romeno ou inglês: marker, value, unit, reference range (70-100, <5, >3.5) ou ref_low/ref_high, date, código LOINC opcional, note. Um CSV não transporta um laboratório, pelo que o executante está em falta, a menos que envie X-Anpheros-Acting-As.

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

JSON quando já tem dados estruturados: {"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, "code": "3016-3"}]}.

Regras de mapeamento que importam

• LOINC quando fornecido, caso contrário por nome. Os nomes são comparados com nomes e sinónimos LOINC em romeno e inglês. Um nome que corresponda a vários conceitos, ou que transporte um qualificador que o conceito não tem (urina, não-HDL, livre, razão), não é adivinhado: mantém o código do laboratório sob urn:anpheros:lab-code e aparece em unmapped, para que possa melhorar o mapeamento do seu lado. Envie códigos LOINC sempre que os tiver.
• Os valores nunca são convertidos. Ureia e nitrogénio ureico são códigos diferentes; LDL direto e LDL calculado são códigos diferentes; glicose do soro e do sangue capilar são códigos diferentes. O conector escolhe o correto a partir do nome e do método, e deixa o número como está.
• Os tempos mantêm a sua zona. Um tempo v2 com um deslocamento é mantido; sem um, é usado o deslocamento de MSH-7 com um aviso; sem nenhum em qualquer lugar, apenas a data é armazenada. Os tempos CSV não transportam zona e são armazenados como datas.
• Idempotente. Envie o mesmo relatório duas vezes com a mesma Idempotency-Key e obterá a mesma resposta e sem duplicados.
• Provenance em cada resultado: o sistema de origem, o ID do relatório e o executante, conforme exigido pelo HL7 Europe Laboratory Report.

O que o paciente vê

Os resultados aparecem no registo da pessoa e, se utilizarem o Anpheros Daily, no seu telemóvel assim que chegam, com o intervalo de referência e a tendência dos relatórios anteriores. Nada para digitalizar, nada para retipar. Se um resultado for anormal, a pessoa vê o indicador; a aplicação não o interpreta.

Testes

A sandbox é gratuita e os pacientes sintéticos já têm histórico laboratorial. Envie um relatório para um deles e leia-o de volta:

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" --data-binary @report.csv
curl "$BASE/fhir/R4/Observation?patient=$PID&category=laboratory&_sort=-date" -H "Authorization: Bearer $KEY"

A especificação completa, incluindo as notas de conformidade do HL7 Europe, está em developers.anpheros.com/guides/lab-connector.

Perguntas frequentes

Temos de alterar o que o nosso LIS produz?

Não. Envie a mensagem ORU^R01 ou a exportação CSV como está. Se puder adicionar códigos LOINC, faça-o; caso contrário, o conector mapeia por nome e informa-o sobre o que não conseguiu mapear.

E quanto aos resultados que não conseguem mapear?

São armazenados com o código próprio do laboratório e o texto exato do relatório, para que nada se perca, e listados em unmapped para que possa adicionar um código LOINC na próxima vez.

Os intervalos de referência e os indicadores de anormalidade são mantidos?

Sim: o intervalo vai para referenceRange, o indicador para interpretation, a unidade é armazenada como UCUM, e o valor nunca é convertido.

Um laboratório pode enviar resultados para um paciente que não criou?

Apenas com o consentimento da pessoa, ou como a organização para a qual o projeto atua com X-Anpheros-Acting-As. Um projeto vê os pacientes que criou; tudo o resto requer uma autorização.

Existe algum custo para a integração?

A sandbox é gratuita. A produção começa em 49 € por mês por organização, com o primeiro mês gratuito; veja preços.