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

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.

Para facilitar seu entendimento criamos uma documentação com todas as integração no Postman, clique aqui para acessá-la.

Ao clicar na opção LANGUAGE, você pode selecionar a linguagem desejada para gerar exemplos de integração, onde será montado o código com a requisição de acordo com a linguagem selecionada.

IMPORTANTE: os arquivos enviados na integração Rest seguem os layouts de emissão específicos de cada módulo do InvoiCy, a estrutura desses campos não sofreu nenhuma alteração. Para facilitar seu entendimento, disponibilizamos abaixo o layout de envio de cada módulo:

• Layout de envio módulo NF-e e NFC-e
• Layout de envio módulo CT-e
• Layout de envio módulo MDF-e
• Layout de envio módulo NFS-e

Para o cadastro de empresas também deve-se seguir o layout de integração:

• Cadastro de empresas