2022
Consultar quantidade de documentos emitidos via Web Service
31 de janeiro de 2022Olá! 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:
![](https://desenvolvedores.migrate.info/wp-content/uploads/2022/01/estrutura-ws-consulta-bilhetagem-1-1024x445.jpg)
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.
![](https://desenvolvedores.migrate.info/wp-content/uploads/2022/01/chave-de-acesso-do-parceiro-1-1-1024x240.jpg)
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:
![](https://desenvolvedores.migrate.info/wp-content/uploads/2022/01/estrutura-soap-envio-1.jpg)
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.
![](https://desenvolvedores.migrate.info/wp-content/uploads/2022/01/layout-consulta-bilhetagem.jpg)
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.
![](https://desenvolvedores.migrate.info/wp-content/uploads/2022/01/retorno-soap-1.jpg)
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.
![](https://desenvolvedores.migrate.info/wp-content/uploads/2022/01/retorno-consulta-bilhetagem.jpg)
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.