Última atualização em: 08 de junho, 2021
Antes de iniciar a leitura deste artigo, realize a leitura do artigo Autenticação API Rest.
Entendido o processo de geração do token JWT (JSON Web Token) para a obtenção do accessToken e refreshToken, entenderemos a utilização dos mesmos através de exemplificação na ferramenta Postman, utilizada pela Migrate. Caso não deseje utilizar o Postman, é possível a utilização de outra ferramenta a seu critério.
A utilização do accessToken e do refreshToken pode ser realizada de duas formas pelo sistema parceiro, sendo elas:
Autenticação utilizando apenas o accessToken
Obtidos os accessToken e refreshToken, o accessToken terá validade de 1 hora e o refreshToken terá validade de 24 horas. É necessário o tempo de expiração dos tokens para que apenas usuários em posse da chave de parceiro e chave de acesso da empresa emissora, possam realizar a autenticação com a aplicação, fazendo uso dos serviços e tendo acesso às informações das operações dos emissores.
Desta forma, o accessToken poderá ser utilizado para autenticação com o Invoicy dentro do período de 1 hora. O mesmo deverá ser enviado na aba “Headers” em “Authorization” em todas as requisições:
Se o accessToken for utilizado com sua validade expirada, o Invoicy retornará a seguinte estrutura:
Com isso, o sistema parceiro deverá possuir um tratamento em que sempre que receber o retorno de status 400 com title “\”Invalid token\”” será necessário gerar um novo JWT a ser enviado na opção Gerar Token do projeto, para receber um novo accessToken a ser utilizado.
Autenticação utilizando o accessToken e refreshToken
Neste caso, ao receber o retorno de status 400 com title “\”Invalid token\”” o sistema parceiro deverá enviar o refreshToken ao Invoicy através da opção Refresh Token do projeto exemplo:
Ao realizar este envio, serão retornados novos accessToken e refreshToken a serem utilizados para a autenticação. Vale ressaltar que a diferença ao utilizar o accessToken e também utilizar o refreshToken é que no momento em que o accessToken expira utiliza-se o refreshToken e não é necessário gerar um novo token JWT.
Importante! Após expiradas as 24 horas de validade do primeiro refreshToken retornado, obrigatoriamente o sistema parceiro deverá gerar um novo token JWT para receber accessToken e refreshToken novos. Ou seja, se optar por utilizar o refreshToken, no mínimo 1 vez ao dia o sistema integrado ao Invoicy terá de gerar um JWT para receber o accessToken e refreshToken e nas próximas 24 horas poderá trabalhar apenas com o refreshToken para receber chaves accessToken válidas.
Situação hipotética 1: por exemplo, a empresa gerou seu primeiro accessToken e refreshToken para autenticação com o Invoicy para envio de documentos e ela emitiu 3 documentos dentro de 1 hora com este accessToken. Após, a empresa realizou o envio do quarto documento, excedendo a 1 hora de validade mas ainda dentro das 24 horas de validade do refreshToken, e o Invoicy retornou status 400 com title “\”Invalid token\””. Neste momento, o sistema parceiro deve enviar o resfreshToken para obter o novo accessToken e refreshToken a serem utilizados na autenticação.
Situação hipotética 2: a empresa gerou seu primeiro accessToken e refreshToken para autenticação com o Invoicy para envio de documentos e ela emitiu 3 documentos dentro de 1 hora com este accessToken. Após, a empresa realizou o envio do quarto documento, excedendo a 1 hora de validade do accessToken, assim, o sistema envia o refreshToken e recebe um novo accessToken e refreshToken. O quinto documento foi emitido após as 24 horas de validade do refreshToken gerado para o primeiro documento emitido, assim, o sistema parceiro gera um novo JWT para enviar na opção Gerar Token do projeto.
Se enviado um refreshToken expirado, o Invoicy retornará a seguinte estrutura:
Importante observar que title passa a ser message e a descrição do retorno muda para “Invalid refresh token”.
Recebendo este retorno o software da empresa parceira deve gerar um novo JWT para receber novos accessToken e refreshToken a serem utilizados na autenticação.
Desenvolvedores Migrate 