Como Usar APIs de EHR? Guia Completo

TL;DR

As APIs de EHR (Prontuário Eletrônico de Saúde) acessam registros de saúde de pacientes armazenados em sistemas como Epic, Cerner e Athenahealth. A maioria dos EHRs modernos suporta FHIR (Fast Healthcare Interoperability Resources), um formato padrão para dados de saúde. A autenticação usa OAuth 2.0 com extensões SMART on FHIR. Para testes, use Apidog para validar recursos FHIR, testar em sandboxes e garantir que sua integração lida com os dados do paciente corretamente antes de conectar-se a sistemas de produção.

Introdução

Os Prontuários Eletrônicos de Saúde contêm tudo sobre o cuidado do paciente: diagnósticos, medicamentos, resultados de exames, alergias e planos de tratamento. Hospitais, clínicas e sistemas de saúde armazenam esses dados em plataformas de EHR como Epic, Cerner e Athenahealth.

Construir aplicativos de saúde significa conectar-se a esses sistemas. Não se pode pedir aos hospitais para exportar arquivos CSV. Você precisa de APIs. Mas as APIs de saúde são diferentes das APIs web típicas. Elas lidam com informações de saúde protegidas (PHI) e devem cumprir regulamentações como a HIPAA nos EUA.

A boa notícia: a maioria dos fornecedores de EHR agora suporta FHIR, um formato de API padrão. A notícia desafiadora: autenticação, autorização e mapeamento de dados permanecem complexos.

Se você está construindo integrações de saúde, o Apidog o ajuda a testar recursos FHIR, validar estruturas de dados e garantir que seu aplicativo lida com os dados do paciente corretamente. Você pode testar em sandboxes públicas antes de trabalhar com sistemas hospitalares reais.

Teste APIs FHIR com Apidog - grátis

Ao final deste guia, você será capaz de:

Compreender os tipos e a estrutura dos recursos FHIR
Autenticar com SMART on FHIR
Consultar dados demográficos e clínicos de pacientes
Criar e atualizar recursos de pacientes
Testar com sandboxes de EHR

Compreendendo o FHIR

FHIR (Fast Healthcare Interoperability Resources) é o padrão moderno para APIs de saúde. Ele define:

Recursos: Tipos de dados para conceitos de saúde (Paciente, Observação, Medicação)
API REST: Operações padrão em recursos
Formatos: Representações JSON e XML

Estrutura da URL base

https://ehr.example.com/fhir/r4/{resource-type}/{id}

Exemplo:

GET https://ehr.example.com/fhir/r4/Patient/123

Versão FHIR

A maioria dos EHRs usa FHIR R4 (Release 4). Alguns sistemas mais antigos usam DSTU2. Este guia aborda o R4.

Tipos de recursos

Recurso	Propósito
Paciente	Dados demográficos e administrativos
Profissional	Prestadores de serviços de saúde
Organização	Hospitais, clínicas
Observação	Resultados de exames, sinais vitais
MedicationRequest	Prescrições
Condição	Diagnósticos, problemas
Encontro	Visitas, internações
DocumentReference	Documentos clínicos
AlergiaIntolerância	Alergias e reações adversas

Estrutura do recurso FHIR

Exemplo de recurso Paciente

{
  "resourceType": "Patient",
  "id": "123",
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": ["John", "Michael"]
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "line": ["123 Main St"],
      "city": "Boston",
      "state": "MA",
      "postalCode": "02101",
      "country": "USA"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "555-123-4567",
      "use": "home"
    },
    {
      "system": "email",
      "value": "john.smith@example.com"
    }
  ],
  "identifier": [
    {
      "system": "http://hospital.example.org/mrn",
      "value": "MRN-123456"
    }
  ]
}

Exemplo de recurso Observação

{
  "resourceType": "Observation",
  "id": "obs-123",
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "vital-signs",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "8480-6",
        "display": "Pressão arterial sistólica"
      }
    ]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "effectiveDateTime": "2026-03-24T09:30:00Z",
  "valueQuantity": {
    "value": 120,
    "unit": "mmHg",
    "system": "http://unitsofmeasure.org",
    "code": "mm[Hg]"
  }
}

Autenticação com SMART on FHIR

SMART on FHIR estende o OAuth 2.0 para a área da saúde. Ele lida com o contexto do paciente e escopos específicos de EHR.

Fluxo OAuth para acesso ao paciente

Passo 1: Obter URL de autorização

GET https://ehr.example.com/fhir/r4/.well-known/smart-configuration

A resposta inclui:

{
  "authorization_endpoint": "https://ehr.example.com/oauth2/authorize",
  "token_endpoint": "https://ehr.example.com/oauth2/token",
  "scopes_supported": [
    "patient/*.read",
    "patient/*.write",
    "user/*.read",
    "launch/patient"
  ]
}

Passo 2: Redirecionar usuário para autorizar

https://ehr.example.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=patient/*.read&
  state=random_state_value

Passo 3: Trocar código por token

curl -X POST "https://ehr.example.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "patient/*.read",
  "patient": "123"
}

O campo patient fornece o contexto do ID do paciente.

Escopos SMART

Escopo	Acesso
`patient/*.read`	Ler todos os dados do paciente
`patient/Patient.read`	Ler apenas dados demográficos do paciente
`patient/Observation.read`	Ler apenas observações
`user/*.read`	Ler todos os dados para o usuário autorizado
`launch/patient`	EHR lança seu aplicativo com contexto do paciente

Consultando dados do paciente

Obter dados demográficos do paciente

curl -X GET "https://ehr.example.com/fhir/r4/Patient/123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Procurar observações

curl -X GET "https://ehr.example.com/fhir/r4/Observation?patient=123&category=vital-signs" \
  -H "Authorization: Bearer ACCESS_TOKEN"

A resposta é um Bundle:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 5,
  "entry": [
    {
      "resource": { ... Recurso Observação ... }
    }
  ]
}

Parâmetros de busca comuns

# Resultados de laboratório por intervalo de datas
GET /Observation?patient=123&category=laboratory&date=gt2026-01-01

# Código LOINC específico
GET /Observation?patient=123&code=http://loinc.org|8480-6

# Medicamentos
GET /MedicationRequest?patient=123&status=active

# Condições (diagnósticos)
GET /Condition?patient=123&clinical-status=active

# Encontros
GET /Encounter?patient=123&type=AMB

Paginação

Grandes conjuntos de resultados são paginados:

GET /Observation?patient=123&_count=20

A resposta inclui links:

{
  "link": [
    {
      "relation": "next",
      "url": "https://ehr.example.com/fhir/r4/Observation?patient=123&_count=20&page=2"
    }
  ]
}

Criando e atualizando recursos

Criar uma observação

curl -X POST "https://ehr.example.com/fhir/r4/Observation" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Observation",
    "status": "final",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "8480-6",
        "display": "Pressão arterial sistólica"
      }]
    },
    "subject": {
      "reference": "Patient/123"
    },
    "effectiveDateTime": "2026-03-24T09:30:00Z",
    "valueQuantity": {
      "value": 118,
      "unit": "mmHg",
      "system": "http://unitsofmeasure.org",
      "code": "mm[Hg]"
    }
  }'

Atualizar um paciente

curl -X PUT "https://ehr.example.com/fhir/r4/Patient/123" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "id": "123",
    "name": [{
      "family": "Smith",
      "given": ["John", "Michael"]
    }],
    "telecom": [{
      "system": "phone",
      "value": "555-999-8888",
      "use": "home"
    }]
  }'

Especificidades do fornecedor de EHR

Epic

A API FHIR da Epic está disponível na maioria dos grandes hospitais.

URL base: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/
Sandbox: https://fhir.epic.com/test/api/FHIR/R4/
Documentação: https://fhir.epic.com

A Epic exige o registro do aplicativo em seu marketplace de aplicativos para acesso à produção.

Cerner

A Cerner (Oracle Health) usa FHIR padrão com algumas extensões.

URL base: https://fhir-myrecord.cerner.com/r4/{tenant-id}
Sandbox: https://fhir-deprecated.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d
Documentação: https://docs.oracle.com/en/health/health-cerner/

Athenahealth

A Athenahealth fornece APIs FHIR e legadas.

URL base: https://api.platform.athenahealth.com/fhir/r4/{practice-id}
Sandbox: Disponível através do programa de desenvolvedores
Documentação: https://docs.athenahealth.com

Testando com Apidog

APIs de saúde exigem testes cuidadosos. Dados de pacientes são sensíveis.

1. Use sandboxes públicas

Teste em sandboxes FHIR públicas:

# HAPI FHIR (código aberto)
https://hapi.fhir.org/baseR4

# Sandbox SMART Health IT
https://launch.smarthealthit.org

2. Validar recursos FHIR

pm.test('Resource is valid Patient', () => {
  const response = pm.response.json()
  pm.expect(response.resourceType).to.eql('Patient')
  pm.expect(response.id).to.exist
  pm.expect(response.name).to.be.an('array')
})

pm.test('Observation has required fields', () => {
  const resource = pm.response.json()
  pm.expect(resource.status).to.exist
  pm.expect(resource.code).to.exist
  pm.expect(resource.subject).to.exist
})

3. Testar fluxo de autenticação

Salve a configuração SMART como ambiente:

AUTHORIZATION_ENDPOINT: https://ehr.example.com/oauth2/authorize
TOKEN_ENDPOINT: https://ehr.example.com/oauth2/token
CLIENT_ID: seu_client_id
CLIENT_SECRET: seu_client_secret
SCOPE: patient/*.read

Teste APIs FHIR com Apidog - grátis

Considerações de conformidade

HIPAA

Nos EUA, os aplicativos de saúde devem cumprir o HIPAA. Isso afeta:

Transmissão de dados: Use TLS 1.2+
Armazenamento de dados: Criptografar em repouso
Controle de acesso: Registro de auditoria, acesso mínimo necessário
Business Associate Agreement (BAA): Requerido com fornecedores de EHR

Segurança SMART on FHIR

Os tokens expiram (geralmente 1 hora)
Tokens de atualização disponíveis para sessões estendidas
O contexto do paciente está vinculado ao escopo do token
O logout requer revogação do token

Minimização de dados

Solicite apenas os escopos de que precisa:

Bom: patient/Observation.read
Evite: patient/*.read, a menos que seja necessário

Erros comuns e soluções

401 Não autorizado

Causa: Token expirado ou inválido.

Solução: Atualize o token usando o token de atualização da autorização inicial.

403 Proibido

Causa: O escopo não inclui o recurso solicitado.

Solução: Verifique seus escopos. Se precisar de mais acesso, solicite escopos adicionais durante a autorização.

404 Não encontrado

Causa: Paciente ou recurso não existe.

Solução: Verifique o ID do recurso. Certifique-se de que o paciente esteja acessível com o contexto do paciente do seu token atual.

422 Entidade Inprocessável

Causa: Falha na validação do recurso FHIR.

Solução: Verifique os campos e terminologias obrigatórias:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "required",
    "details": {
      "text": "Observation.status é obrigatório"
    }
  }]
}

Alternativas e comparações

Recurso	Epic	Cerner	Athenahealth	OpenEMR
FHIR R4	✓	✓	✓	Parcial
SMART on FHIR	✓	✓	✓	Não
Acesso a Sandbox	✓	✓	Limitado	Auto-hospedagem
Documentação da API	Excelente	Boa	Boa	Básica
Fatia de mercado	Grandes hospitais	Sistemas de saúde	Pequenas clínicas	Código aberto

Epic e Cerner dominam grandes sistemas de saúde. Athenahealth atende clínicas menores. OpenEMR é de código aberto, mas tem suporte limitado a APIs.

Casos de uso no mundo real

Portal do paciente. Um sistema de saúde constrói um portal do paciente que extrai dados da Epic. Pacientes visualizam resultados de exames, medicamentos e próximos agendamentos. O portal usa APIs FHIR com autenticação SMART on FHIR.

Pesquisa clínica. Uma empresa farmacêutica precisa identificar pacientes elegíveis para ensaios clínicos. Eles consultam APIs FHIR em vários sistemas hospitalares para encontrar pacientes que correspondem aos critérios, com o devido gerenciamento de consentimento.

Monitoramento remoto. Uma empresa de telessaúde integra sinais vitais relatados pelo paciente com sistemas de EHR. Observações são criadas via API FHIR e imediatamente visíveis para os clínicos na Epic.

Conclusão

Aqui está o que você aprendeu:

FHIR é o padrão para APIs de saúde
Recursos representam conceitos de saúde como pacientes e observações
SMART on FHIR lida com OAuth com contexto do paciente
Cada fornecedor de EHR tem detalhes de implementação específicos
Teste com sandboxes antes da produção

Seus próximos passos:

Explore a sandbox pública HAPI FHIR
Compreenda os tipos de recursos FHIR para seu caso de uso
Inscreva-se nos programas de desenvolvedores de EHR
Teste com Apidog usando dados de pacientes fictícios
Implemente o tratamento de dados compatível com HIPAA

Teste APIs FHIR com Apidog - grátis

botão

FAQ

Qual a diferença entre FHIR e HL7 v2?HL7 v2 é um padrão de mensagens mais antigo usado em interfaces hospitalares. FHIR é um padrão moderno de API REST. A maioria das novas integrações usa FHIR, mas HL7 v2 ainda é comum em sistemas legados.

Preciso de um BAA para usar APIs de EHR?Sim, se você estiver lidando com PHI. Acordos de Associado Comercial (Business Associate Agreements) são exigidos entre entidades cobertas e associados comerciais. Verifique com a equipe de conformidade do fornecedor de EHR.

Como obtenho acesso à API FHIR da Epic?Registre-se no marketplace App Orchard da Epic. Para testes em sandbox, use a sandbox pública deles. O acesso à produção requer aprovação hospitalar.

O que é um contexto de paciente?Tokens SMART on FHIR incluem um ID de paciente. Suas chamadas de API são limitadas aos dados desse paciente. Isso garante que os aplicativos só possam acessar os dados que o paciente autorizou.

Posso escrever dados em EHRs?Sim, mas com limitações. A maioria dos EHRs permite criar observações e atualizar dados demográficos do paciente. A escrita de diagnósticos ou medicamentos geralmente requer aprovação de suporte à decisão clínica.

Como lido com códigos de terminologia?FHIR usa terminologias padrão:

LOINC para exames laboratoriais e observações
SNOMED CT para conceitos clínicos
CID-10 para diagnósticos
RxNorm para medicamentos

Use esses sistemas ao criar recursos.

E sobre a saúde internacional?FHIR é global. Cada país pode ter guias de implementação. Os EUA usam perfis US Core. Verifique as especificações da sua região.