Integração via API Rest para emissão de documentos

Índice

1. Índice

O InvoiCy permite que os clientes façam a integração via API Rest para efetuar o envio de documentos, para os módulos NF-e/NFC-e, CT-e, MDF-e e NFS-e. Além da emissão para esses módulos, também é possível efetuar o envio de eventos, inutilização, descarte e consultas de documentos, e ainda realizar o cadastro de novas empresas e a exportação de documentos.

Para realizar a integração com as APIs o primeiro passo é se autenticar para que o InvoiCy possa garantir a segurança da origem da comunicação. Para isso, será necessário gerar um token de autenticação no padrão JWT (RFC – 7519), e enviar para a rota {{host}}/oauth2/invoicy/auth. Abaixo é detalhado como deverá ser gerado esse token:

O host varia por ambiente sendo homologação https://apibrhomolog.invoicy.com.br e produção https://apibr.invoicy.com.br/.
O parâmetro “iat” é um numérico com a data de criação do token, deve ser informado a data/hora atual no fuso zero, desde a Era Unix.
O parâmetro “exp” é um numérico com a data de expiração do token, nele deve ser informado a data/hora atual no fuso zero, desde Era Unix, mais 120 segundos, resultando o tempo de expiração no formato timestamp. O tempo de expiração do token deverá ser no máximo de 120 segundos.
O parâmetro “sub” é uma string com o CNPJ da empresa ou a chave de parceiro. Quando for gerado um token para cadastro/atualização de empresa deverá conter a chave de parceiro nesse caso, no restante das situações será utilizado o CNPJ da empresa. Mas atenção, quando for gerado um token para integração com a extensão InvoiCy Tax Template, o parâmetro “sub” também deve ser preenchido com a chave de parceiro.
O parâmetro “partnerKey” é uma string com a chave de parceiro fornecida pelo InvoiCy. Quando for gerado um token para cadastro de empresa, não enviar essa informação. Quando for gerado um token para integração com a extensão InvoiCy Tax Template, o parâmetro “partnerKey” também não deve ser informado.
A chave de acesso é a chave privada fornecida pelo InvoiCy para cada empresa cadastrada. Quando for gerado um token para cadastro de empresa deverá conter a chave de acesso do parceiro nesse caso.
Obs: para consulta de empresa utilizar o token com o CNPJ e não chave de parceiro.

Tendo criado o primeiro token JWT, deverá ser enviado para a API de autenticação para obter o refreshToken e accessToken. Avaliar o exemplo “Gerar Token” que está na documentação do Postman descrita abaixo.

O refreshToken será utilizado para criar um novo accessToken válido quando o mesmo expirar, a cada 1 hora. Quando expirar o refreshToken após 24 horas, será necessário realizar o mesmo processo descrito acima para obter um novo token válido. Avaliar o exemplo “Refresh Token” que está na documentação do Postman descrita abaixo.

O accessToken deverá ser enviado no header “Authorization” em todas as requisições de documentos ou empresa.