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

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?wsdl.
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; 18 – Resumo.

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.