Autenticação
A autenticação em APIs REST é um componente fundamental para garantir a segurança e a integridade das transações de dados. Para a integração com o InvoiCy via API REST, o método de autenticação adotado está fundamentado no uso de JSON Web Tokens (JWT), conforme a especificação RFC 7519.
É importante ressaltar que, o host varia por ambiente, sendo: homologação https://apibrhomolog.invoicy.com.br e produção https://apibr.invoicy.com.br/.
Para referência visual, consulte o vídeo demonstrativo clicando aqui.
Antes de iniciar o desenvolvimento em seu sistema, a abordagem mais eficaz para compreender o fluxo é a simulação da geração manual do token JWT.
Para simular o processo de geração, é sugerido o uso do portal oficial do JWT. Na interface da ferramenta, o painel "JWT Decoded" deve ser configurado, ajustando-se as seções "Decoded Payload" e "JWT Verify Signature". O "Decoded Payload" contém as reivindicações (claims) que definem o contexto e as permissões da solicitação.
Estes são os campos obrigatórios e suas respectivas descrições para:
JWT de Parceiro
| CAMPO | DESCRIÇÃO | EXEMPLO |
|---|---|---|
| iat | Horário atual no formato timestemp fuso 0 | 1765997468 |
| exp | Horário atual no formato timestemp fuso 0 + 120 segundos | 1765997468 |
| sub | Chave de Parceiro | ABCabcCBAcbaA+CabcCBAc== |
| Secret | Chave de acesso de parceiro | XxXxeWT0tjAY0xr0oxX0XxNxHElr0T xxK0xlQir0e00= |
JWT de Empresa
| CAMPO | DESCRIÇÃO | EXEMPLO |
|---|---|---|
| iat | Horário atual no formato timestemp fuso 0 | 1765997468 |
| exp | Horário atual no formato timestemp fuso 0 + 120 segundos | 1765997468 |
| sub | CNPJ da Empresa | 99999999999999 |
| partnerKey | A Chave de parceiro fornecida pelo InvoiCy. | ABCabcCBAcbaA+CabcCBAc== |
| Secret | Chave de acesso da empresa | A1b2C3d4E5f6G7h8I9/j10K11l12M13n |
A conversão da data/hora para o formato timestamp Unix pode ser realizada facilmente por meio de conversores online, como o Epoch Converter.
Em seguida, acesse a seção "JWT Verify Signature", que tem como intuito garantir a integridade e a autenticidade do token. No campo editável desta seção, é obrigatório inserir a chave de acesso privada (Secret) correspondente, que é a chave privada fornecida pelo InvoiCy.
Esta chave privada, se refere a chave de acesso da empresa. No entanto, para a geração de um token para cadastro de empresa, a chave a ser utilizada é a chave de acesso do parceiro. Ambas as chaves podem ser localizadas ao clicar em "Dados da Empresa", no "Painel de Controle" do InvoiCy.
Ressaltando que, para a consulta de empresa, é necessário utilizar sempre a chave de acesso da empresa.
Com o preenchimento correto das informações nas seções "Decoded Payload" e "JWT Verify Signature", o JWT será gerado automaticamente no painel "JSON Web Token (JWT)". Este código é o que deve ser enviado para o InvoiCy.
O envio do JWT é realizado através da opção "Gerar Token", geralmente utilizando uma ferramenta de testes de API como o Postman, fazendo referência ao projeto de exemplo disponibilizado aqui. O JWT gerado deve ser incluído na requisição, no campo denominado "token".
É importante salientar que, o sistema parceiro precisa realizar o envio do JWT para o InvoiCy em no máximo 120 segundos, devido à limitação temporal definida pelo parâmetro exp no "Decoded Payload".
Após o envio bem-sucedido do JWT, o InvoiCy retornará dois tokens essenciais que serão utilizados para autenticar todas as requisições de envio de documentos, sendo elas:
- accessToken: O token principal de acesso, utilizado nas chamadas de API.
- refreshToken: Utilizado para obter um novo accessToken após a expiração do atual, evitando a necessidade de gerar um novo JWT inicial.
Para mais informações sobre a aplicação e o ciclo de vida do accessToken e do refreshToken, clique aqui.