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 o agendamento 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 o agendamento 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 o agendamento e a 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:

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:

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.

Gere a estrutura do arquivo XML de agendamento

Primeiramente, é necessário agendar a exportação dos documentos desejados, para, em seguida, realizar o download dos mesmos.

Clique aqui para visualizar um exemplo de XML com os parâmetros. Estão disponíveis três opções de agendamento, mas deve-se optar por apenas um dos modelos. É possível ainda solicitar uma exportação 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 exportação, é permitido informar uma faixa de até 100 mil documentos. Clique aqui para efetuar o download de um exemplo da estrutura desse layout.

– 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 exportação, 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.

Destacando que nesse modelo 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 exportação, 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 clique aqui.

Destacando que nesse modelo 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 exportação por requisição ao Web Service, caso seja informada mais de uma o sistema irá buscar os documentos pela primeira forma encontrada, seguindo a ordem descrita acima.

– Status do documento: Juntamente com as formas de exportação listadas acima, é possível ainda filtrar pelo status específico do documento, informando na tag <StatusDocumento> 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 exportação. 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 exportação na linguagem PHP clique aqui.

– Resumo dos documentos: caso no momento da exportação 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 agendamento do protocolo como exemplificado no tópico a seguir, serão retornadas as principais informações dos documentos, e dependendo dos parâmetros enviados poderá retornar ou não o arquivo XML. Clique aqui para visualizar um exemplo de retorno do resumo dos documentos.

Realize a leitura do retorno do agendamento

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

Como nesse Web Service a exportação dos documentos será em lotes, ao efetuar o agendamento 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 realizar o agendamento de exportação dos documentos, deverá retornar a mensagem ‘100 – Lote agendado com sucesso. Realize a consulta dos protocolos posteriormente’, acompanhada do número do protocolo e da data/hora recomendada para a próxima consulta.

Recomenda-se somente realizar a consulta do protocolo após o prazo estabelecido na tag <ProxConsultaProtocolo>, 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 o número do protocolo, envie o layout específico para consulta, incluindo o CNPJ da empresa e o número do protocolo para download, conforme ilustrado na imagem a seguir. Clique aqui para fazer download desse exemplo.

O envio da consulta do 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 será retornada a mensagem ‘100 – Protocolo processado‘, e um arquivo .zip convertido para base64, contendo os arquivos XML para download. 

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 disponível para download, ao realizar a consulta irá retornar a mensagem ‘102 – Protocolo não liberado‘, acompanhada de um horário aproximado para 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.