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

Última atualização em: 10 de junho, 2020

O InvoiCy permite que os clientes façam a integração via API Rest para efetuar o envio de documentos, por enquanto para os módulos NF-e/NFC-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.

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.
  • 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.
  • 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 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. Quando expirar o refreshToken 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. 

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:

Verifique se sua empresa está apta para entrar em produção

Última atualização em: 07 de janeiro, 2015

Antes de realizar o checklist abaixo, é importante o Parceiro realizar a leitura da documentação no Portal, através do link http://desenvolvedores.migrate.com.br/modulo-nfs-e/.

Analisar as particularidades dos padrões que serão utilizados pelos seus clientes:
http://desenvolvedores.migrate.com.br/padroes-nfs-e/

Abaixo segue os testes mínimos necessários para ser considerado apto a iniciar o processo em Produção no módulo NFS-e.

Para emissão normal seguir os passos abaixo:

Cadastrar mais de uma empresa:

– Gerar XML de Envio:
http://desenvolvedores.migrate.com.br/2014/03/27/gerar-xml-de-envio-passoapasso

– Autorizar um documento:
http://desenvolvedores.migrate.com.br/2014/03/25/emitir-uma-nfs-e/

– Realizar a consulta de um documento:
http://desenvolvedores.migrate.com.br/2014/03/25/consultar-uma-nfs-e/

– Cancelar um documento:
http://desenvolvedores.migrate.com.br/2014/03/26/cancelar-uma-nfs-e/

– Testar a emissão com Itens (preencher a tag ListaItens e a tag de Serviço de Maneira adequada)
– Testar a emissão com um Lote (5 RPSs ou mais)
– Seguir o fluxo no processo síncrono e assíncrono

Algumas particularidades deste módulo:

– Padrões que utilizam arquivos, seguir o seguinte procedimento:
http://desenvolvedores.migrate.com.br/2014/03/27/integracao-com-padroes-que-utilizam-arquivos/

– A empresa deve verificar o fluxo atual de seus clientes, e realizar testes de emissão de acordo com o fluxo de cada um de seus clientes.

Exemplos:

– Empresa emite NFS-e com ISS Retido. Deverá testar a emissão de NFS-e com ISS Retido.
– Empresa emite NFS-e sem ISS Retido. Deverá testar a emissão de NFS-e sem ISS Retido.
– Verificar códigos de tributação da empresa no município, e realizar testes utilizando os códigos reais, simulando o dia-a-dia da empresa.
OBS: Essas são regras de negócio que só o parceiro terá conhecimento, e será de sua inteira responsabilidade testá-las e aprová-las em seu ERP.

Verifique se sua empresa está apta para entrar em produção

Última atualização em: 07 de janeiro, 2015

Antes de realizar o checklist abaixo, é importante o Parceiro realizar a leitura da documentação no Portal, através do link http://desenvolvedores.migrate.com.br/modulo-mdf-e/.

Abaixo segue os testes mínimos necessários para o Parceiro ser considerado apto para iniciar o processo em Produção no módulo MDF-e.

Para emissão normal seguir os passos abaixo:

– Autorizar um documento:
http://desenvolvedores.migrate.com.br/2014/04/01/enviando-um-mdf-e-2/

– Encerrar um documento:
http://desenvolvedores.migrate.com.br/2014/07/03/encerrando-um-mdf-e

– Realizar a consulta de um documento:
http://desenvolvedores.migrate.com.br/2014/03/07/consultando-um-documento-nf-e-ou-nfc-e/

– Cancelar um documento:
http://desenvolvedores.migrate.com.br/2014/04/02/cancelando-um-mdf-e-2/

Algumas particularidades deste módulo:

– Incluir um novo condutor para MDF-e já autorizado:
https://testemigrate.wordpress.com/2014/07/03/evento-de-inclusao-de-condutor

– A empresa deve verificar o fluxo atual de seus clientes, e realizar testes de emissão de acordo com o fluxo de cada um de seus clientes.

Exemplos:

– Se o cliente realiza transportes interestaduais entre mais de um Estado, deve testar emissão de MDF-e com informação de Percurso.
– Se o cliente referencia NF-e em seu MDF-e, deve testar a emissão referenciando NF-e.
– Se o cliente referencia CT-e em seu MDF-e, deve testar a emissão referenciando CT-e.
OBS: Essas são regras de negócio que só o parceiro terá conhecimento, e será de sua inteira responsabilidade testá-las e aprová-las em seu ERP.

Verifique se sua empresa está apta para entrar em produção

Última atualização em: 07 de janeiro, 2015

Antes de realizar o checklist abaixo, é importante o Parceiro realizar a leitura da documentação no Portal, através do link http://desenvolvedores.migrate.com.br/modulo-ct-e/.

Abaixo segue os testes mínimos necessários para o Parceiro ser considerado apto para iniciar o processo em Produção no módulo CT-e.

Para emissão normal seguir os passos abaixo:

– Autorizar um documento:
https://testemigrate.wordpress.com/2014/09/16/enviando-um-ct-e

– Inutilizar um documento:
http://desenvolvedores.migrate.com.br/2014/09/16/inutilizar-um-ct-e

– Realizar a consulta de um documento:
http://desenvolvedores.migrate.com.br/2014/03/07/consultando-um-documento-nf-e-ou-nfc-e

– Cancelar um documento:
https://testemigrate.wordpress.com/2014/09/16/cancelando-um-ct-e

– Emitir uma Carta de Correção:
https://testemigrate.wordpress.com/2014/09/16/carta-de-correcao-eletronica-para-ct-e

Para emissão em contingência seguir os passos abaixo:

– Emitir um documento em contingência SVC:
https://testemigrate.wordpress.com/2014/09/16/emissao-de-ct-e-em-contingencia

Algumas particularidades deste módulo:

– A empresa deve verificar o fluxo atual de seus clientes, e realizar testes de emissão de acordo com o fluxo de cada um de seus clientes.

Exemplos:

– Se o cliente emitir com Modal Rodoviário, deve testar emissão de um CT-e utilizando modal Rodoviário.
– Se o cliente utilizar modal Aéreo, deve testar emissão de um CT-e utilizando modal Aéreo.
– Se o cliente referencia NF-e em seus CT-e, deve testar a emissão de CT-e com referência de NF-e.
OBS: Essas são regras de negócio que só o parceiro terá conhecimento, e será de sua inteira responsabilidade testá-las e aprová-las em seu ERP.

Verifique se sua empresa está apta para entrar em produção

Última atualização em: 07 de janeiro, 2015

Antes de realizar o checklist abaixo, é importante o Parceiro realizar a leitura da documentação no Portal, através do link http://desenvolvedores.migrate.com.br/modulo-nf-e/.

Abaixo segue os testes mínimos necessários para o Parceiro ser considerado apto para iniciar o processo em Produção no módulo NF-e.

Para emissão normal seguir os passos abaixo:

– Autorizar um documento:
http://desenvolvedores.migrate.com.br/2013/10/22/envio-de-nf-e-nfc-e/

– Inutilizar um documento:
http://desenvolvedores.migrate.com.br/2014/03/07/inutilizando-uma-nf-e-ou-nfc-e

– Realizar a consulta de um documento:
http://desenvolvedores.migrate.com.br/2014/03/07/consultando-um-documento-nf-e-ou-nfc-e/

– Cancelar um documento:
http://desenvolvedores.migrate.com.br/2014/03/07/cancelando-uma-nf-e-ou-nfc-e

– Emitir uma Carta de Correção:
http://desenvolvedores.migrate.com.br/2014/03/07/carta-de-correcao-eletronica-cc-e-2

Para emissão em contingência seguir os passos abaixo:

– Emitir um documento em contingência SVC:
http://desenvolvedores.migrate.com.br/2014/03/07/emissao-em-contingencia

– Emitir um documento em contingência EPEC:
http://desenvolvedores.migrate.com.br/2014/03/07/emissao-em-contingencia

Algumas particularidades deste módulo:

– A empresa deve verificar o fluxo atual de seus clientes, e realizar testes de emissão de acordo com o fluxo de cada um de seus clientes.

Exemplos:

– Se determinado cliente é do simples nacional, deverá testar emissão de notas com CST do Simples Nacional.
– Se cliente é do Regime Normal, deverá testar emissão de notas com CST do Regime Normal.
– Se cliente usa informação de transportador, deve testar a emissão informando o grupo do transportador.
– Se cliente vende medicamentos, deve testar emissão de documentos com tipo de produto = medicamento.
OBS: Essas são regras de negócio que só o parceiro terá conhecimento, e será de sua inteira responsabilidade testá-las e aprová-las em seu ERP.

Integração com Padrões que utilizam arquivos – Antigo

Última atualização em: 31 de março, 2016

 

Alguns padrões adotados pelas prefeituras utilizam arquivos para a integração, e o fluxo de emissão fica um pouco diferente dos demais que utilizam a integração via Web Service. A seguir é detalhado um passo-a-posso desse fluxo:

     1. Enviando o RPS para o InvoiCy NFS-e
A primeira etapa é enviar o XML para o InvoiCy NFS-e. Este XML conterá os dados da NFS-e, da mesma forma como os outros padrões que se comunicam via web service. Não há diferenças na primeira etapa, basta enviar o XML para o web service de Recepção do RPS.

     2. Adquirindo o arquivo com o Lote de RPS da Prefeitura
Nos padrões que utilizam arquivo como integração será retornado duas tags extras <ArquivoTXT> e <ExtensaoArquivo>. A tag “ArquivoTXT” conterá o arquivo em Base64 que deverá ser decodificado e transformado em arquivo e a tag “ExtensaoArquivo” conterá a extensão do arquivo. Para informações de como decodificar o conteúdo da tag em arquivo ver o artigo Exemplo de decodificação de base64 para arquivo.

     3. Enviando o arquivo para a prefeitura
Para enviar o arquivo para a prefeitura é necessário acessar o Portal da NFSE da mesma. Dentro do portal haverá uma opção para importar o arquivo. A localização desta opção muda de padrão para padrão, por exemplo, no SigCORP TXT a opção está em NFS-e e depois Enviar Arquivo (Lote), conforme imagem abaixo:

img_sistema_integracao

Após o upload, a prefeitura irá validar, importar os RPSs e transforma-los em NFS-e.

     4. Obtendo o retorno da Prefeitura
Para completar o fluxo com o InvoiCy NFS-e e efetivar o RPS (ou cancelar, caso a prefeitura tenha essa opção), é necessário obter o arquivo de retorno da prefeitura, que conterá as NFS-e. Como exemplo, no SIGCorp TXT, basta ir em Movimento, selecionar o período, ir em Serviços Prestados / Ferramentas NF-e e clicar em Exportar Notas Emitidas, conforme imagem abaixo:

img_sistema_integracao_ii

     5. Enviando o retorno da prefeitura para o InvoiCy NFS-e
Para enviar o arquivo com as NFS-e para o InvoiCy NFS-e, utiliza-se o mesmo web service para o Envio do RPS. A diferença nesse caso é que o XML deve conter apenas o Cabeçalho e as tags <ArquivoTXT> e <ExtensaoArquivo>. A tag <ArquivoTXT> preenchida com o arquivo da prefeitura codificado em Base64 e a tag <ExtensaoArquivo> com a extensão do arquivo. O InvoiCy NFS-e irá realizar o processamento necessário para o padrão e retornar o status do mesmo

 

Notas Rejeitadas
Os padrões com arquivo não costumam ter notas rejeitadas. Isso se dá pelo fato de que a validação ocorre na prefeitura, o InvoiCy NFS-e apenas gera o arquivo a ser enviado para a prefeitura. Caso o RPS seja rejeitado na prefeitura, ele normalmente não é importado (pode variar de padrão para padrão), e o retorno da prefeitura não irá contemplar aquelas notas que foram rejeitadas pela prefeitura. Caso algum RPS no arquivo esteja inválido, pode-se corrigir o RPS e repetir os passos 1 a 3.

 

Cancelamento de notas fiscais
O cancelamento no InvoiCy NFS-e, se dá de 3 formas:

1. Quando uma nota é cancelada na prefeitura, deve-se repetir o procedimento n° 4, pois no retorno da prefeitura conterá o status da nota (cancelada ou efetivada).

2. Através do web service de Cancelamento, no qual a nota será marcada como cancelada apenas no InvoiCy NFS-e.

3. Através da opção Cancelar NFS-e via interface web do InvoiCy NFS-e, o qual também apenas irá marcar a nota como cancelada. Os itens 1 e 2 funcionam dessa maneira pois não há comunicação direta com a prefeitura.

Artigos Relacionados:

Integrando com o módulo NFS-e – Antigo

Última atualização em: 31 de julho, 2014

 

A integração de seu ERP com o InvoiCy NFS-e deve ser realizada através de Web Service disponibilizado pelo InvoiCy. Este Web Service é único, e deve ser utilizado para qualquer emissão com o InvoiCy, independente da prefeitura que se deseja enviar. Abaixo, detalhamos o processo de integração com o módulo NFS-e.

  • Visualize a estrutura WSDL do Web Service.

Para visualizar a estrutura WSDL do Web Service, basta copiar e colar o link do Web Service em seu navegador de internet, por exemplo https://gnfse.gnfe.com.br/apnuc134.aspx?wsdl. Assim podemos visualizar toda a estrutura do WSDL, conforme demonstra a imagem abaixo:

  • Realize o consumo do Web Service.

Você deverá realizar o consumo do Web Service para realizar a integração. Dentro da TAG <nfse:Entradaxml>, você deverá informar o conteúdo XML da NFS-e, contendo a estrutura de campos. Os campos da NFS-e devem estar convertidos para formato texto, conforme exemplo abaixo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp. Para facilitar seu entendimento, disponibilizamos para você o download de um exemplo completo de consumo dos Webservices do InvoiCy (Schemas XSD e XMLs de Exemplo). RecepcaoRPS.zip

  •  Realize a leitura do retorno do envio da NF-e.

Após o envio da NFS-e, precisamos realizar a leitura do retorno do processamento do documento. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do envio de apenas um único documento. Note que na TAG <EspelhoRPS> é retornado o “espelho” do RPS, codificado em Base64. Agora que você já realizou sua integração, podemos dar prosseguimento ao próximo passo. Seu próximo passo é: Cadastrar uma Empresa via Web Service

Artigos Relacionados:

Integração com Padrões que utilizam arquivos

Última atualização em: 05 de julho, 2017

 

Alguns padrões adotados pelas prefeituras utilizam arquivos para a integração, e o fluxo de emissão fica um pouco diferente dos demais que utilizam a integração via Web Service. A seguir é detalhado um passo-a-posso desse fluxo:

     1. Enviando o RPS para o módulo NFS-e
A primeira etapa é enviar o XML para o módulo NFS-e. Este XML conterá os dados da NFS-e, da mesma forma como os outros padrões que se comunicam via web service. Não há diferenças na primeira etapa, basta enviar o XML para o web service de Recepção do RPS. A imagem abaixo mostra um exemplo do XML de Envio.

     2. Adquirindo o arquivo com o Lote de RPS da Prefeitura
Nos padrões que utilizam arquivo como integração será retornado conteúdo nas duas tags: <Arquivo> e <ExtensaoArquivo>. A tag “Arquivo” conterá o arquivo em Base64 que deverá ser decodificado e transformado em um arquivo e a tag “ExtensaoArquivo” conterá a extensão do arquivo. Para informações de como decodificar o conteúdo da tag em arquivo ver o artigo Exemplo de decodificação de base64 para arquivo.

     3. Enviando o arquivo para a prefeitura
Para enviar o arquivo para a prefeitura é necessário acessar o Portal da NFSE da mesma. Dentro do portal haverá uma opção para importar o arquivo. A localização desta opção muda de padrão para padrão, por exemplo, no SigCORP TXT a opção está em NFS-e e depois Enviar Arquivo (Lote), conforme imagem abaixo:

img_sistema_integracao
Após o upload, a prefeitura irá validar, importar os RPSs e transforma-los em NFS-e.

     4. Obtendo o retorno da Prefeitura
Para completar o fluxo com o módulo NFS-e e efetivar o RPS (ou cancelar, caso a prefeitura tenha essa opção), é necessário obter o arquivo de retorno da prefeitura, que conterá as NFS-e. Como exemplo, no SIGCorp TXT, basta ir em Movimento, selecionar o período, ir em Serviços Prestados / Ferramentas NF-e e clicar em Exportar Notas Emitidas, conforme imagem abaixo:

img_sistema_integracao_ii

     5. Enviando o retorno da prefeitura para o InvoiCy NFS-e

Para enviar o arquivo com as NFS-e para o InvoiCy, utiliza-se o mesmo web service para o Envio do RPS. A diferença nesse caso é que o XML deve conter apenas o Cabeçalho e as tags <Arquivo>,<ExtensaoArquivo>,<CNPJ_Prest> e <tpAmb>. A tag <Arquivo> preenchida com o arquivo da prefeitura codificado em Base64, a tag <ExtensaoArquivo> com a extensão do arquivo, <CNPJ_Prest> com o CNPJ da Empresa e a tag <tpAmb> com o Tipo de Ambiante: 1-Produção e 2-Homologação. O InvoiCy irá realizar o processamento necessário para o padrão e retornar o status do mesmo.

Veja um exemplo de upload.

Notas Rejeitadas

Os padrões com arquivo não costumam ter notas rejeitadas. Isso se dá pelo fato de que a validação ocorre na prefeitura, o InvoiCy apenas gera o arquivo a ser enviado para a prefeitura. Caso o RPS seja rejeitado na prefeitura, ele normalmente não é importado (pode variar de padrão para padrão), e o retorno da prefeitura não irá contemplar aquelas notas que foram rejeitadas pela prefeitura. Caso algum RPS no arquivo esteja inválido, pode-se corrigir o RPS e repetir os passos 1 a 3.

Cancelamento de notas fiscais
O cancelamento no InvoiCy NFS-e, se dá de 2 formas:

1. Quando uma nota é cancelada na prefeitura, deve-se repetir o procedimento n° 4, pois no retorno da prefeitura conterá o status da nota (cancelada ou efetivada).

2. Através do web service de Cancelamento, no qual a nota será marcada como cancelada apenas no InvoiCy.

Artigos Relacionados:

Como integrar com o módulo NFS-e?

Última atualização em: 25 de agosto, 2014

A integração de seu ERP com o Módulo deve ser realizada através de Web Service disponibilizado pelo Módulo. Este Web Service é único, e deve ser utilizado para qualquer emissão com o Módulo, independente da prefeitura que se deseja enviar. Abaixo, detalhamos o processo de integração com o módulo NFS-e.

  • Visualize a estrutura WSDL do Web Service

Para visualizar a estrutura WSDL do Web Service, basta copiar e colar o link em seu navegador de internet, por exemplo https://homolog.invoicy.com.br/arecepcao.aspx?wsdl. Assim podemos visualizar toda a estrutura do WSDL, conforme demonstra a imagem abaixo:

  • Realize o consumo do Web Service

Você deverá realizar o consumo do Web Service para realizar a integração. Dentro da TAG , você deverá informar o conteúdo XML do RPS, contendo a estrutura de campos. Os campos do RPS devem estar convertidos para formato texto, conforme exemplo abaixo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “<”, “>” e “”” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar seu entendimento, disponibilizamos para você o download de um exemplo completo de consumo dos Web Services do Módulo (Schemas XSD e XMLs de Exemplo). Clique aqui para realizar o download deste exemplo.

  •  Realize a leitura do retorno do envio do RPS.

Após o envio dos RPS, precisamos realizar a leitura do retorno do processamento do documento. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do envio de apenas um único documento. Note que na TAG < DocPDFBase64> é retornado o “espelho” do RPS, codificado em Base64.

Agora que você já realizou sua integração, podemos dar prosseguimento ao próximo passo.

Seu próximo passo é: Como emitir uma NFS-e?

Artigos Relacionados: