Geração de Tokens
A partir do JWT gerado na autenticação, é possível gerar estes tokens utilizando uma ferramenta de testes de API como o Postman, utilizando como base a documentação de exemplo disponibilizada aqui. Para compreender melhor sobre como realizar a geração do JWT acesse o artigo: Autenticação.
Na sequência, localize a requisição "Gerar Token", clique nela e selecione a seção Body (raw). Em "token" informe o JWT gerado e clique em "Send" para realizar o envio, conforme demonstrado abaixo:
No retorno da requisição serão exibidos o accessToken e o refreshToken, que são essenciais para realizar todas as demais requisições via API REST. Segue abaixo um exemplo deste retorno:
Destacando que, cada um desses tokens tem suas particularidades, como a validade limitida após a geração dos mesmos. No entanto, ambos tem a função de servir como um autenticador em todas a requisições enviadas. Confira a seguir as principais diferenças entre eles:
accessToken
Com a obtenção dos tokens, o accessToken passará a ter validade limitada, para que somente os usuários em posse da chave de parceiro e de acesso da empresa emissora, possam realizar a autenticação com a aplicação, fazendo uso dos serviços e acessando à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 e deverá ser enviado na seção Headers em todas as requisições.
Se o accessToken for utilizado com sua validade expirada, o Invoicy retornará a mensagem "Invalid token". Por isso, o sistema parceiro deverá possuir um tratamento em que ao receber o retorno de status 400 com a mensagem "Invalid token" seja gerado um novo JWT na requisição "Gerar Token", para enviá-lo e receber um novo accessToken.
refreshToken
Com a obtenção dos tokens, o refreshToken passará a ter validade limitada, para que somente os usuários em posse da chave de parceiro e de acesso da empresa emissora, possam realizar a autenticação com a aplicação, fazendo uso dos serviços e acessando à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 24 horas e deverá ser enviado na seção Headers em todas as requisições.
O refreshToken pode ser utilizado para obter um novo accessToken após a expiração do atual, evitando a necessidade de gerar um novo JWT inicial.
Neste caso, ao receber o retorno de status 400 com a mensagem "Invalid token" o sistema parceiro deverá enviar o refreshToken ao Invoicy através da requisição "Refresh Token" da documentação de exemplo. Ao realizar este envio, serão retornados novos tokens a serem utilizados para a autenticação. A diferença ao utilizá-los, é que no momento em que o accessToken expira, utiliza-se o refreshToken e não é necessário gerar um novo token JWT por um longo tempo.
É importante ressaltar que, após expiradas as 24 horas de validade do primeiro refreshToken retornado, obrigatoriamente o sistema parceiro deverá gerar um novo token JWT para receber novos tokens. 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.
Com a geração efetuada, é possível utilizar os tokens para enviar diferentes requisições via REST. Para mais instruções sobre como realizar estes envios, consulte os seguintes artigos: