Conheça os serviços

A conexão com a RNDS ocorre por meio de requisições https em conformidade com o padrão FHIR. As requisições devem partir da infraestrutura empregada pelo estabelecimento de saúde e atingir os web services da RNDS.

As requisições estão devidamente documentadas e disponíveis nos web services dos ambientes oferecidos pela RNDS.

O foco aqui é esclarecer como submeter tais requisições. Mesmo que o integrador já possua experiência com requisições https, é sugerida a leitura deste texto com o propósito de ambientação com os serviços oferecidos pela RNDS.

Cenário de prática

A submissão de requisições é comentada com ilustrações que empregam a ferramenta Postman (usada por desenvolvedores para interação com web services). Existem muitas outras opções e pode-se empregar qualquer uma delas.

Os exemplos oferecidos são compatíveis com as expectativas configuradas nos servidores FHIR da RNDS. Ou seja, as requisições ilustram as respostas obtidas dos ambientes oferecidos pela RNDS. De fato, foram experimentadas no ambiente de homologação.

CUIDADO

O ambiente de produção não deve ser empregado com a finalidade de experimentar a integração com os web services da RNDS.

Embora desejável o acesso ao ambiente de homologação para validar o que está sendo produzido, este acesso pode não estar disponível, o que não impede a prática.

RECOMENDAÇÃO

Empregar um servidor FHIR publicamente disponível para experimentação.

Metas

Ao final, espera-se que você saiba:

• As requisições disponíveis.
• Os headers necessários e como montar os valores correspondentes.
• A estrutura do payload para cada requisição.
• Submeter as requisições por meio da ferramenta Postman.
• Interpretar as respostas.
• Experimentar valores diferentes para o payload, headers e parâmetros (URL).
• O fluxo típico da interação com a RNDS usando HTTPS.
• Empregar o certificado digital para obter token de acesso.

Caso siga, compreenda e tenha praticado cada um dos itens abaixo, terá adquirido parte relevante da habilidade necessária para construir o conector.

Pré-requisitos

Conforme ilustrado, a interação com a RNDS depende de várias informações e um arquivo (certificado digital) (destacados em verde). O arquivo adicional é a configuração do Postman (destacado em amarelo), ou seja, uma demanda específica desta ferramenta, ao contrário das demais.

• Informações necessárias:

  • Identificador do solicitante fornecido pela RNDS quando a solicitação de acesso é aprovada. Esta aprovação, além de definir o identificador do solicitante, também autoriza o acesso ao ambiente de homologação.
  • CNES. O CNES do laboratório.
  • CNS de um profissional de saúde lotado no estabelecimento de saúde cujo CNES é fornecido acima. O CNS indica em nome do quem as requisições ao ambiente de homologação serão feitas.

• Arquivos necessários:

  • Certificado digital. O arquivo correspondente deve estar disponível, é um arquivo com a extensão .pfx, aqui será referenciado por certificado.pfx. Também será necessária a senha para acesso ao conteúdo do certificado.

  • Baixe o arquivo JSON de (configuração) do Postman, contendo exemplos de requisições prontas. Além das requisições este arquivo também contém a documentação de cada uma delas. A documentação das requisições também encontra-se amplamente disponível.

Segurança (headers)

Toda requisição ao endereço EHR (veja ambientes), faz uso de dois headers obrigatórios, aqui definidos como headers de segurança:

• X-Authorization-Server: este é header por meio do qual o valor do token de acesso é fornecido. O valor deste header é definido pela concatenação de Bearer com o valor do token. Em consequência, para o token de valor "token", o valor do header seria Bearer token. Convém ressaltar que o token de acesso é uma sequência de mais de 2000 caracteres e, portanto, bem mais extensa que o simples valor "token".
• Authorization: neste header é identificado o profissional de saúde, lotado no estabelecimento de saúde em questão, em nome do qual a requisição é feita. O valor fornecido deve ser o CNS deste profissional.

Passos

De posse das informações e dos arquivos, veja seção anterior, pode-se configurar o Postman: (a) importar collection; (b) configurar certificado digital e (c) configurar variáveis.

Importar collection

Veja o vídeo acerca de como importar aqui

Ao abrir o Postman você verá uma tela similar àquela abaixo, exceto que não terá o destaque para o botão Import, empregado para "importar" o arquivo baixado anteriormente:

Após importado, o resultado é similar àquele abaixo. A versão pode ser diferente, por exemplo. Observe que estão disponíveis 11 requisições, agrupadas naquelas de "Segurança" e "Saúde".

Neste ponto pode-se selecionar uma das requisições e, no canto superior direito, botão Send submeter aquela selecionada. Contudo, qualquer uma delas deve falhar, afinal, não indicamos o certificado a ser empregado nem outras configurações necessárias.

Fornecer o certificado digital para uso

Veja o vídeo acerca de como configurar o Postman com o certificado digital aqui

O Postman precisa ser configurado para usar o certificado digital do estabelecimento de saúde em questão, quando uma requisição for direcionada ao endereço empregado para autenticação do ambiente de homologação.

Esta configuração é exigida para a correta execução do serviço denominado "Obter token de acesso". E o resultado desta requisição é necessário para a execução de todos os demais serviços. Em tempo, este é o único serviço que usa diretamente o certificado digital.

O serviço "Obter token de acesso" produz como resultado (retorno) o token de acesso. Tal token é exigido por todos os demais serviços. Ou seja, primeiro se obtém o token de acesso, que tem validade por 30 minutos, e depois ele é reutilizado, neste período, em todas as demais requisições. Transcorridos os 30 minutos, será necessário uma nova requisição ao serviço "Obter token de acesso", para que um novo token, válido pelos próximos 30 minutos, possa ser reutilizado.

A indicação do certificado digital a ser utilizado pelo Postman é realizada da seguinte forma. Selecione File (opção do menu), na sequência a opção Settings e, por fim, abre-se a janela abaixo, na qual a aba Certificates deve ser selecionada e, por último, Add Certificate.

Quando Add Certificate é pressionado, abre-se tela similar àquela abaixo. Observe que nenhum valor estará preenchido, ao contrário da tela exibida abaixo, na qual as três informações exigidas já estão fornecidas: (a) o domínio para o qual o certificado será utilizado pelo Postman, ou seja, a porta Auth do ambiente de homologação ou, especificamente, o endereço ehr-auth-hmg.saude.gov.br; (b) o arquivo .pfx contendo o certificado digital do estabelecimento de saúde e, por último, (c) a senha empregada para se ter acesso ao conteúdo do certificado.

Ao clicar no botão Add, o Postman estará configurado para usar o certificado, para acesso ao endereço indicado e, para o uso, empregará a senha fornecida.

Após a configuração do certificado, quando se requisita a submissão do serviço "Obter token de acesso", que está disponível exatamente no endereço fornecido na configuração acima, o certificado e a senha serão utilizados pelo Postman para submter a requisição em questão. Agora, o resultado esperado é 200 OK. Observe que, logo abaixo, uma visualização (visualize) alternativa do retorno oferecido pela RNDS é exibida, na qual o access_token é ocultado. As demais informações não são sigilosas. Em particular, observe que o token tem uma validade de 30 minutos, ou seja, a intenção é que seja reutilizado neste período, conforme mencionado anteriormente.

As demais requisições dependem de outras configurações. Mais um passo e todas elas estarão funcionando.

Configurar variáveis

A configuração do Postman para fazer uso do certifica digital viabiliza a execução da requisição "Obter token de acesso". As demais, contudo, além do token retornado por esta requisição, dependem de outros valores, neste caso, depositados em variáveis. Abaixo segue o conjunto das variáveis empregadas pelo Postman para execução das requisições.

Ao todo são 10 variáveis, nem todas podem ser vistas acima. Os valores para as 3 primeiras, individuo-cns, lab-cnes e lab-identificador, devem ser definidos de forma compatível com o certificado digital utilizado. São valores específicos por estabelecimento de saúde. Na figura acima são fornecidos valores espúrios, fictícios (a serem substituídos). Por exemplo, lab-cnes deve ter como valor o CNES do estabelecimento de saúde cujo certificado digital foi fornecido ao Postman no passo anterior. Assim como individuo-cns deve ser o CNS de um profissional de saúde lotado no estabelecimento de saúde em questão.

As 3 variáveis seguintes, auth, ehr e ufg-cnpj, são independentes do estabelecimento de saúde. As duas primeiras identificam valores pertinentes ao ambiente de homologação da RNDS. A última apenas configura um CNPJ para facilitar a execução de requisição de consulta por CNPJ. Neste caso, este CNPJ está disonível no próprio portal da UFG (CNPJ utilizado no exemplo).

Os valores das 4 últimas variáveis são gerados pelo próprio Postman durante a execução das requisições. Por exemplo, a variável access_token é definida pela execução do serviço "Obter token de acesso" e, como anteriormente informado, o valor desta variável é empregado na composição do header de nome X-Authorization-Server por todas as demais requisições.

Variáveis específicas por estabelecimento de saúde (assim como o certificado digital):

• lab-identificador: identificador do laboratório fornecido pela RNDS quando o credenciamento é homologado. Observe que este identificador não é o CNES. Observe que o responsável pelo laboratório deverá acompanhar o pedido de credenciamento e, quando este é homologado, este identificador estará disponível por meio do portal de serviços (o mesmo empregado para pedir o credenciamento). Veja identificador do solicitante para detalhes.

• lab-cnes: o código CNES do laboratório cujo credenciamento foi solicitado por meio do portal de serviços da RNDS e também aprovado. Naturalmente, o certificado digital empregado para configurar o Postaman deve ser do laboratório em questão.

• individuo-cns: conforme o próprio nome indica, é o CNS de um indivíduo, em particular, o CNS do profissional de saúde em nome do qual requisições serão feitas. Ou seja, este CNS deve estar associado ao laboratório em questão (CNES fornecido na variável acima). Este valor será enviado para a RNDS por meio do header de nome Authorization em todos os contatos com a RNDS. A exceção é o serviço "Obter token de acesso", que não faz uso deste header. Adicionalmente a este uso, com o propósito de evitar a definição de outra variável, este valor também é reutilizado para outras finalidades, por exemplo, para identificar o paciente de um exame.

Variáveis de uso amplo:

• auth: endereço empregado para autenticação. Este valor é empregado na requisição "Obter token de acesso", conforme ilustrado abaixo, na montagem da URL correspondente (destaque na cor laranja).

• ehr: endereço para envio das requisições de serviços (web services) de saúde. Enquanto o valor da variável auth é empregado apenas para a requisição do serviço "Obter token de acesso", o valor da variável ehr é empregado em todas as demais requisições. À semelhança de auth, a variável ehr é empregada na montagem da URL da requisição, conforme ilustrado abaixo (destaque na cor laranja).

• ufg-cnpj: CNPJ da Universidade Federal de Goiás (UFG). Empregado apenas para teste. Observe que este valor pode ser obtido do próprio portal da UFG.

Variáveis geradas pelo próprio Postman:

• access_token: gerada a partir da resposta para a requisição "Obter token de acesso". Se executada de forma satisfatória, deposita nesta variável o token de acesso a ser consultado por todas as demais requisições.

• exame-id-lab: identificador gerado de forma aleatória para um resultado de exame laboratorial. Este valor é gerado pela requisição "Enviar resultado de exame" e utilizado pela requisição "Substituir resultado de exame".

• exame-id-rnds: identificador gerado pela própria RNDS para um resultado de exame submetido de forma satisfatória (requisição "Enviar resultado de exame"). Este identificador único, gerado pela RNDS, é depositado nesta variável e, à semelhança de exame-id-lab, também é empregado pela requisição "Substituir resultado de exame".

Experimentar requisições

A execução de requisições é feita com a seleção da requisição a ser executada e, em seguida, ao clicar no botão Send. A requisição será submetida e o retorno será exibido. A sugestão é experimentar mudanças nos parâmetros das requisições, no payload de um resultado de exame, remover um header, alterar o valor de um header e observar os resultados. Desta forma será possível adquirir fluência na interação com a RNDS.

Como criar código correspondente às requisições?

O Postman novamente ajuda aqui. Para cada requisição o Postman apresenta como a mesma pode ser implementada usando várias estratégias, incluindo ferramentas de linha de comandos como curl e wget, por exemplo, além de código em Java, C#, JavaScript, Swift e outras, perfazendo dezenas de alternativas.

Apenas por curiosidade (e por diversão) segue como executar uma das requisições oferecidas pela RNDS em Ocaml:

open Lwt
open Cohttp
open Cohttp_lwt_unix

let reqBody =
  let uri = Uri.of_string "https://ehr-services.hmg.saude.gov.br/api/fhir/r4/Organization/01567601000143" in
  let headers = Header.init ()
    |> fun h -> Header.add h "Content-Type" "application/json"
    |> fun h -> Header.add h "X-Authorization-Server" "Bearer tokenAqui"
    |> fun h -> Header.add h "Authorization" "00112233445566"
  in
  Client.call ~headers `GET uri >>= fun (_resp, body) ->
  body |> Cohttp_lwt.Body.to_string >|= fun body -> body

let () =
  let respBody = Lwt_main.run reqBody in
  print_endline (respBody)

A exceção não adequadamente contemplada pelo Postman é a obtenção do token de acesso. Contudo, esta necessidade está devidamente desenvolvida, tanto para Java quanto JavaScript, e documentada.

Parabéns!

Os "primeiros contatos" com um servidr FHIR, possivelmente do ambiente de homologação da RNDS foram estabelecidos. Seguramente, após exercitar as várias requisições, a ambientação necessária tanto com as informações necessárias, quanto aquelas retornadas, e a estrutura da requisição, estará concluída.

O próximo passo é o desenvolvimento do código que executa as requisições exercitadas com o propósito de integração entre o estabelecimento de saúde e a RNDS. seja atribuição de cada laboratório, e cada um possui suas especificidades, isto não inviabiliza mais um passo na direção de facilitar esta integração, que é o motivo de existência do presente guia: ilustrar o conector(software de integração), um componente de software implementado, que pode inspirar ou até ser reutilizado pelo laboratório para a sua integração.