jun
10
2020

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

Atualizado em

Í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.

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.

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

Artigos relacionados:

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:

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

Mais informações