Como funciona o monitoramento
Depois de ativado, o Monitoramento consulta continuamente os ambientes oficiais em busca de novos documentos fiscais vinculados ao CNPJ.
Cada vez que essa verificação é executada, uma consulta é registrada.
Quando novos documentos são encontrados, eles ficam imediatamente disponíveis para sua aplicação.
Esse ciclo continua sendo executado automaticamente enquanto o monitoramento permanecer ativo.
Cada execução gera uma consulta
Uma consulta representa uma única execução do monitoramento.
Ela registra informações como:
- data e hora da execução;
- intervalo de NSUs processado;
- quantidade de documentos encontrados;
- status da execução.
Mesmo quando nenhum documento é localizado, uma consulta é registrada indicando que aquela execução foi realizada com sucesso.
As consultas permitem acompanhar o histórico do monitoramento e servem como base para integrações via polling.
Cada documento encontrado pode gerar um webhook
Quando uma consulta encontra novos documentos fiscais, a Nota Gateway envia um webhook para cada documento encontrado.
Cada webhook contém o JSON completo do documento encontrado, no mesmo formato disponibilizado pelas APIs de consulta.
Esse é o modelo de integração recomendado, pois sua aplicação recebe os documentos automaticamente, sem precisar consultar a API periodicamente.
Integração sem webhooks
Caso sua aplicação não possa receber webhooks, os documentos permanecem disponíveis na API.
Nesse modelo, sua aplicação consulta periodicamente as execuções do monitoramento e recupera os documentos encontrados em cada uma delas.
Os dados retornados por essa API são exatamente os mesmos enviados pelos webhooks.
Processamento incremental
O Monitoramento utiliza o NSU (Número Sequencial Único) para controlar o progresso da distribuição de documentos.
A cada consulta, a Nota Gateway continua exatamente do último NSU processado, garantindo que documentos já distribuídos não sejam consultados novamente.
Esse controle é realizado automaticamente pela plataforma. Na maioria das integrações, não é necessário manipular NSUs diretamente.
Latência
O Monitoramento não funciona em tempo real.
O tempo necessário para que um documento esteja disponível depende principalmente de:
- quando ele é disponibilizado pelo ambiente oficial;
- do intervalo entre as consultas executadas pela Nota Gateway;
- da forma de integração utilizada pela sua aplicação.
Com webhooks, sua aplicação é notificada automaticamente assim que um novo documento é encontrado.
Com a API de Consultas, a latência também dependerá da frequência com que sua aplicação realiza as consultas.
Desativando um monitoramento
Um monitoramento permanece ativo até que seja desativado.
Depois de desativado, novas consultas deixam de ser executadas.
As consultas já realizadas e os documentos encontrados continuam disponíveis para consulta pela API.