2014
Consultando um Documento (NF-e, NFC-e, MDF-e ou CT-e)
7 de março de 2014Olá! Neste artigo descrevemos como é realizada a consulta de documento através do InvoiCy.
A consulta de um documento permite obter o status atual de qualquer documento (NF-e, NFC-e, MDF-e, CT-e, etc), além de suas principais informações, juntamente com o PDF e o XML do mesmo. É possível também consultar documentos que não foram efetivados ou que não foram emitidos pelo InvoiCy. Neste caso, é necessário informar a chave de acesso do documento no momento do consumo do Web Service.
Caso seja executada uma consulta de um documento que não existe na base de dados do InvoiCy, o usuário receberá o retorno: 117 – Nenhum documento localizado na base de dados.
A partir deste momento assumimos que você já leu o artigo “Integrando com o InvoiCy”. Caso ainda não tenha lido este artigo, recomendamos a sua leitura para facilitar o entendimento deste artigo.
1. Gere a estrutura do arquivo XML de consulta
Através da consulta, é possível buscar informações de vários documentos em apenas uma requisição.
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.
2015-09-10T00:00:01
2015-09-11T23:59:00
– Por série: Informar apenas a série utilizada pela empresa, onde será retornada a numeração do último documento emitido para a respectiva série.
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 <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.
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.
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.
2. Consuma o Web Service de envio de documentos do InvoiCy
Após a geração do XML dos 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. Caso for consultado algum documento que não esteja no InvoiCy, será retornado apenas o seu status perante a SEFAZ.
Disponibilizamos um exemplo de XML de retorno, clique aqui para fazer o download.
O base 64 do XML e do DANFE/DACTE retornado estarão codificados em UTF-8. Este mesmo padrão deve ser utilizado para a decodificação e geração dos respectivos arquivos.
Destacando que o limite de documentos retornados na consulta é de 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.
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.
Para mais informações sobre esse processo, leia o artigo Bloqueio do Web Service no InvoiCy.
Artigos Relacionados: