Novo Web Service para consulta e exportação de documentos

Última atualização em: 25 de março, 2021

Olá! Neste artigo vamos lhe auxiliar a realizar a integração do seu ERP com o novo Web Service disponibilizado para consulta e exportação de documentos no InvoiCy. Pronto para iniciar? Então vamos lá!

A Plataforma InvoiCy disponibiliza de um novo Web Service para efetuar a consulta e a exportação em lote de documentos XML, com o objetivo de agilizar o processo de exportação sem interferir no funcionamento dos demais processos. Essa funcionalidade pode ser utilizada sem a necessidade de interação com a interface da Plataforma InvoiCy, pois todo o processo funciona via Web Service.

O seu ERP deve realizar a integração com o novo Web Service disponibilizado pelo InvoiCy. Trata-se do WS aexportardocumentos.aspx. Este Web Service é único, e deve ser utilizado apenas para efetuar a consulta e exportação de documentos no InvoiCy. Abaixo, detalhamos o processo de integração com esse Web Service.

Para realizar a integração, realize os seguintes passos:

1. 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, para empresas que utilizam o ambiente de homologação, utilizar o link https://consultahomolog.invoicy.com.br/aexportardocumentos.aspx.
Já para empresas que fazem uso do ambiente de produção, o link utilizado deve ser o seguinte https://consulta.invoicy.com.br/aexportardocumentos.aspx?wsdl. Assim podemos visualizar toda a estrutura do WSDL, conforme demonstra a imagem abaixo:

2. Realize o consumo do Web Service

Você deverá realizar o consumo do Web Service para efetuar a integração. Ao consumir o WS, você deverá informar os seguintes parâmetros:

• EmpPK: Chave de Parceiro disponibilizada pela Migrate para cada cliente.

Exemplo: PYcEsFuKroDBojfiFEl+Ms==

A chave de parceiro é gerada por nosso Sistema de Gestão no momento que a sua empresa é cadastrada como nosso parceiro. A mesma será enviada por e-mail e utilizada para controlar as empresas de clientes finais que utilizarão licenças adquiridas pela sua empresa.

• EmpCK: Código HASH gerado em formato MD5 de acordo com os dados enviados.

Exemplo: 213f3b55d679e790258fd811cc86d309

Utilizado para validar a comunicação e propor segurança à comunicação. Consulte o artigo “Como gerar o código Hash MD5?” para mais informações.

• EmpCO: Identificador do PDV.
• Texto: Uso interno do InvoiCy. Não é necessário o preenchimento.
• Documento: Conteúdo do XML com os parâmetros da consulta a ser enviada para o InvoiCy.
• Parâmetros: Neste campo podem ser informados alguns parâmetros, como por exemplo, quais dados deseja que retorne na consulta dos documentos. Seu preenchimento é obrigatório para efetuar a consulta.

O conteúdo das tags “Documento” e “Parametros” deve ser convertido para texto, como demonstra a imagem abaixo:

Clique aqui para fazer download do XML exibido na imagem.

3. Gere a estrutura do arquivo XML de consulta

Primeiramente deve-se efetuar a consulta dos documentos desejados, para após fazer o download desses documentos.

Clique aqui para visualizar um exemplo de XML com os parâmetros para consulta. Estão disponíveis três opções de consulta, mas deve-se optar por apenas um dos modelos para consulta. É possível ainda solicitar uma consulta com o resumo dos documentos. Veja a seguir o detalhamento de cada um desses modelos:

– Por faixa de numeração: Deve informar o número inicial e final, juntamente com a série do documento. Destacando que nesse modelo de consulta, é permitido informar uma faixa de até 100 mil documentos. Clique aqui para efetuar o download de um exemplo da estrutura desse layout de consulta.

– Intervalo de datas de emissão: A data inicial e a data final de emissão deverão ser preenchidas, juntamente com o horário, caso desejar. Ao optar por essa forma de consulta, as tags de numeração e série deverão ser preenchidas com zero, ou removidas da estrutura do layout enviado, e as tags de datas de inclusão também deverão ser removidas. Clique aqui para efetuar o download de um exemplo da estrutura desse layout de consulta.

Destacando que nesse modelo de consulta o período de datas informado não pode ultrapassar 31 dias.

2016-06-01T00:00:01
2016-06-30T23:59:00

– Intervalo de datas de inclusão: A data inicial e a data final de inclusão deverão ser preenchidas, juntamente com o horário, caso desejar. Ao optar por essa forma de consulta, as tags de numeração e série deverão ser preenchidas com zero, ou removidas da estrutura do layout enviado, e as tags de datas de emissão também deverão ser removidas. Para visualizar um exemplo da estrutura desse layout de consulta clique aqui.

Destacando que nesse modelo de consulta o período de datas informado também não pode ultrapassar 31 dias.

2016-06-01T00:00:01 2016-06-30T23:59:00

Vale ressaltar que deve-se optar por apenas uma destas opções de consulta por requisição ao Web Service, caso seja informada mais de uma o sistema irá buscar os documentos pela primeira forma de consulta encontrada, seguindo a ordem descrita acima.

– Status do documento: Juntamente com as formas de consulta listadas acima, é possível ainda filtrar pelo status específico do documento, informando na tag os possíveis status listados a seguir:

1 – Pendente; 2 – Autorizado; 3 – Rejeitado; 4 – Necessita interação; 5 – Cancelado; 6 – Inutilizado; 7 – Aguardando Consulta; 8 – Encerrado; 9 – Em Conflito; 10 – EPEC; 11 – Contingência off-line; 12 – Denegado; 13 – Contingência FS-DA.

Deve-se também escolher quais as informações que serão retornadas no momento da consulta. Para isso, é necessário gerar um XML específico que será informado na tag “parametros” do SOAP de envio. Clique aqui, para visualizar um XML de exemplo dos parâmetros de retorno.

Disponibilizamos também um documento que especifica o layout dos XMLs que devem ser gerados, clique para fazer o download.

Para acessar um exemplo de consulta na linguagem PHP clique aqui.

– Resumo dos documentos: caso no momento da consulta você optar por retornar o resumo dos documentos, tag <ResumoDocumento> preenchida como S, serão retornadas apenas as informações mais relevantes dos documentos, onde o conteúdo não será compactado e nem convertido para base64.

Nesse caso, após efetuar o processo de consulta do protocolo como exemplificado no tópico a seguir, serão retornadas as principais informações dos documentos, e dependendo dos parâmetros enviados na consulta poderá retornar ou não o arquivo XML. Clique aqui para visualizar um exemplo de retorno do resumo dos documentos.

4. Realize a leitura do retorno do envio

Após o envio da consulta para exportação dos documentos, precisamos realizar a leitura do retorno do processamento dessa requisição.

Como nesse novo Web Service a exportação dos documentos será em lotes, ao efetuar a consulta de documentos a exportação não será executada já na sequência, mas será retornado no Web Service o número de um protocolo, que deverá ser consultado posteriormente para que a exportação dos documentos seja executada.

Os lotes serão compostos por no máximo 50 arquivos. Dessa forma, se a exportação for de 100 arquivos serão gerados 2 protocolos contendo 50 arquivos cada.

Ao efetuar a consulta dos documentos deverá retornar a mensagem ‘100 – Lote agendado com sucesso. Realize a consulta dos protocolos posteriormente’, juntamente com o número do protocolo e a data/hora recomendada para realizar a próxima consulta.

Recomenda-se somente realizar a consulta do protocolo após esse prazo (tag ), pois muitas consultas irão resultar no bloqueio da requisição.

O retorno da consulta contendo o número do protocolo gerado segue a seguinte estrutura SOAP:

Para fazer download do XML exibido na imagem clique aqui.

Após receber no retorno o número do protocolo, deverá enviar o layout específico para consulta de protocolos, informando o CNPJ da empresa e o número do protocolo que deseja efetuar download, conforme demonstra a imagem a seguir. Clique aqui para fazer download desse exemplo.

O envio da consulta protocolo segue a seguinte estrutura SOAP, conforme imagem abaixo. E clicando aqui é possível fazer download desse exemplo.

Se o protocolo estiver gerado e pronto para download irá retornar a mensagem 100 – Protocolo processado, e um arquivo .zip convertido para base64, contendo os arquivos XML para download. Veja na imagem abaixo o retorno do Web Service.

Caso for gerado mais de um protocolo, ao efetuar a consulta do primeiro protocolo, no retorno do Web Service na tag < ProxProtocolo> já virá o número do próximo protocolo que deverá ser consultado.

Caso o protocolo ainda não esteja liberado para download, no momento da consulta irá retornar a mensagem 102 – Protocolo não liberado, juntamente com um horário aproximado para efetuar a próxima consulta.

Clique aqui para fazer download do XML exibido na imagem, que demonstra o retorno de um protocolo já processado.

OBSERVAÇÃO: O InvoiCy conta com um controle das requisições recebidas, onde ao receber várias vezes a mesma requisição de consulta, dentro de um determinado período de tempo, irá bloquear essa requisição para prevenir que o ERP do cliente não entre em loop e cause lentidão no sistema.

Para evitar esse bloqueio, recomenda-se que em caso de consulta de documento, deve-se adicionar um “sleep” entre uma e outra conexão, de 15 segundos, por exemplo. E também limitar o número total de consultas.

Diferença entre o novo Web Service aexportardocumentos.aspx e o Web Service arecepcao.aspx:

Vamos esclarecer bem a diferença entre realizar uma consulta pelo Web Service arecepcao.aspx ou pelo novo Web Service aexportardocumentos.aspx. Para mais informações acesse o artigo “Diferença entre o WS arecepcao.aspx e o WS aexportardocumentos.aspx“.

Web Service arecepcao.aspx:

• Forma de retorno: síncrono, ou seja, com retorno imediato, ao realizar uma consulta os documentos são retornados posteriormente.
• Limite de documentos retornados: 100 documentos, mas este valor pode ser alterado para menos, sempre em escala de 50 em 50, sendo que 50 é a menor quantidade retornada. Ao consultar uma quantidade maior que 100 documentos, a consulta não será executada e nenhum documento será retornado.
• Pode retornar tanto o arquivo XML como o PDF, de acordo com as configurações do usuário.

Web Service aexportardocumentos.aspx:

• Forma de retorno: assíncrono, ou seja, o retorno não é imediato, ao realizar uma requisição é necessário  efetuar uma consulta para obter o resultado.
• Limite de documentos retornados: Os lotes serão compostos por no máximo 50 arquivos, mas ao consultar uma quantidade maior os documentos serão retornados mesmo assim. Por exemplo, se a exportação for de 100 arquivos serão gerados 2 protocolos contendo 50 arquivos cada.
• Retorna apenas o arquivo XML dos documentos.

Acesse um exemplo de agendamento de exportação utilizando a linguagem PHP, clicando aqui.

Para mais informações sobre esse processo, leia o artigo Bloqueio do Web Service no InvoiCy.

Controle de requisições recebidas pelo InvoiCy

Última atualização em: 19 de abril, 2016

 

Buscando melhorar a usabilidade da aplicação por parte dos usuários Parceiros e evitar problemas durante a realização de uma tarefa, seja de consulta, reenvio ou cancelamento de um documento, o InvoiCy conta com um controle das requisições recebidas, em decorrência de consumo indevido do Web Service, caracterizado por um número excessivo de conexões em um curto espaço de tempo.

Esse processo consiste em bloquear uma requisição que se repita mais de ‘N’ vezes dentro de um determinado período de tempo, pois ocorriam situações onde a mesma requisição era enviada várias vezes para o InvoiCy, o que sobrecarregava a aplicação, que não conseguia processar as requisições recebidas em um tempo aceitável. Nesses casos, normalmente o ERP está em um LOOP realizando uma tarefa (consultando, reenviando, cancelando) referente a algum documento, mas excede um número razoável de conexões em um curto espaço de tempo. O bloqueio é preventivo, para que esse loop não cause lentidão no sistema.

Para que isso não aconteça é preciso revisar/programar a integração considerando que:

• Em caso de reenvio ou consulta de documento, deve-se adicionar um “sleep” entre uma e outra conexão, de 15 segundos, por exemplo.
• Limitar o número total de consultas: se o sistema realiza uma consulta a cada 30 segundos, ele fará 20 consultas em um intervalo de cinco minutos. Se ainda assim não obtiver o retorno desejado, é importante que o sistema pare o loop de consultas, e deixe para o usuário fazer a consulta manualmente, ou agende para voltar a executar depois de um intervalo maior (2-5 minutos), realizando uma nova tentativa.
• A implementação desse controle não irá impactar na forma como o usuário integra com a aplicação, onde o mesmo poderá enviar várias vezes a mesma requisição, porém após um determinado número de vezes o InvoiCy irá bloquear e não processará as requisições recebidas. Passado o período de bloqueio, essas requisições serão processadas e enviadas. É importante destacar que o InvoiCy irá bloquear apenas a requisição que foi enviada diversas vezes, e não a empresa. E o tempo de bloqueio e a quantidade de requisições será controlada por módulo.

Porém, se o usuário não seguir as recomendações acima e mesmo após a requisição ser bloqueada temporariamente continuar enviando várias vezes essa mesma requisição, o InvoiCy irá bloquear a requisição de forma permanente, onde será necessário entrar em contato com nossa equipe de suporte para efetuar o desbloqueio da requisição.

Códigos de Retorno Cadastro de Empresa via Web Service

Última atualização em: 14 de agosto, 2019

Neste artigo iremos abordar os possíveis códigos de retorno ao realizar o cadastro de uma empresa através do Web Service do InvoiCy.

Ao realizar o cadastro de uma empresa via Web Service, você usuário poderá obter os seguintes retornos:

100 – Solicitação de cadastro recebida

Ao receber esse retorno significa que a sua empresa foi cadastrada com sucesso no InvoiCy.

101 – Falha na estrutura do XML ou campos obrigatórios não preenchidos

Nessa situação a empresa não foi cadastrada, pois algum dos dados informados não estava de acordo. O usuário receberá o código 101 juntamente com o campo que não foi informado corretamente.

103 – Falha na validação do certificado digital

Esse retorno ocorre quando há uma inconformidade com o certificado digital informado para a empresa, onde a senha pode estar incorreta, a data de validade estar vencida, ou o certificado informado não corresponder a empresa que está sendo cadastrada.

104 – E-mail do usuário é inválido

No momento de cadastrar a empresa, ao informar incorretamente o e-mail do usuário será retornado o código 104.

105 – Campos nome ou senha do usuário não informados

Se ao cadastrar a empresa não for informado corretamente as informações referentes ao nome e senha do usuário será retornado o código 105.

106 – Usuário já cadastrado

Se o usuário informado no momento de cadastrar a empresa já estiver cadastrado será retornado o código 106.

107 – Usuário e senha da caixa de e-mail não informada

Ao cadastrar uma empresa pode-se também configurar uma caixa de e-mail. Será retornado o código 107 quando o usuário e senha da caixa de e-mail não forem informados corretamente.

108 – Não foi possível conectar ao servidor de e-mail informado

Esse retorno irá ocorrer quando o servidor de e-mail informado não estiver de acordo, não possibilitando o acesso ao mesmo.

109 – Empresa Matriz não encontrada

Ao cadastrar uma Filial, quando a empresa Matriz não for encontrada irá retornar o código 109 para o usuário.

115 – A raiz do CNPJ do certificado informado difere da raiz do CNPJ da empresa! O certificado foi cadastrado com sucesso

Ao realizar o cadastro de uma empresa e informar um certificado digital que tenha sua raiz de CNPJ diferente da raiz de CNPJ da empresa cadastrada, será retornada essa mensagem apenas como um aviso, mas o cadastro do certificado será efetuado com sucesso da mesma forma.

173 – Chave de comunicação ou chave de parceiro inválida

O código 173 será retornado quando a chave de comunicação ou a chave de parceiro estiverem inválidas, retornando especificamente para o usuário qual das chaves está incorreta.

Cadastrar empresa via Web Service

Última atualização em: 23 de março, 2021

Neste artigo iremos demonstrar como realizar o cadastro de uma empresa através do Web Service do InvoiCy.

A partir de agora, assumimos que você já leu o artigo Integrar com o InvoiCy NF-e. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.

O cadastramento da empresa é muito simples. Para que isso se torne possível, siga os seguintes passos:

1. Consumindo o Web Service
Primeiramente, você deve realizar o consumo do Web Service de Cadastro de empresas  – https://homolog.invoicy.com.br/arecepcao.aspx

2. Criar os XML para o envio
O XML deve ser convertido para String, porém, antes disso, deve-se gerar a chave de comunicação empCK. Mas como fazer isso se ainda não temos a chave de comunicação da empresa?

É simples. Neste caso, deve-se utilizar a chave de parceiro (EmpPK) para fazer a concatenação e posteriormente gerar a chave hash MD5.

3. Armazenar os dados de retorno
Caso a empresa seja cadastrada com sucesso, é preciso guardar o Código da Empresa no InvoiCy e a chave de acesso, informações fundamentais para a emissão com a empresa.

Para obter os Layouts de envio e retorno do Cadastro de Empresas, faça o download do arquivo CadastroEmpresa.zip. Nele você encontrará também arquivos XML de exemplo.

O documento XML deve ser convertido para texto, e inserido entre as TAGS do SOAP de envio. Veja abaixo um exemplo:

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 a geração do XML de integração, disponibilizamos o XML de envio, que poderá servir como base.

4. Realize a leitura do retorno do cadastro de Empresa
Após o envio do XML, precisamos realizar a leitura do retorno do processamento do cadastro. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do envio de apenas uma empresa.

O seu sistema deve ler o retorno, validando as informações conforme o layout de retorno. O retorno apresentará o status de cada processo, desde o cadastro da empresa, a instalação do certificado, a validação da licença e o cadastro do usuário.

Para saber mais sobre os possíveis códigos de retorno ao cadastrar uma empresa via Web Service, acesse o artigo Códigos de Retorno Cadastro de Empresa via Web Service.

Cancelando uma NF-e ou NFC-e

Última atualização em: 23 de março, 2021

Agora iremos descrever como é realizado o cancelamento de uma NF-e ou NFC-e através do InvoiCy.

A partir deste momento, assumimos que você já leu o artigo “Enviando uma NF-e ou NFC-e”. Caso ainda não tenha lido este artigo, recomendamos a sua leitura para facilitar o entendimento deste artigo.

Proceda com os seguintes passos para realizar o cancelamento de um documento:

1.      Autorize um documento
O cancelamento só pode ser feito para documentos que receberam a autorização de uso pela SEFAZ. Atente-se para o prazo de cancelamento da NF-e que pode variar para cada UF. Em caso de dúvidas, consulte a SEFAZ de seu estado para maiores informações.

2.      Gere a estrutura do arquivo XML de cancelamento
Você deverá gerar a estrutura do XML de cancelamento de uma NF-e, de acordo com o Layout de eventos da NF-e. Para visualizá-lo, consulte o artigo “Envio de Eventos”.

Nós disponibilizamos para você um exemplo da estrutura do arquivo de cancelamento para facilitar seu entendimento. Clique aqui, para realizar o download.

3.      Consuma o Web Service de envio de documentos do InvoiCy
Após gerar o layout de cancelamento da NF-e que você deseja cancelar, basta realizar o consumo do WS de integração do InvoiCy, conforme já descrito no artigo “Integrando com o InvoiCy”.

Para facilitar o seu entendimento, anexamos a este artigo um exemplo completo de cancelamento de uma NF-e através do WS de integração do InvoiCy. Clique aqui, e realize o download do documento.

4.      Obtenha o retorno do cancelamento
Ao realizar o consumo do Web Service do InvoiCy, no retorno será possível identificar se a operação foi realizada com sucesso e qual o status do documento.

O layout de retorno do Web Service para o cancelamento, assim como qualquer outro evento, é o mesmo retornado no momento da emissão da NF-e ou da NFC-e. Para os eventos, estarão preenchidas as tags específicas no retorno, como o EveTp e EveId, como mostra a imagem abaixo.

Se a empresa está emitindo em contingência e necessita realizar o cancelamento de uma NF-e ou NFC-e , o InvoiCy irá armazenar o evento do cancelamento e enviá-lo após a empresa sair da contingência e o documento ser efetivado.

O próximo passo é: Consultando uma NF-e ou NFC-e, para isso acesse o artigo e confira.

Artigos Relacionados:

• Integrando com o módulo NF-e
• Envio de eventos

Enviando uma NF-e ou NFC-e

Última atualização em: 23 de março, 2021

Neste momento iremos explicar como realizar a emissão de uma NF-e ou NFC-e integrando com o InvoiCy.

A partir de agora assumimos que você já leu o artigo “Integrando com o módulo NF-e”. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.

O envio de um documento é muito simples. Para que isso se torne possível siga os seguintes passos:

1.      Consumindo o Web Service
Primeiramente, você deve realizar o consumo do Web Service de envio de documentos do InvoiCy, conforme o artigo “Integrando com o módulo NF-e”.

2.      Gerando o documento na estrutura correta
O InvoiCy permite o envio de documentos no layout 4.00 da NF-e e também da NFC-e. Para obter esse Layout consulte o artigo “Layout 4.00”. Nele você encontra a estrutura completa do arquivo XML para gerar o documento a ser enviado ao InvoiCy.

O XML do documento deve ser convertido para texto, e inserido entre as TAGS <inv:Documento> </inv:Documento> do SOAP de envio. Veja abaixo um exemplo:

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 “>” por “&lt;” e “&gt;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar o seu entendimento anexamos a este artigo um exemplo de arquivo XML no layout da NF-e.

Clique aqui, para realizar o download do exemplo de Envio de NF-e.

Para facilitar a geração do XML de integração, disponibilizamos um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. OBS: O arquivo de esquema corresponde a versão 4.00.

Clique aqui, para realizar o download do arquivo de esquema XSD.

3.      Realize a leitura do retorno do envio
Após o envio da NF-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 <Documento> é retornado o conteúdo XML do retorno, codificado em “CDATA”. Este conteúdo pode ser lido pelo ERP para atualização do Status do documento.

Abaixo demonstramos a estrutura do XML de retorno:

Todo o conteúdo acima estará inserido em uma tag “CDATA” e retornará dentro da TAG <Documento> do SOAP de retorno.

Para facilitar seu entendimento, anexamos um exemplo do XML do retorno. Clique aqui, e realize o download.

Existe ainda uma tabela de códigos e descrições dos retornos da SEFAZ, que você pode consultar no artigo “Códigos de Retorno da SEFAZ”.

Agora que você já está familiarizado com a integração, podemos prosseguir ao próximo passo.

Seu próximo passo é:  Cancelando uma NF-e ou NFC-e

Artigos Relacionados:

• Integrando com o módulo NF-e
• Layout 4.00