Pular para o conteúdo principal

Integração com Sistemas Externos no Prontuário Eletrônico e-SUS APS

Descrição​

O Prontuário Eletrônico e-SUS APS permite configurar sistemas externos por meio do módulo Integração, disponível para o Administrador da Instalação.

Após a configuração, o acesso ao sistema externo será disponibilizado de acordo com o local definido no momento do cadastro. Ele poderá ser acessado pelo menu lateral do Prontuário Eletrônico e-SUS APS ou, durante o Atendimento Individual e o Atendimento Odontológico, por meio da aba Sistemas Externos.

Cadastro do sistema externo​

  1. O cadastro de sistemas externos está habilitado somente para as instalações que possuam HTTPS configurado (ver manual Habilitação do HTTPS).

  2. O cadastro deve ser feito pelo Administrador da Instalação no módulo Integração > Sistemas externos, informando os seguintes dados dos integradores:

    a) Para o cadastro de Pessoa física, o registro deve conter as seguintes informações da pessoa que será responsável pela integração:

    • URL de acesso ao sistema externo;
    • Nome;
    • CPF;
    • E-mail;
    • Nome do sistema;
    • Local de acesso: menu lateral ou Atendimento (Atendimento Individual e Atendimento Odontológico).

    b) Para o cadastro de Pessoa jurídica, o registro deve conter as seguintes informações da pessoa que será responsável pela integração:

    • URL de acesso ao sistema externo;
    • Nome;
    • CNPJ;
    • E-mail;
    • Nome do sistema;
    • Local de acesso: menu lateral ou Atendimento (Atendimento Individual e Atendimento Odontológico).

  3. Após o cadastro de um sistema externo, será gerada a chave de assinatura, que o sistema externo utilizará para validar as requisições de acesso enviadas pelo Prontuário Eletrônico e-SUS APS (ver item Chave de assinatura).

O Administrador da Instalação é responsável por fornecer a chave de assinatura aos responsáveis pelos sistemas externos.

atenção

Uma chave gerada anteriormente não pode ser recuperada. Caso ela seja perdida, será necessário realizar um novo cadastro para gerar uma nova chave.

Sistemas habilitados para iFrame​

Não é possível carregar o iFrame no Prontuário Eletrônico e-SUS APS caso o sistema configurado possua configurações que restrinjam o uso do conteúdo, como, por exemplo, quando o servidor envia cabeçalhos de segurança específicos. Os cabeçalhos que podem causar essa restrição incluem:

  • Content-Security-Policy: se configurado como frame-ancestors 'none', impede que qualquer site carregue o conteúdo em um iFrame;

  • X-Frame-Options: definido com valores como SAMEORIGIN ou DENY, esse cabeçalho restringe a exibição do conteúdo em iFrames. O valor SAMEORIGIN permite que o conteúdo seja exibido apenas em páginas do mesmo domínio, enquanto DENY bloqueia completamente a exibição em iFrames.

Para mais informações:

Chave de assinatura​

Durante a configuração de um sistema externo, o Prontuário Eletrônico e-SUS APS gera uma chave de assinatura. Essa chave permite que o sistema externo confirme que a solicitação de acesso foi realmente enviada pelo Prontuário Eletrônico e-SUS APS.

Para obter a chave de assinatura, o responsável pelo sistema externo deverá entrar em contato com o Administrador da Instalação do município.

Exemplo de URL assinada​

https://localhost:4000/iframe?documento-profissional=12345&documento-cidadao=67890&pec_timestamp=1749542182&pec_sign=9e6c598297ba33f47cfccafa4869ec70428ac3c76b0e037ec08daf96d2616c0f

Como funciona​

  1. Parte base da URL (usada para assinar):

    https://localhost:4000/iframe?documento-profissional=12345&documento-cidadao=67890&pec_timestamp=1749542182

    Esta é a parte que será usada para gerar e verificar a assinatura. Note que ela termina no timestamp.

  2. Timestamp:

    • O parâmetro pec_timestamp=1749542182 representa o momento da requisição (em segundos);
    • O sistema externo pode estabelecer um critério de validade, por exemplo, considerando válidas apenas as requisições feitas em uma janela de 30 minutos.

  3. Assinatura:

    • O parâmetro pec_sign=9e6c...6c0f contém a assinatura HMAC-SHA256 da URL;
    • A assinatura é calculada usando toda a URL até o timestamp (inclusive);
    • É usado o algoritmo HMAC-SHA256 com a chave secreta (chave de assinatura) para gerar a assinatura.

Processo de verificação​

  1. O sistema externo pega a URL completa e remove tudo o que estiver após &pec_sign=;
  2. Usa essa URL "limpa" para calcular um novo HMAC;
  3. Compara o HMAC calculado com o recebido no parâmetro pec_sign;
  4. Simultaneamente, verifica se o pec_timestamp está dentro da janela esperada.

A requisição só é considerada válida se:

  • a parte da URL até o timestamp gerar a mesma assinatura que foi recebida;
  • o timestamp estiver dentro da janela estabelecida.

Exemplo de cálculo do HMAC (JavaScript/Node/Express)​

// O exemplo utiliza o módulo crypto do Node.js
const crypto = require("crypto");

// HMAC_KEY deve conter a chave de assinatura fornecida pelo Administrador da Instalação
const HMAC_KEY = process.env.HMAC_KEY;

function calculateHMAC(req) {
  // A URL assinada no PEC é canônica. Pode ser necessário codificar a URL se ela tiver caracteres especiais.
  const fullUrl = `${req.protocol}://${req.get("host")}${req.originalUrl}`;
  const urlToSign = fullUrl.split("&pec_sign=")[0];
  return {
    urlToSign,
    signature: crypto
      .createHmac("sha256", HMAC_KEY)
      .update(urlToSign)
      .digest("hex"),
  };
}

Verificação do timestamp​

function verifyTimestamp(timestamp) {
  const currentTimeInSeconds = Math.floor(Date.now() / 1000);
  const timeDiff = Math.abs(currentTimeInSeconds - Number(timestamp));
  // Permitir diferença de até 30 minutos
  return timeDiff <= 1800;
}

Comparação da assinatura​

Para comparar a assinatura calculada com a recebida, recomenda-se utilizar uma comparação de tempo constante, como a função crypto.timingSafeEqual, que evita ataques baseados no tempo de resposta:

function isValidRequest(req) {
  const { signature } = calculateHMAC(req);
  const received = String(req.query.pec_sign || "");
  const a = Buffer.from(signature, "hex");
  const b = Buffer.from(received, "hex");
  const signatureOk = a.length === b.length && crypto.timingSafeEqual(a, b);
  return signatureOk && verifyTimestamp(req.query.pec_timestamp);
}

Parâmetros dinâmicos​

Os parâmetros permitem que o Prontuário Eletrônico e-SUS APS envie informações, por meio da URL, ao sistema externo que está sendo acessado.

Parâmetros disponíveis​

  1. [documentoCidadao]: identificador do cidadão que está sendo atendido pelo profissional. Preferencialmente, é enviado o CPF do cidadão; caso não exista, é enviado o CNS (disponível apenas para sistemas definidos com o local de acesso Atendimento);

  2. [documentoProfissional]: identificador do profissional que está acessando o sistema externo. Preferencialmente, é enviado o CPF do profissional; caso não exista, é enviado o CNS;

  3. [cnes]: identificador do estabelecimento do profissional.

Exemplo de URL com parâmetros​

  • O sistema externo deverá disponibilizar ao Administrador da Instalação a URL com as variáveis, no formato previsto pelo Prontuário Eletrônico e-SUS APS:

    https://[url_do_sistema_externo]?documento-profissional=[documentoProfissional]&documento-cidadao=[documentoCidadao]&cnes-estabelecimento=[cnes]

  • Ao acionar a URL, o Prontuário Eletrônico e-SUS APS substituirá as variáveis pelos seus valores efetivos:

    https://[url_do_sistema_externo]?documento-profissional=27406912030&documento-cidadao=07838480051&cnes-estabelecimento=1234567

Dessa forma, o sistema externo poderá identificar o profissional e o cidadão contemplados nessa requisição e direcionar assertivamente para os dados corretos.

nota

Os parâmetros de segurança (pec_timestamp e pec_sign) são sempre acrescentados ao fim da URL pelo Prontuário Eletrônico e-SUS APS.

2ª versão. Atualizado em 06 de novembro de 2026.