Pular para conteúdo

IPES Resultados de Exames Laboratoriais e de Exames de Imagem

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. Essa 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 esses, 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 credenciado do Planserv ou de um fornecedor de software. É desejável identificar também o produto de software para o qual pretende-se imple,entar 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.

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 do serviços do RES (API EHRRunner, rota https://dev.ipes.tech/ehrrunner/fhir).

Coleção RES-Planserv Resultados de Exames Laboratoriais e de Exames de Imagem

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

  • Resultado de exames laboratoriais: usado para envio de resultados de exames laboratoriais, em formato visualizável por pacientes e profissionais (tipicamente, formato PDF). Tipicamente, um documento com resultados de exames laboratoriais poder conter múltiplos exames (painéis ou analitos), portanto esse é o cenário suportado.

  • Resultado de exame de imagem: usado para envio de laudos de exames de imagens, em formato visualizável por pacientes e profissionais (tipicamente, em formato PDF). Tipicamente, um laudo de um resultados de exame de imagem se refere a um único exame realizado, sendo sugerido que cada laudo seja enviado em uma transação separada.

As informações são enviadas, encapsuladas em um recurso Bundle, do tipo “transaction” (“type” = “transaction”). A mensagem deve ser codificada em representação JSON (Content-Type application/fhir+json; Accept application/fhir+json). Os modelos computacionais suportados para esses envios devem seguir um dos seguintes perfis:

  • Resultado de exames laboratoriais: deve conter um Bundle transaction, contendo três entradas (entry) com os seguintes recursos:

(1) DiagnosticReport - contém os elementos de dados do resultado de exames;

(2) ServiceRequest - contém os elementos de dados do pedido médico;

(3) Binary - contém o documento (PDF) com o resultado de exame, codificado em formato BASE64.

  • Resultado de exame de imagem: deve conter um Bundle transaction, contendo três entradas (entry) com os seguintes recursos:

(1) DiagnosticReport - contém os elementos de dados do resultado de exame;

(2) ServiceRequest - contém os elementos de dados do pedido médico;

(3) Binary - contém o documento (PDF) com o laudo do exame, codificado em formato BASE64.

Para se criar um novo Resultado de Exame (laboratório ou imagem) na plataforma, é necessário configurar um valor apropriado para a variável "idSistemaOrigem" - utilizada como valor da propriedade "identifier" do recurso DiagnosticReport da transação. 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. Utilizar uma string sem carateres especiais de até 24 digitos.

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), configurado na variável {{cnesExecutor}};

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

  • Lista de resultados de exames de laboratório: recupera a lista de resultados de exames laboratoriais disponíveis para o paciente no RES.

  • Lista de resultados de exames de imagem: recupera a lista de laudos de exames de imagem disponíveis para o paciente no 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 sapude) 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. Resultado de exames de laboratório ou Resultado de exame de imagem: Criar um ou mais resultados de exame para o paciente. Cada resultado de exame deverá ser enviado através de uma requisição própria - resultados de exame diferentes deverão ter valores diferentes para o identifier (variável idSistemaOrigem);

  3. Recuperar os registros gerados (Lista de resultados de exames de laboratório ou Lista de resultados de exames de imagem).

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