Monitoramento de Notas Fiscais
O Monitoramento de Notas Fiscais permite acompanhar automaticamente os documentos fiscais vinculados a um CNPJ.
Depois de ativado, a Nota Gateway consulta continuamente os ambientes oficiais e identifica novas NFS-e emitidas e recebidas e NF-e recebidas. Sempre que um novo documento é encontrado, ele pode ser entregue automaticamente para sua aplicação por webhook ou recuperado posteriormente pela API de Consultas.
O monitoramento é contínuo: basta ativá-lo uma única vez para que a Nota Gateway mantenha as consultas automaticamente.
O que você recebe
Para cada documento encontrado, disponibilizamos:
- Dados estruturados em JSON;
- XML autorizado;
- PDF (quando disponível);
- Eventos relacionados ao documento;
- Manifestação do destinatário (NF-e).
O mesmo modelo de dados está disponível tanto nos webhooks quanto na API de Consultas.
Como funciona
Depois de ativar um monitoramento, a Nota Gateway consulta continuamente os ambientes oficiais em busca de novos documentos fiscais.
Sua aplicação pode integrar de duas formas:
Webhooks (recomendado)
Sempre que um novo documento é encontrado, enviamos automaticamente um webhook para sua aplicação contendo o JSON completo da nota fiscal.
Esse é o modelo recomendado para a maioria das integrações.
API de Consultas
Caso sua aplicação não possa receber webhooks, você pode consultar periodicamente as execuções do monitoramento e recuperar os documentos encontrados por meio da API.
Esse modelo é indicado para ambientes que utilizam polling ou possuem restrições para exposição de endpoints HTTP.
Casos de uso
O Monitoramento pode ser utilizado em diversos cenários:
| Situação | Como o Monitoramento ajuda |
|---|---|
| Contas a pagar | Localiza automaticamente novas notas fiscais recebidas. |
| Conciliação fiscal | Compara documentos fiscais com pedidos, contratos ou lançamentos internos. |
| Recuperação de XML | Mantém XMLs autorizados disponíveis para download. |
| Manifestação do destinatário | Identifica rapidamente NF-e que exigem manifestação. |
| Auditoria e rastreabilidade | Mantém o histórico completo das consultas e dos documentos encontrados. |
Modelo da API
Toda a API é organizada em torno de três recursos.
Monitoramento
Representa a configuração do monitoramento para um CNPJ e um tipo de documento fiscal.
Uma vez ativado, o monitoramento permanece executando continuamente até ser desativado.
Consulta
Cada execução do monitoramento gera uma consulta.
Ela registra quando a execução ocorreu, quais documentos foram encontrados e o resultado da operação.
As consultas são utilizadas tanto para integração via polling quanto para recuperação do histórico.
Documento
Representa uma nota fiscal ou um evento encontrado durante uma consulta.
Os documentos podem ser recebidos automaticamente por webhook ou recuperados posteriormente pela API de Consultas.
O próximo passo é o Quickstart, onde você ativará seu primeiro monitoramento e receberá seus primeiros documentos.