Utilização do accessToken e refreshToken

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 dos tokens pode ser realizada de duas formas pelo sistema parceiro, sendo elas:

Autenticação utilizando apenas o accessToken

Ao obter as informações desses tokens, 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 nos “Headers” em todas as requisições

Se o accessToken for utilizado com sua validade expirada, o Invoicy retornará “Invalid token\”.

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.

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 esses dois tokens, é 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.