Pular para conteúdo

IPES Registro Eletrônico de Saúde - Planserv

Apresentação

Este projeto apresenta um conjunto de requisições para as APIs de interoperabilidade da Plataforma Eletrônica da Saúde (iPES) - que implementa a plataforma de interoperabilidade do PLANSERV (RES-Planserv). Conforme disposto na Instrução nº 06/2025, publicada no Diário Oficial do Estado da Bahia em 18 de abril de 2025, os prestadores ou credenciados junto ao PLANSERV deverão integrar seus sistemas ao RES-Planserv. Esta coleção apresenta exemplos relevantes de interoperabilidade com esse serviço e pode ser usada por prestadores, credenciados, bem como por fornecedores de software utilizados por estes, para desenvolver a interoperabilidade entre os seus sistemas e a plataforma Planserv.

As APIs implementam um serviço de Registro Eletrônico de Saúde (RES) longitudinal e compartilhável baseado no padrão HL7 FHIR (https://hl7.org/fhir/R4), com restrições adicionais impostas pelos perfis FHIR Nacionais, especialmente aqueles definidos pelo perfil FHIR BR-CORE (https://br-core-ig.web.app/) e pelos perfis utilizados pela Rede Nacional de Dados em Saúde (https://simplifier.net/RedeNacionaldeDadosemSaude).

Segurança da API

As APIs são disponibilizadas, em ambiente de desenvolvimento, com segurança em nível de Aplicação baseada no padrão OAUTH2. Para usar as APIs, os interessados deverão solicitar as credenciais de segurança diretamente para a iPES através do e-mail helpdesk@ipes.tech. No e-mail favor indicar que se trata de uma implementação de interoperabilidade com o RES-Planserv, identificar a empresa solicitante e indicar se trata-se de um prestador cedenciado do Planserv ou de um fornecedor de software. É desejável identificar também o produto de software para o qual pretende-se implementar a interoperabilidade. O prazo para emissão de credenciais, após aprovação pelo Planserv, é de até 72h úteis.

As credenciais de segurança obtidas devem ser configuradas como variáveis da coleção (consumerKey, consumerSecret e oidSistemaOrigem).

O token de aplicação - que permite acessar as funcionalidades da API - pode ser gerado usando a requisição "token".

Nota: essa requisição deverá ser realizada uma única vez a cada 3600 segundos, i.e. 1h.

Sobre o uso das APIs desta coleção

As APIs disponibilizadas estão conectadas a um ambiente de desenvolvimento, portanto, é possível que haja instabilidades no funcionamento das APIs (ainda que isso não seja comum).

Os dados presentes nesse ambiente são tipicamente dados artificiais, o que minimiza o risco de acessos não autorizados. Entretanto, a plataforma tem várias conexões com sistemas produtivos, em especial, o sistema do Cartão Nacional de Saúde (CNS) do Ministério da Saúde. Assim, é possível que alguns dados sejam dados reais - apenas na medida do necessário para a plataforma funcionar.

Para utilizar as APIs, é necessário configurar o CPF do paciente (cpfPaciente) nas variáveis da coleção (aba Variables). Utilizar apenas números (sem qualquer tipo de separadores, como . ou -). Utilizar apenas CPF de individuos que autorizem o uso de seus dados, recomenda-se que utilize CPF dos próprios integrantes da equipe de desenvolvimento. Em especial, os dados demográficos do indivíduo identificado pelo CPF informado, serão coletados a partir do serviço do CNS. Essa é uma funcionalidade intrinseca da plataforma e como o ambiente é usado em outros cenários (não é exclusivo para o Planserv) adotamos o uso de CPFs válido apenas.

Coleção RES-Planserv

Nesta coleção, são exemplificados os cenários de interoperabilidade para envio de informações ao RES-Planserv (API EHRPoster, rota https://dev.ipes.tech/ehrposter/fhir) e a recuperação dessas informações a partir dos serviços do RES (API EHRRunner, rota https://dev.ipes.tech/ehrrunner/fhir).

Esta coleção contém exemplos de envio de informações referentes aos atendimentos de pacientes do Planserv, incluindo:

  • Registro de Atendimento Clínico (RAC): resumo atendimentos clínicos ambulatoriais, conforme modelo de informação publicado na Portaria SAE/MS nº 234, de 18 de julho de 2022, que institui o Modelo de Informação para Registro de Atendimento Clínico (RAC) no âmbito do Ministério da Saúde, disponível em https://bvsms.saude.gov.br/bvs/saudelegis/saes/2022/prt0234_20_07_2022.html.

  • Sumário de Alta (SA): sumário de alta hospitalar, conforme modelo de informação publicado na Portaria SAES nº 701, de 29 de setembro de 2022, disponível em https://bvsms.saude.gov.br/bvs/saudelegis/Saes/2022/prt0701_19_10_2022.html. Esta portaria estabelece o modelo de informação para o Sumário de Alta, que é um documento clínico que resume as principais informações sobre o paciente ao receber alta de um estabelecimento de saúde.

As informações do RAC e do SA devem ser codificadas como um FHIR document (https://hl7.org/fhir/R4/documents.html). Os modelos computacionais suportados para esses documentos devem seguir a um dos seguintes perfis:

Para se criar um novo RAC ou um SA na plataforma, é necessário configurar um valor apropriado para a variável "idSistemaOrigem". Este valor deve ser utilizado como parte do campo "identifier" do recurso Composition do documento FHIR, representando o identificador único do documento gerado pelo sistema de origem. Requisições sucessivas com o mesmo valor para essa variável serão interpretadas como "atualizações" do resultado de exame, possibilitando, portanto, a atualização de resultados e laudos. Portanto, é necessário especificar um valor diferente para essa variável para cada novo documento que se deseja criar. Utilize uma string sem caracteres especiais de até 24 dígitos.

Adicionalmente, é necessário configurar o identificador do estabelecimento de saúde onde o documento foi gerado, que deve utilizar o número do Cadastro Nacional de Estabelecimentos de Saúde (CNES). Este valor deve ser informado na variável cnesExecutor, que deve ser configurada na aba Variables da coleção, assim como as demais variáveis mencionadas anteriormente.

A recuperação de registros de um paciente contidos no RES-Planserv é exemplificada nas seguintes operações:

  1. Bundle: recupera todos os documentos (tipicamente, RAC ou SA) disponíveis para o paciente no RES;
  2. Patient Summary: recupera um conjunto de informações clínicas extraídas e processadas a partir de envios de informações de atendimentos anteriores, em um formato analítico denominado Patient Summary do RES.
  3. Timeline: recupera a lista de contatos assistenciais disponíveis para o paciente do RES.

Nota-se que caso haja registros clínicos para o paciente enviados por múltiplos sistemas de origem, esses serão integralmente interoperados pela plataforma, permitindo que o RES seja formado longitudinalmente (registros de diferentes serviços de saúde) e compartilhado integralmente (registros agrupados de todos os serviços de saúde que interoperam com a plataforma).

Após o uso adequado das APIs e o desenvolvimento da integração do sistema próprio com a plataforma, em ambiente de desenvolvimento, deverá ocorrer uma homologação com o time da iPES e, posteriormente, a emissão de credenciais definitivas para acesso ao ambiente de produção da plataforma.

A sequência de uso das APIs (após configurar o CPF do paciente) recomendada consiste em:

  1. token (geração do token OAUTH2 para acesso às APIs);

  2. RAC ou SA (com ou sem modificações): Criar um ou mais RAC ou SA para o paciente;

  3. Bundle: Recuperar os documentos gerados para os pacientes (RAC e SA).

  4. Patient Summary (operation) ou Patient Summary (personalizado): Obter o Patient Summary para o paciente (gerado a partir dos RACs enviados).

  5. Timeline (Encounter): obter a lista de atendimentos (Encounter) para o paciente (gerados a partir dos RACs enviados).

  6. Visualizar os dados na aplicação (necessário login no Gov.Br). https://portal.planservdev.ipes.tech.