Consultar quantidade de documentos emitidos via Web Service

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, homolog.invoicy.com.br/aconsultabilhetagem.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 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 Parceiros, 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.

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.

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.