TOTVS Protheus – Integração com Web Service REST Autenticação e Token com JSON
Veremos neste artigo como fazer uma integração simples com um Web Service REST que exige autenticação e envio de token usando a linguagem AdvPL (Advanced Protheus Language).
Entendendo o cenário fictício
Uma distribuidora que possui frota própria e vende
para todo o Brasil precisa fazer averbação (seguro) de todas as cargas que são
transportadas e para isso precisa enviar os arquivos XML (Extensible Markup Language) correspondente às NF-e
que compõe estas cargas para o Web Service (WS) da seguradora.
O web service da seguradora recebe os XML e devolve
o protocolo de averbação da NF-e. De forma bem resumida esse é o processo que iremos tratar nessa integração.
Testando a conexão com o Web Service (WS)
Partindo do princípio de que já verificamos a
documentação do WS da seguradora e de posse dos dados para
autenticação, vamos fazer os testes necessários antes de partir para a
codificação. Para isso podemos usar ferramentas como Postman, Insomnia, SoapUI
e afins.
Passo 1: Na documentação do WS é informado
que os dados de autenticação devem ser passados no body (corpo) do arquivo em
formato JSON (Java Script Object Notation) conforme exemplo:
{ "usuario": "teste", "senha":
"wsteste", "codigoconn": "22582258" }
A documentação ainda informa o seguinte:
“No header Accept deve ser informado application/json
ou application/xml, essa informação define qual o tipo de resposta que será recebido
ao realizar o consumo.”
“O Content-Type deve ser application/json para
chamadas de autenticação (Auth); para envio de documentos informar
application/xml no Content-Type.”
“Acionar o link (http://webserver.averba.com.br/rest/auth)
para autenticação e recepção de Token.”
Estas informações já são o suficiente para
iniciarmos os testes. Portanto já podemos prosseguir com uso da ferramenta para
testar a autenticação e recepção do token.
Passo 2: Seguindo adiante a figura 1 ilustra o uso da ferramenta Insomnia, onde foi passado no body do objeto JSON os atributos e seus valores, além do endereço web conforme explicado na documentação.
FIGURA 1 Configuração inicial para autenticação no Web Service
FIGURA 2 Definindo os parâmetros do cabeçalho (Header) do arquivo
FIGURA 3 Resultado do teste de autenticação e retorno
Agora que já conseguimos concluir os testes
necessários vamos implementar essa mesma autenticação usando a linguagem AdvPL
no próximo tópico.
Partindo para a implementação em AdvPL: Autenticando e recuperando token
Nesta etapa vamos basicamente repetir todo o
processo, porém implementando através de uma linguagem de programação o envio
do objeto JSON para autenticação no serviço e recuperação do token que será
usado posteriormente.
Iremos usar as classes FWRest e JsonObject que possuem os métodos necessários para fazer nosso trabalho. Na figura 4 foi implementado a função RecuperaTokenWebService() e a função BuscaDadosLogin() que busca os dados de autenticação (usuário, senha e codigoadm) no formato JSON. No geral é uma implementação simples de se fazer.
Os dados de autenticação poderiam também ser
atribuídos de forma direta no método SetPostParams, dispensando a necessidade
de criar a função BuscaDadosLogin() caso posteriormente não precise reutilizar
os dados em outra função. Veja o exemplo abaixo de como ficaria:
oRest:SetPostParams('{"usuario":"teste",
"senha":"wsteste", "codigoatm":"22582258"}')
Por fim ao executar a função RecuperaTokenWebService() teremos o resultado exibido em tela para fins didáticos conforme figura 5, ou seja, nossa aplicação esta autenticando e retornando o token.
O próximo passo é fazer o envio do XML junto com o
token para a seguradora, pegar o protocolo de averbação e gravar em uma tabela
customizada do ERP.
Enviando token e o XML da NF-e
Nessa fase teremos que consultar a documentação
novamente para verificar como deve ser feito o envio do XML, ou seja, verificar como deve ser elaborado o arquivo JSON para envio. Essa documentação é mostrada
na tabela 1.
Em resumo a documentação nos mostra uma nova URL e a configuração do header. Vamos fazer o teste com esses dados na ferramenta Insomnia. A figura 6 representa a configuração das propriedades do header incluindo a string do token conforme solicitado na documentação. Lembre-se que o Token é a string retornada conforme exemplo da figura 5.
Na figura 7 temos a configuração do corpo do
arquivo JSON, onde colamos o conteúdo de um arquivo XML e na direita é mostrado
o retorno em JSON após clicar no botão send. Assim concluímos mais esse teste
pela ferramenta e agora vamos continuar o desenvolvimento da nossa rotina.
Na figura 8 temos a implementação da rotina.
Adicionamos ao vetor as propriedades do cabeçalho e no valor BEARER chamamos a
função que retorna o token.
No SetPostParams foi utilizado a função
BuscaNfeXML() que recupera um XML da base de dados. Não irei entrar em detalhes
sobre essa função pois não faz parte do escopo.
Conforme pode ser verificado você poderá fazer os
tratamentos necessários conforme o retorno do método GetHTTPCode(), o retorno será no formato JSON sendo necessário utilizar métodos da classe
JsonObject.
Conclusão
Vimos através de um cenário fictício o uso das
classes FWRest e JsonObject para a realização de uma integração simples usando
a linguagem AdvPL. Realizamos a autenticação e envio de token pela ferramenta
de teste Insomnia, implementamos uma aplicação teste que autêntica e recupera o
token de um objeto JSON, enviamos o XML junto com o token e obtivemos retorno
JSON. Por fim verificamos as possibilidades que ainda podem ser realizadas com
base no retorno do web service, como por exemplo pegar os dados do retorno,
validar, gravar no banco de dados e etc. No entanto isso dependerá da
necessidade de cada negócio. O importante neste trabalho foi passar de forma
didática a visão geral de uma integração básica e espero que seja útil para o
aprendizado e troca de informações. Até a próxima!
Comentários
Postar um comentário