01. DADOS GERAIS
Produto: | TOTVS Saúde Planos |
---|---|
Linha de Produto: | Datasul |
Segmento: | Saúde |
Módulo: | HAT - Atendimento ao Público |
Função: | PTU Online |
País: | Brasil |
Requisito: | DSAUGPSAUTOR-11228 |
02. SITUAÇÃO/REQUISITO
Com o objetivo de dar continuidade à estratégia de evolução tecnológica dos produtos da linha Datasul, é necessário disponibilizar um novo serviço para o PTU Online, eliminando a dependência do Foundation Saúde.
O objetivo deste documento é apresentar os detalhes do novo serviço para o PTU Online no Tomcat, criado para a substituir o atualmente em uso no JBoss.
03. SOLUÇÃO
Foi realizada a implementação das funcionalidades destacadas abaixo, dando origem ao novo serviço do PTU Online.
A versão mínima para utilização do serviço é a 12.1.2307, com liberação no patch de 15/01/2024 para as versões 12.1.2307-9 e 12.1.2311-3.
É possível utilizar o serviço de forma híbrida com o Foundation Saúde, realizando a migração parcialmente, conforme detalhado na aba Procedimento para Configuração.
1. Acesse o menu Importação Menu Datasul (men706aa) e importe o arquivo men_hat.d.
2. Acesse o menu Programa Produto Datasul (bas_prog_dtsul) e altere o registro "hat.ptuOnlineParam" para liberar as permissões de acesso ao menu "PTU Online" da Central de Integrações Saúde Planos (hgp.integrationsParams).
Com o novo serviço, a aplicação htzfoundation.ear (JBoss) passa a ser totvs-hgp-ptuonline.war (Tomcat), contendo somente os Webservices do PTU Online.
Para que a comunicação entre os serviços funcione corretamente, é necessário que o Tomcat onde é executado o serviço totvs-hgp-ptuonline.war reconheça as variáveis abaixo. A configuração pode ser feita diretamente nos scripts de inicialização do Tomcat (mais detalhes e exemplos aqui: Como criar variaveis de ambiente visiveis ao Datasul no Tomcat) ou mesmo diretamente como variáveis de ambiente do sistema operacional:
TOTVS_HOST: <host>:<porta> do serviço do Tomcat do Datasul. Ex: http://meu-datasul:8080
TOTVS_USERNAME: usuário de login que será utilizado para autenticação Basic no Datasul para execução dos serviços
TOTVS_PASSWORD: senha que será utilizada junto ao parâmetro acima
Obs: estas variáveis são utilizadas por outras aplicações, portanto é possível que já estejam configuradas no seu ambiente, e nesse caso, nenhuma ação é necessária, apenas a conferência.
Dica para validar esta etapa
Após configurar as variáveis de ambiente e reiniciar o Tomcat, utilize a URL abaixo para validar se o ambiente as reconheceu corretamente:
http://<SERVIDOR>:<PORTA>/totvs-hgp-webservices/ptu/v8/integrations/gateway/serverInfo
O resultado deve ser semelhante a isto:
As variáveis precisam aparecer nesta consulta antes de prosseguir para a próxima etapa. Caso contrário ocorrerão problemas de comunicação.
O serviço oferece suporte a comunicação por meio de WebServices com segurança (certificado digital), exigidos pela Unimed do Brasil.
Inicialmente é necessário possuir um keystore (.jks) contendo somente o certificado digital disponibilizado pela Unimed do Brasil:
Um keystore é um arquivo no formato .jks que serve como um repositório de certificados. Para correto funcionamento, é necessário que dentro dele exista somente o certificado disponibilizado pela Unimed do Brasil.
A criação de um keystore pode ser realizada através do comando keytool -genkeypair.
A importação de um certificado para um keystore pode ser realizada através do comando keytool -importcert.
A ferramenta keytool é distribuída junto com a instalação de um Java JDK,:
Maiores informações sobre a ferramenta podem ser consultadas em sua documentação oficial.
A Unimed Brasil somente realiza comunicação com os WebServices publicados utilizando o certificado digital fornecido por eles. Para que não haja conflito do PTU Online com outros processos que necessitam de certificado digital na entrada, é recomendado que o cliente utilize um Tomcat exclusivo para o serviço do PTU. Nesse caso, as variáveis de ambiente configuradas no item Servidor de Aplicação devem ser criadas no servidor onde o serviço do PTU estará rodando.
Após obter o keystore.jks conforme as orientações acima, o mesmo deve ser referenciado na inicialização do Tomcat, adicionando as tags Djavax.net.ssl.keyStore e Djavax.net.ssl.keyStorePassword na variável JAVA_OPTS. Somente atendendo a estas etapas será possível realizar as comunicações de envio e recebimento de transações com o WSD de intercâmbio.
Exemplo: "JAVA_OPTS=-Djavax.net.ssl.keyStore=<pasta>/keystore.jks -Djavax.net.ssl.keyStorePassword=<senha>"
Configurando no Linux
No Linux, adicionar as tags no arquivo de inicialização do serviço, normalmente em /etc/systemd/system/meu_servico.service
Exemplo:
Configurando no Windows
No Windows, adicionar as tags através da tela de configurações ...\tomcat\bin\tomcat9w.exe
Obs: dependendo da forma com que o serviço foi criado, o arquivo tomcat9w.exe pode ter sido renomeado para o nome do seu serviço. Neste caso, basta usar o seu arquivo.exe
Neste exemplo, tomcat9w.exe foi renomeado durante a instalação:
Ao executar o programa acima, será aberta esta tela. Basta adicionar as variáveis e reiniciar o Tomcat:
Conferência das configurações
Após realizar as configurações acima, o Tomcat deve ser reiniciado, e as novas variáveis devem aparecer no início do log .../tomcat/logs/catalina.out, conforme o exemplo:
Se as variáveis não aparecerem no log, revise as configurações antes de prosseguir.
Na Central de Integrações Saúde Planos (hgp.integrationsParams) foi criado o novo menu PTU Online, contendo as parametrizações do serviço:
Este menu contém as configurações que anteriormente eram realizadas no arquivo foundation-exchange.properties do JBoss.
Com o novo serviço, essas configurações passam a ser realizadas diretamente no sistema.
Comunicação
- A URL do serviço deve ser o servidor + porta onde a aplicação está rodando:
- Ex: http://servidor1:8080
- Apesar de ser um serviço do próprio ERP, este parâmetro é necessário para que aplicações externas consigam acessar. Ex: Autorizador Web realizando a comunicação de uma guia de intercâmbio.
- Nesse momento de funcionamento híbrido, a versão do PTU Online continua sendo definida na Manutenção Parâmetros Globais Sistema (hpr1410p/hcg.globalParameters). Quando ocorrer a descontinuação definitiva do módulo Foundation Saúde, o parâmetro será migrado para essa tela.
Endpoints
- Quando o campo relacionado ao endpoint estiver preenchido, o sistema realizará a comunicação através do novo serviço, via Tomcat.
- Quando o campo relacionado ao endpoint estiver vazio, o sistema realizará a comunicação através do Foundation, via JBoss.
As URL's a serem informadas são as fornecidas pela Unimed do Brasil para comunicação com o WSD referente à cada mensagem.
As mensagens de Pedido de Autorização (0600), Ordem de Serviço (0806) são dependentes pois quando ocorre o recebimento de uma ordem de serviço (0806), o sistema encaminha o pedido de autorização (0600) referente à aquela O.S., portanto devem ser migradas juntas.
As demais não possuem dependência e podem ser migradas individualmente conforme evolução dos testes.
Exemplo:
Editando e preenchendo o campo do endpoint da mensagem de Status da Transação (0360):
Ao realizar uma consulta de Status da Transação através da Consulta Status da Transação (hat0110p/hat.transactionStatusInquiry), a comunicação será realizada através do novo serviço e não mais pelo Foundation.
Assim como as URL's da Unimed do Brasil devem ser preenchidas nessa tela, é necessário atualizar os endpoints do serviço na Unimed do Brasil para que o WSD comunique com cada mensagem, sendo elas:
- Pedido de Autorização (0600): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/pedidoAutorizacao
- Pedido de Complemento de Autorização (0605): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/pedidoComplementoAutorizacao
- Pedido de Insistência (0302): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/pedidoInsistencia
- Resposta de Auditoria (0404): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/respostaAuditoria
- Cancelamento (0311): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/cancelamento
- Consulta de Dados do Beneficiário (0412): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/consultaDadosBeneficiario
- Status da Transação (0360): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/statusTransacao
- Comunicação de Decurso de Prazo (0700): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/comunicacaoDecursoPrazo
- Comunicação de Internação ou Alta (0750): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/comunicacaoInternacaoAlta
- Ordem de Serviço (0806): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/ordemServico
- Autorização de Ordem de Serviço (0804): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/autorizacaoOrdemServico
- Consulta de Dados do Prestador (0418): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/consultaDadosPrestador
- Contagem de Beneficiários (0430): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/requisicaoContagemBeneficiarios
- Transações Respondidas pelo WSD (1100): https://<servidor>:<porta>/totvs-hgp-ptuonline/v91_00/consultaA1100
É necessário substituir o <servidor> e <porta> conforme seu ambiente.
Log Auxiliar
- Habilita/desabilita a geração de arquivos auxiliares contendo os dados de entrada e saída das comunicações realizadas no PTU Online, úteis para ambientes de homologação e validação de informações.
- Os arquivos serão gerados seguindo a nomenclatura: "Operação" + "Código da transação" + "Descrição da transação" + "Data" + "Hora".json
- Operação poderá ser: Envio, Resposta, Recebimento ou Resposta de Recebimento
- Exemplo de arquivos gerados:
- Quando habiitado é necessário informar um diretório válido para exportação, normalmente um diretório de rede que o PASOE consiga acessar.
- Quando desabilitado nenhum arquivo será exportado.
Essa funcionalidade é similar à pasta "xmlwslog" que existia no servidor do Foundation, com a diferença que os arquivos serão gerados em formato JSON e não mais XML. Para verificar os XMLs que trafegaram de fato pelo WSD da Unimed do Brasil, pode ser utilizada a consulta de fases da transação pela Interface Única.
O novo serviço utiliza o conceito de Broker Escalável, onde é possível direcionar as chamadas ao Progress para um broker específico, isolando o back-end de outras aplicações, como o ERP por exemplo.
Toda comunicação encaminhada da aplicação totvs-hgp-ptuonline.war para o Progress enviará na requisição a chave "x-totvs-server-alias" como "totvs-saude-planos-ptuonline", sendo necessário que o cliente inclua através dos Parâmetros Foundation (btb962aa) um novo registro contendo esse alias.
Exemplo:
No programa BTB962AA (Parâmetros Foundation), criar um novo registro contendo o alias "totvs-saude-planos-ptuonline":
Caso o cliente deseje isolar a parte Progress do PTU Online em um broker separado, deve ser criada uma nova instância do PASOE, referenciando-a através do campo "Servidor Aplicação". Para maiores detalhes sobre a criação da instância no PASOE, ver a documentação: Criando uma instância PASOE através do OpenEdge Explorer
Caso o cliente não deseje fazer essa separação, basta criar o registro com o alias "totvs-saude-planos-ptuonline" referenciando para o mesmo "Servidor Aplicação" existente.
Na página Broker Escalável - Exemplo de como fazer uso do aplicativo e alias para chamadas REST é possível verificar maiores detalhes sobre essa configuração.
Para os clientes que utilizam programas de CPC no processo do PTU Online, deverão atentar-se para as orientações abaixo:
Os programas cpc-api-recebe-ptu91.p e cpc-atconstrans.p foram substituídos pelo cpc-bosau-recebe-ptu-online.p.
Para funcionamento correto das rotinas no processo, é necessário criar o novo programa e migrar a lógica existente para ele.
Foundation: cpc/cpc-api-recebe-ptu91.p Tomcat: cpc/cpc-bosau-recebe-ptu-online.p
cpc/cpc-api-recebe-ptu91.i cpc/cpc-bosau-recebe-ptu-online.i
cpc/cpc-atconstrans.p
cpc/cpc-atconstrans.i
- A nova nomenclatura não contém o número da versão do PTU, não sendo mais necessário criar um novo programa a cada atualização
- Os nomes dos pontos de chamada foram mantidos os mesmos. Ex: "ORDEM-SERVICO", "ALTERA-PREST"
- O novo programa deve conter somente 2 parâmetros: a tabela de entrada e a de saída:
- Para migração da lógica da CPC, deve ser considerada a nova nomenclatura das temp-tables do programa (todos os campos anteriormente existentes foram mantidos):
# | Descrição | Causa | Possíveis soluções |
---|---|---|---|
1 | Ao realizar uma comunicação de envio é apresentado o erro: "I/O error on POST request for "/null/dts/datasul-rest/resources/prg/hat/v1/ptuOnlineV91_00/<mensagem>" | A variável de ambiente "TOTVS_HOST" não foi reconhecida | Verifique se as variáveis de ambiente foram configuradas conforme a documentação Como criar variaveis de ambiente visiveis ao Datasul no Tomcat. |
2 | Ao realizar uma comunicação de envio ou recebimento é apresentado o erro: "I/O error: Received fatal alert: bad_certificate; nested exception is javax.net.ssl.SSLHandshakeException" | O certificado digital não foi reconhecido | 1 - Verifique se o keystore utilizado possui somente o certificado digital da Unimed do Brasil 2 - Verifique se o keystore foi referenciado corretamente na inicialização do Tomcat através das variáveis -Djavax.net.ssl.keyStore e -Djavax.net.ssl.keyStorePassword 3 - Verifique se não há conflito com outros certificados, utilizando um Tomcat exclusivo para o PTU Online 4 - Utilize um proxy reverso para atribuir o certificado digital da Unimed do Brasil nas comunicações de entrada Na página Configuração de HTTPS para o Datasul for THF é possível verificar mais informações sobre o processo de certificação digital com Tomcat. |
Não houve alteração no processo de utilização das funcionalidades que envolvem o PTU Online. Todas as regras de negócio e operações em tela foram mantidas.
Exemplo: Ao solicitar uma guia de intercâmbio pelo AT0110Z, o processo de inclusão/comunicação percebido pelo usuário será o mesmo, com a diferença que o sistema estará direcionando a chamada para a Unimed do Brasil através do novo serviço e não mais pelo Foundation.
03. ASSUNTOS RELACIONADOS