Consultar quantidade de documentos emitidos via Web Service

Última atualização em: 09 de janeiro, 2017

 

Olá! Neste artigo vamos lhe auxiliar a realizar a integração do seu ERP com o novo Web Service disponibilizado para consultar a quantidade de documentos emitidos pela sua empresa no InvoiCy. Pronto para iniciar? Então vamos lá!

A Plataforma InvoiCy disponibiliza de um novo Web Service para efetuar a consulta da quantidade de documentos emitidos pela sua empresa, dentro de um determinado período. 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 aconsultabilhetagem.aspx. Este Web Service é único e deve ser utilizado apenas para efetuar a consulta da quantidade de documentos emitidos por sua empresa no InvoiCy, independente do tipo de documento que se deseja consultar. Abaixo, detalhamos o processo de integração com esse Web Service.

Para realizar a integração siga 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, https://homolog.invoicy.com.br/aconsultabilhetagem.aspx. 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 proporcionar segurança à comunicação. Consulte o artigo “Como gerar o código Hash MD5?” para mais informações.

Por questões de segurança, ao invés de utilizar a chave de acesso para gerar a chave de comunicação deverá ser utilizada a Chave de acesso do parceiro, que estará disponível na tela de Módulos contratados, apenas para usuários Administrador ou Parceiro. A imagem a seguir demonstra a localização dessa nova chave.

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 ao executar uma consulta de documentos. Seu preenchimento é obrigatório para efetuar uma consulta, mas especificamente para esse tipo de consulta da quantidade de documentos não é obrigatório.

Dentro da TAG <inv:Documento>, você deverá informar o conteúdo XML da 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 exemplo SOAP exibido na imagem.

3. Gere a estrutura do arquivo XML de consulta

Para efetuar a consulta da quantidade de documentos emitidos pela empresa, deve-se informar os seguintes parâmetros na estrutura do XML:

– Modelo do documento: NF-e, NFC-e, CT-e, MDF-e, CF-e SAT, NFS-e

– Tipo do ambiente: 1 – Produção; 2 – Homologação

– Tipo da consulta: 1 – Acumulado: ao informar esse tipo de consulta será necessário definir se deseja obter os documentos acumulados apenas do dia anterior ou os documentos acumulados do mês, até o dia anterior; 2 – Período: será necessário informar o período desejado para a consulta, respeitando o limite de 3 meses.

– Acumulado: Ao optar pelo tipo de consulta 1 – Acumulado, deverá escolher a forma da consulta, 1 – Do dia anterior: a consulta irá retornar apenas os documentos acumulados do dia anterior; 2 – Do mês: a consulta irá retornar os documentos acumulados do mês, até o dia anterior.

É importante destacar que ao realizar uma consulta acumulada do mês (até o dia anterior) no dia 01/11, por exemplo, irá retornar os documentos do mês anterior, ou seja, do mês de outubro.

Se a consulta for acumulada do dia anterior, no dia 01/12, por exemplo, irá retornar apenas os documentos do dia 30/11.

Já ao executar uma consulta acumulada do dia anterior, ou acumulada do mês (até o dia anterior) no dia 02/12, irá retornar apenas os documentos do dia 01/12.

Data de Inclusão Inicial: quando o tipo de consulta for por Período deverá informar a data inicial da consulta.

Data de Inclusão Final: quando o tipo de consulta for por Período deverá informar a data final da consulta, que deverá ser menor que a data atual e o período não poderá ultrapassar o limite de 3 meses.

CNPJ do Emissor: ao efetuar a consulta o usuário poderá obter o retorno dos documentos de uma empresa específica, então deverá informar o CNPJ dessa empresa. É possível também efetuar a consulta para mais de uma empresa ao mesmo tempo, basta informar os CNPJ correspondentes a cada empresa. Caso nenhum CNPJ seja informado a consulta será realizada para todas as empresas do Parceiro, que possuem licença ativa para o módulo consultado.

A imagem a seguir demonstra a estrutura do layout XML de envio para consulta.

Layout consulta Bilhetagem

Clique aqui para visualizar um exemplo do XML com os parâmetros para consulta.

Para facilitar seu entendimento disponibilizamos um exemplo do layout de envio em Excel, clique aqui para fazer o download.

4. Realize a leitura do retorno do envio

Após o envio da consulta de quantidade dos documentos, precisamos realizar a leitura do retorno do processamento dessa requisição. O retorno recebido segue a seguinte estrutura SOAP.

Para fazer download do arquivo SOAP exibido na imagem clique aqui. A estrutura SOAP acima demonstra o retorno da consulta de documentos de apenas uma única empresa.

Abaixo demonstramos a estrutura do XML de retorno da consulta.

Retorno consulta Bilhetagem

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.

Consultar pulos de numeração

Última atualização em: 05 de agosto, 2016

 

Buscando facilitar para os usuários efetuarem o controle dos documentos emitidos por suas empresas, disponibilizou-se no InvoiCy um novo layout de integração para consulta dos pulos de numeração, onde será possível identificar falhas no sequencial da numeração de documentos emitidos para todos os módulos.

Os principais motivos que podem ocasionar falhas no sequencial de envio dos documentos são:

– Documentos emitidos que ainda não estão com status: Autorizado, Cancelado, Inutilizado ou Denegado;

– Pulo de numeração no aplicativo emissor;

– Falha do aplicativo emissor no envio do documento;

– Documentos emitidos que permanecem com status: Pendente, Rejeitado, Contingência Offline, Em conflito, EPEC ou Necessita interação.

O seu primeiro passo é enviar via Web Service o novo layout de integração para efetuar a consulta dos pulos de numeração. A imagem abaixo demonstra a estrutura do layout, onde deve-se informar o CNPJ do emitente, CNPJ da empresa, modelo do documento, tipo de ambiente, série e data de emissão inicial e final, não podendo ultrapassar o período de 31 dias. Clique aqui para efetuar download de um exemplo desse layout.

 

Após efetuar o envio do layout para consulta dos pulos de numeração, deverá retornar o código 100 – Pulos de numeração processados, se o processo foi executado com sucesso. O retorno da consulta segue a seguinte estrutura SOAP.

Para fazer download do XML exibido na imagem clique aqui.

No retorno da consulta irá conter o CNPJ do emissor, modelo e série do documento consultado, Quantidade de pulos de numeração, juntamente com a especificação da sequência dos números que estão faltando, e ainda o código e descrição do retorno.

Caso não encontre pulos de numeração para o período informado, irá retornar a mensagem: 100 – Nenhum pulo de numeração encontrado.

Para facilitar seu entendimento, disponibilizamos também um documento que especifica o layout dos XMLs que devem ser gerados, clique aqui para fazer o download.

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

Última atualização em: 13 de fevereiro, 2017

 

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, com o objetivo de agilizar o processo de exportação dos documentos 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, independente do tipo de documento que se deseja exportar. 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. 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.

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.

Consulta Protocolo

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

Caso no momento da consulta você optar por retornar o resumo dos documentos, tag 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 acima, serão retornadas as principais informações dos documentos, juntamente com seu arquivo XML e PDF. Clique aqui para visualizar um exemplo de retorno do resumo dos documentos.

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.

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.

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.

Consulta de CF-e SAT autorizados e cancelados no InvoiCy via WS

Última atualização em: 06 de maio, 2016

 

Neste artigo iremos descrever como é realizada a consulta de arquivos XML autorizados ou cancelados via CF-e-SAT na Plataforma InvoiCy.

A partir deste momento assumimos que você já leu o artigo Sistema Autenticador e Transmissor de Cupons Fiscais Eletrônicos (CF-e-SAT). 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 a consulta de um arquivo XML emitido via CF-e-SAT.

1. Gere a estrutura do arquivo XML de consulta

Clique aqui para visualizar um exemplo de XML com os parâmetros para consulta. Deve-se optar por apenas uma das formas de consulta a seguir:

– Por faixa de numeração: Deve informar o número inicial e final, juntamente com a série do documento.

– Pela chave de acesso: Informar apenas a chave de acesso do documento, obrigatório caso ocorra a consulta de um documento que não esteja na base de dados do InvoiCy. Neste caso o sistema irá consultar seu status junto a SEFAZ.

– Intervalo de datas: A data inicial e a data final deverão ser preenchidas, juntamente com o horário. 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.

<DataEmissaoInicial>2015-09-10T00:00:01</DataEmissaoInicial>

<DataEmissaoFinal>2015-09-11T23:59:00</DataEmissaoFinal>

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.

Destacando que no momento de realizar uma consulta a tag <dhUF> não deve ser informada. Esta deverá ser usada apenas quando se deseja consultar o status de serviço da SEFAZ.

É possível também escolher quais as informações 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 XML que devem ser gerados, clique para fazer o download.

2. Consuma o Web Service de envio de documentos do InvoiCy

Após a geração do XML de parâmetros de consulta e do XML dos parâmetros de retorno, o próximo passo é realizar o consumo do Web Service de recepção do InvoiCy.

O XML dos parâmetros de consulta deve estar na tag “Documento”; o XML dos parâmetros de retorno deve estar na tag “Parametros”. Ambos convertidos para texto, como mostra a imagem abaixo:

Clique aqui para fazer download do XML exibido na imagem.

Para a geração do código hash informado no campo “EmpCK” deve-se utilizar apenas o conteúdo da tag “Documento”. O procedimento para a geração do hash você encontra no artigo “Gerando o hash MD5“.

3. Obtenha o retorno da consulta

Os dados do retorno da consulta serão de acordo com os parâmetros informados no XML de parâmetros de retorno. Disponibilizamos um exemplo de XML de retorno, clique aqui para fazer o download.