Pular para o conteúdo principal

Simulador

O Simulador é uma cópia reduzida do HubSaúde que roda na sua máquina. Ele responde como o ambiente real, inclusive nas exigências de segurança, o que permite testar autenticação e envio de ponta a ponta sem depender de credenciais de produção. Quem instala e controla é o HubSaúde CLI.

aviso

Os dados não sobrevivem ao reinício. O Simulador guarda tudo apenas em memória, então parar e subir de novo devolve o ambiente limpo, inclusive os sistemas cadastrados. Ele escuta em HTTPS na porta 8443.

Ciclo de vida​

hubsaude sim start
hubsaude sim status
hubsaude sim logs -f
hubsaude sim stop

Com o Simulador em execução, a página https://localhost:8443 apresenta um resumo do ambiente. A porta pode ser alterada com a variável HUBSAUDE_SIMULADOR_PORT. Veja as variáveis de ambiente.

Preparar seu sistema para o Simulador​

Assim como na produção, o Simulador só emite autorização para sistemas previamente cadastrados. A diferença é que o cadastro é feito por você mesmo, em poucos minutos, com um certificado de teste. Não use o certificado ICP-Brasil da instituição nem sua chave privada no Simulador.

1. Gerar um certificado de teste​

Crie um par de chave e certificado próprio para os testes. Escolha a ferramenta disponível no seu computador:

openssl req -x509 -newkey rsa:2048 -keyout client-key.pem \
  -out client-cert.pem -days 365 -nodes \
  -subj "/CN=meu-sistema/O=MinhaInstituicao/C=BR"

O arquivo client-cert.pem é a parte pública, usada no cadastro. A chave fica em client-key.pem (OpenSSL) ou dentro de client-keystore.p12 (keytool).

2. Cadastrar o sistema​

Informe um identificador para o sistema, o certificado de teste e as permissões desejadas. O identificador faz o papel do client_id que, na produção, é entregue pelo credenciamento.

curl -k -X POST https://localhost:8443/clients/register \
  -F "client_id=meu-sistema" \
  -F "certificate=@client-cert.pem" \
  -F "allowed_scopes=system/Patient.rs system/Observation.rs"

A opção -k aceita o certificado próprio do Simulador, que não é emitido por uma autoridade reconhecida. No Windows, use curl.exe no lugar de curl para evitar o atalho do PowerShell com o mesmo nome.

3. Confiar no certificado do Simulador​

Bibliotecas e aplicações recusam conexões com servidores cujo certificado não reconhecem. Baixe o certificado do Simulador e informe-o ao seu sistema:

curl -k https://localhost:8443/certs/simulador-server.pem -o simulador-server.pem

4. Apontar o SDK para o Simulador​

Nos SDKs oficiais, informe o endereço do Simulador como base FHIR e o certificado baixado como âncora de confiança. A descoberta dos demais endereços é automática.

LinguagemEndereço do SimuladorCertificado do Simulador
Python.fhir_base("https://localhost:8443").server_trust_anchor("simulador-server.pem")
Java.fhirBase("https://localhost:8443").serverTrustAnchor(Path.of("simulador-server.pem"))
TypeScriptfhirBase: "https://localhost:8443"serverTrustAnchor: "simulador-server.pem"
C#.FhirBase("https://localhost:8443").ServerTrustAnchor("simulador-server.pem")

Use também o client_id cadastrado, a chave e o certificado de teste gerados no primeiro passo. O exemplo completo, com a passagem para a produção e os problemas mais comuns, está na seção Testar com o Simulador de cada SDK: Python, Java, TypeScript e C#. A âncora de confiança serve apenas para testes locais: em produção, o certificado do HubSaúde já é reconhecido automaticamente.

Gerenciar o cadastro​

# consultar os dados de um sistema cadastrado
curl -k https://localhost:8443/clients/meu-sistema

# remover o cadastro
curl -k -X DELETE https://localhost:8443/clients/meu-sistema

O que o Simulador reproduz​

Não se trata de uma versão simplificada: o Simulador reproduz a mesma mecânica descrita nas páginas de fluxo.

Descoberta​

Os mesmos endereços de descoberta que os SDKs consultam para localizar o servidor de autorização: /.well-known/smart-configuration, /metadata e /cds-services.

Emissão de token​

Exige certificado de cliente e prende o token emitido a ele, exatamente como a produção faz. Veja Cache e mTLS.

Envio de recursos​

Os endereços /fhir/* respondendo no mesmo modelo de envio em duas etapas. Veja como funciona o envio.

Diferenças em relação à produção​

AspectoSimuladorProdução
Cadastro do sistemaFeito por você, pelo endereço /clients/registerFeito pelo credenciamento no Ganesha
Certificado do clienteQualquer certificado, inclusive de testeCertificado ICP-Brasil válido da instituição
Conferência dos registrosApenas a estrutura do JSON FHIRRegras completas dos Guias de Implementação
DadosEm memória, apagados ao reiniciarPersistidos

Como o Simulador confere apenas a estrutura, um registro aceito por ele ainda pode ser recusado na produção. Confira sempre os registros no Validador antes de enviá-los.

Na prática

Usar a interface do Simulador​

Depois de hubsaude sim start, abra https://localhost:8443 no navegador (aceite o certificado autoassinado na primeira visita). Tudo fica numa única página de referência: o menu superior salta para cada bloco de endpoints e, dentro de cada card, Exemplos traz comandos prontos para copiar.

Use a interface em conjunto com os passos Preparar seu sistema para o Simulador acima. O diagrama do fluxo indica a ordem; os cards detalham cada chamada. Se preferir ir direto pelo SDK, os endereços são os mesmos descritos aqui.

Topo e menu

Confira se o Simulador responde: o indicador em execução (verde) confirma que o processo está no ar. O chip testes / homologação deixa claro que não é produção.

O menu é o mapa da página — clique em Fluxo, Gerar Cert., Clientes e assim por diante, ou role até a seção. Cada item corresponde a uma etapa da integração local.

Cabeçalho do Simulador com o brasão, o título HubSaúde — Simulador, o indicador em execução, o chip de ambiente testes / homologação e o menu das seções

Fluxo (visão geral)

Comece por aqui para ver a sequência completa antes de executar qualquer comando:

  1. Gerar certificado de teste
  2. Registrar o cliente (POST /clients/register)
  3. Gerar a assertion (POST /auth/client-assertion)
  4. Obter o token com mTLS (POST /auth/token)
  5. Chamar FHIR com Bearer token

O banner no topo repete o endereço base (https://localhost:8443) e o link para baixar o certificado do servidor — o mesmo arquivo do passo 3 desta página.

Banner de HTTPS em localhost:8443 e o fluxo SMART Backend Services em cinco passos

Gerar certificado (passo 1)

Antes de cadastrar o sistema, você precisa de client-cert.pem (público) e client-key.pem (privada). Os comandos da seção Gerar Cert. espelham o passo 1 desta página; abra Exemplos → OpenSSL, copie e adapte o -subj ao nome do seu sistema.

Use o card Verificar o certificado gerado para conferir validade e fingerprint antes do registro. Só o .pem público vai em /clients/register; a chave privada entra depois, no mTLS de /auth/token.

Seção Gerar Certificado do Cliente, com o aviso sobre o arquivo .pem público e os exemplos OpenSSL abertos para gerar e verificar o certificado

Descoberta (consulta opcional)

Estes três GET são públicos: servem para inspecionar o ambiente ou depurar a descoberta que o SDK já faz sozinho ao apontar para https://localhost:8443.

  • /.well-known/smart-configuration — endereços de token e capacidades SMART
  • /metadata — CapabilityStatement FHIR R4
  • /cds-services — serviços CDS Hooks disponíveis

Expanda Exemplos → cURL em cada card e execute no terminal (com -k, como nos exemplos desta página).

Seção Descoberta e Metadados, com os GET públicos e os exemplos cURL de /.well-known/smart-configuration, /metadata e /cds-services

Certificados do Simulador (JWKS)

Diferente do certificado do seu cliente (passo 1), esta seção trata das chaves do próprio Simulador usadas para assinar access tokens.

  • GET /certs — JWKS para quem valida tokens manualmente
  • POST /certs/rotate — só para testes de rotação de chave; invalida tokens já emitidos

Para confiar no HTTPS do servidor no seu código, use o download em /certs/simulador-server.pem, não este JWKS.

Seção Certificados e JWKS, com GET /certs e POST /certs/rotate e os respectivos exemplos cURL

Clientes (passo 2)

Aqui você faz o equivalente local ao credenciamento: associa um client_id ao certificado de teste e define os escopos permitidos.

  1. Abra Clientes no menu.
  2. No card POST /clients/register, expanda os exemplos (multipart ou JSON).
  3. Substitua my-backend-app, o caminho de client-cert.pem e os escopos pelos seus valores — como no passo 2 acima.
  4. Use GET /clients/{clientId} para conferir o cadastro e DELETE para limpar antes de um novo teste.

Seção Gerenciamento de Clientes, com POST /clients/register, GET e DELETE /clients/clientId e os exemplos cURL abertos

Autenticação (passos 3 e 4)

Com o cliente cadastrado, obtenha o access token:

  1. POST /auth/client-assertion — informe client_id e private_key_pem (conteúdo de client-key.pem). A resposta traz o JWT pronto; o Simulador não guarda sua chave privada.
  2. POST /auth/token — envie o JWT no formulário OAuth e apresente o mesmo par certificado/chave no TLS (--cert / --key no cURL). O distintivo mTLS no card lembra que este passo é obrigatório.

Se receber 401 por certificado, confira se o .pem registrado é exatamente o apresentado no handshake. Veja também Autenticação.

Seção Autenticação SMART Backend Services, com POST /auth/client-assertion, exemplo de resposta e POST /auth/token exigindo mTLS

FHIR (passo 5)

Com o Bearer token, exercise o envio assíncrono descrito em Enviar e conferir:

  1. POST /fhir/{resourceType} — envie o Bundle com Prefer: respond-async e Idempotency-Key; anote o Content-Location / id da Task na resposta 202.
  2. GET /Task/{id} — faça polling até a Task concluir e leia o resultado em Task.output.
  3. PUT, PATCH e DELETE — mesma ideia assíncrona; os cards listam os headers exigidos.

Copie o exemplo de POST /fhir/Bundle e substitua <ACCESS_TOKEN> e @bundle.json pelos seus.

Seção FHIR R4 Resource Server Simulado, com POST /fhir/resourceType, GET /Task/id, PUT/PATCH e DELETE, e os exemplos cURL de envio e polling

Administração (encerrar)

Para parar o processo pela API, use POST /shutdown (exemplo cURL no card). No dia a dia, o equivalente pelo CLI é hubsaude sim stop.

Seção Administração, com POST /shutdown e o exemplo cURL para encerrar o Simulador

Próximos passos​