Toolkit FHIR R4 para o ecossistema de saúde brasileiro — definições de biomarcadores, faixas de referência, calculadoras clínicas, normalização de aliases e cliente RNDS.

Documentação completa e contexto do projeto em fhir-brasil.dev.br.

O sistema de saúde brasileiro opera como redes paralelas com troca mínima de dados — laboratórios privados entregam PDFs sem padrão, laboratórios do SUS usam sistemas internos, e nenhum enxerga o outro. O fhir-brasil fornece a infraestrutura de código aberto para resolver essa fragmentação via FHIR R4:

• 180+ biomarcadores com códigos LOINC, nomes em pt-BR/en-US, categorias e unidades UCUM
• 180+ faixas de referência com variantes por sexo/idade, baseadas em diretrizes SBPC/ML, SBC e SBD
• Normalização de aliases — cada laboratório usa nomes diferentes para o mesmo exame; normalizeCode('colesterol HDL') retorna 'HDL'
• Calculadoras clínicas — PhenoAge (idade biológica), BrDMrisc (risco de diabetes), HOMA-IR, VLDL, IMC
• Utilitários OCR — ancoragem de texto para extração de biomarcadores de PDFs de resultados de laboratório
• Cliente RNDS — cliente HTTP para a Rede Nacional de Dados em Saúde (DATASUS), com autenticação mTLS e zero dependências externas

580+ testes automatizados, cobertura acima de 80%, revisão contínua de faixas de referência.

# Core — tipos, biomarcadores, faixas de referência, conversores
npm install @precisa-saude/fhir

# Calculadoras clínicas (PhenoAge, BrDMrisc, derivados)
npm install @precisa-saude/fhir-calculators

# Utilitários OCR
npm install @precisa-saude/fhir-ocr-utils

# Cliente RNDS (Rede Nacional de Dados em Saúde)
npm install @precisa-saude/fhir-rnds

import { normalizeCode } from '@precisa-saude/fhir';

normalizeCode('colesterol HDL'); // → 'HDL'
normalizeCode('Hemoglobina glicada'); // → 'HbA1c'
normalizeCode('TSH ultrassensível'); // → 'TSH'

import { getReferenceRange } from '@precisa-saude/fhir';

const range = getReferenceRange('Cholesterol');
// → { min: 0, max: 190, optimalMax: 190, unit: 'mg/dL', ... }

const rangeForUser = getReferenceRange('HDL', { sex: 'F', age: 45 });
// → Faixa ajustada para mulher de 45 anos

import { labResultToFHIRBundle } from '@precisa-saude/fhir';

const bundle = labResultToFHIRBundle(report, observations, userProfile);
// → FHIR R4 Bundle com Patient + DiagnosticReport + Observations

import { RNDSClient } from '@precisa-saude/fhir-rnds';

const client = new RNDSClient({
  certificate: './certificado.pfx',
  certificatePassword: process.env.RNDS_CERT_PASSWORD!,
  cnes: '1234567',
  cns: '123456789012345',
  environment: 'homologation',
});

const patient = await client.getPatientByCpf('12345678900');
const result = await client.submitBundle(bundle);

Nota: O Cliente RNDS foi testado contra servidor mock abrangente. Validação contra infraestrutura real do RNDS requer certificado ICP-Brasil e ainda não foi realizada. Veja detalhes no README do pacote.

import { phenoage } from '@precisa-saude/fhir-calculators';

const result = phenoage.calculatePhenoAge({
  chronologicalAge: 45,
  albumin: 42,
  creatinine: 80,
  glucose: 5.2,
  crp: 1.5,
  lymphocytePercent: 30,
  mcv: 88,
  rdw: 13,
  alkalinePhosphatase: 70,
  wbc: 6.5,
});
// → { phenoAge: 42.3, ageDifference: -2.7, ... }

Os pacotes core e ocr-utils incluem ferramentas de linha de comando — zero dependências externas. Todas suportam --json para saída estruturada e --help para detalhes.

fhir-bio lookup ApoB --json          # Buscar biomarcador por código
fhir-bio range Glucose --sex F --json # Faixa de referência
fhir-bio units Creatinine --json      # Informações de unidade
fhir-bio lookup-loinc 718-7           # Buscar por código LOINC
fhir-bio list                         # Listar todos os biomarcadores
fhir-bio categories                   # Listar por categoria
fhir-bio convert resultado.json       # Converter JSON para FHIR Bundle
fhir-bio validate bundle.json         # Validar recurso FHIR
fhir-bio import bundle.json           # Importar Bundle e extrair observações
fhir-bio loinc-map                    # Tabela de mapeamento LOINC ↔ código

echo "Hemoglobina 14.5 g/dL Glicose 99 mg/dL TSH 2.5 mUI/L" | fhir-ocr find --json
echo "Hemoglobina 14.5 g/dL Glicose 99 mg/dL" | fhir-ocr codes --json

• FHIR R4 — Todos os recursos seguem o padrão HL7 FHIR R4
• LOINC — Códigos LOINC verificados para interoperabilidade
• SBPC/ML — Faixas de referência baseadas nas diretrizes brasileiras
• UCUM — Unidades no formato Unified Code for Units of Measure
• TUSS/TISS — Terminologias ANS para saúde suplementar
• CID-10 pt-BR — Classificação Internacional de Doenças (tradução DATASUS)
• IBGE/CNES — Códigos de município e tipos de estabelecimento de saúde

• @precisa-saude/fhir — Core: tipos FHIR R4, biomarcadores, faixas de referência, conversores
• @precisa-saude/fhir-calculators — Calculadoras: PhenoAge, BrDMrisc, derivados
• @precisa-saude/fhir-ocr-utils — Utilitários OCR: ancoragem de biomarcadores em texto
• @precisa-saude/fhir-rnds — Cliente RNDS: autenticação mTLS, submissão de bundles
• Implementation Guide FHIR — perfis BRPatient, BRLabObservation, BRDiagnosticReport via SUSHI
• Terminologias brasileiras — TUSS, TISS, CID-10, SUS raça/cor, IBGE, CNES
• Helpers de identificadores brasileiros (CPF, CNS)
• Integração com perfis RNDS (REL, RAC, SA, RIA)

Veja CONTRIBUTING.md para detalhes sobre como contribuir.

Histórico de versões em CHANGELOG.md.

Este software é fornecido para fins informativos e educacionais. Não substitui aconselhamento médico profissional. Veja DISCLAIMER.md.

Apache License 2.0

Mantido por Precisa Saúde