Pular para o conteúdo principal

Manual de Integração para Sistemas externos

1. Descrição​

Atualmente, o Prontuário Eletrônico e-SUS APS permite configurar sistemas externos por meio do módulo de 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 PEC ou, durante o Atendimento Individual e o Atendimento Odontológico, por meio da aba Sistemas Externos.

2. Cadastro do sistema externo​

  1. O cadastro de sistemas externos está habilitado somente para as instalações que possuam HTTPS configurado.

  2. O cadastro deve ser feito pelo Administrador da Instalação no módulo "Integração > Sistemas externos". Sendo necessário informar os seguintes dados dos integradores:

a: Para 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.

b: Para 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.
  1. Após realizar o cadastro de um sistema externo, será gerada a chave de assinatura, que deve ser utilizada para gerar a chave durante a requisição de acesso ao sistema externo.

O Administrador da Instalação é responsável por fornecer a chave de acesso 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.

3. 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ífi cos. 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:

● CSP

● X-Frame Options

4. 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.

4.1. Exemplo de URL​

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

4.1.2 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.

  1. Timestamp:

● O parâmetro pec_timestamp=1749542182 representa o momento da requisição (segundos);

● O sistema pode estabelecer um critério de validade, por exemplo, considerando válidas apenas requisições numa janela de 30 minutos.

  1. 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 para gerar a assinatura.

4.1.3 Processo de Verificação​

  1. O sistema pega a URL completa e remove tudo após &pec_sign=;
  2. Usa esta URL "limpa" para calcular um novo HMAC;
  3. Compara o HMAC calculado com o recebido no parâmetro pec_sign;
  4. Simultaneamente, verifi ca se o pec_timestamp está dentro de uma 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.

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

function calculateHMAC(req) {
const fullUrl = `${req.protocol}://${req.get("host")}${req.originalUrl}`; //url assinada no PEC é canônica. Pode ser necessário codifi car a url se tiver caracteres especiais.
const urlToSign = fullUrl.split("&pec_sign=")[0];
return {
urlToSign,
signature: crypto
.createHmac("sha256", HMAC_KEY) //HMAC_KEY corresponde a chave obtida junto ao administrador da instalação
.update(urlToSign)
.digest("hex"),
};
}

4.1.4.1 Verificação do Timestamp​

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

5. Parâmetros dinâmicos​

Os parâmetros permitem que o Prontuário Eletrônico e-SUS APS envie informações através da URL para o sistema externo que está sendo acessado.

5.1. 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 como Atendimento)

  2. [documentoProfi ssional]: identifi cador do profissional que está acessando o sistema externo, preferencialmente é enviado o CPF do profissional, caso não exista, é enviado o CNS.

  3. [cnes]: identifi cador do estabelecimento do profi ssional.

5.2. Exemplo de URL​

● O sistema externo deverá disponibilizar a URL para o administrador da instalação utilizando as variáveis, no formato previsto pelo Prontuário Eletrônico e-SUS APS: https://[url_do_sistema_externo]?documento-profissional=[documentoProfi ssional]&documento-cidadao=[documentoCidadao]&cnes-estabelecimento=[cnes]

● Ao acionar a URL, o Prontuário Eletrônico e-SUS APS irá substituir os valores das variáveis pelo efetivo valor da mesma: https://[url_do_sistema_externo]?documento-profissional=27406912030&documento-cidadao=07838480051

Dessa forma, o sistema externo poderá identificar o profissional e cidadão que estão sendo contemplados nessa requisição e direcionar assertivamente para os dados corretos. Importante ressaltar que os dados de segurança sempre serão enviados através da URL. bridge.ufsc.