Consultas
Uma consulta representa uma execução do Monitoramento.
Sempre que a Nota Gateway consulta os ambientes oficiais em busca de novos documentos fiscais, uma nova consulta é criada.
Cada consulta registra:
- quando a execução aconteceu;
- se ela foi concluída com sucesso;
- quantos documentos foram encontrados;
- o intervalo de NSUs processado.
Mesmo quando nenhum documento é encontrado, uma consulta é registrada.
Quando utilizar consultas
A maioria das integrações utiliza webhooks e nunca precisa consultar esta API.
A API de Consultas é indicada quando sua aplicação:
- não pode receber webhooks;
- precisa reprocessar documentos;
- deseja acompanhar o histórico do monitoramento;
- precisa auditar execuções anteriores.
Recuperando documentos
O fluxo de integração é simples:
Primeiro, liste as consultas executadas.
Depois, para cada consulta de interesse, recupere os documentos encontrados.
Cada documento retornado possui exatamente o mesmo formato enviado pelos webhooks.
Processamento incremental
Como cada consulta representa uma execução do monitoramento, sua aplicação pode processar apenas as consultas novas desde a última sincronização.
O fluxo recomendado é:
- listar as consultas mais recentes;
- identificar quais ainda não foram processadas;
- recuperar os documentos de cada consulta;
- marcar a consulta como processada.
Caso ocorra uma falha durante o processamento, basta repetir a leitura daquela consulta.
Como os documentos continuam disponíveis na API, não há risco de perda de informações.
Status da consulta
Uma consulta pode estar em execução, concluída ou ter falhado.
Consultas concluídas com zero documentos encontrados representam uma execução normal: apenas não havia novos documentos disponíveis naquele momento.
Já consultas com falha indicam que não foi possível concluir a execução e podem ser analisadas posteriormente através das informações retornadas pela API.
NSU
Cada consulta informa o intervalo de NSUs processado durante sua execução.
O NSU é utilizado internamente pela Nota Gateway para garantir o processamento incremental dos documentos.
Na maioria das integrações não é necessário utilizar essa informação diretamente, mas ela pode ser útil para auditoria e diagnóstico.
Webhooks e Consultas retornam os mesmos dados
Os documentos enviados pelos webhooks são exatamente os mesmos retornados pela API de Consultas.
A diferença está apenas na forma de entrega:
- Webhook: entrega automática assim que um documento é encontrado.
- API de Consultas: recuperação sob demanda pela sua aplicação.