Pular para o conteúdo principal

Primeiros passos

Neste guia você irá:

  1. Ativar o monitoramento de um CNPJ.
  2. Configurar um webhook para receber novos documentos.
  3. Entender as duas formas de integração disponíveis: Webhook e API de Consultas.

Ao final, sua aplicação estará pronta para receber automaticamente novas NF-e e NFS-e.

Antes de começar

Você precisará de:

  • Um Token de API.
  • O empresaId (UUID da empresa).
  • Um endpoint HTTPS para receber webhooks (recomendado).
  • Um certificado digital válido cadastrado para a empresa.

Como funciona

Depois que o monitoramento é ativado, a Nota Gateway consulta continuamente os ambientes oficiais em busca de novos documentos fiscais vinculados ao CNPJ.

Quando um novo documento é encontrado, você pode recebê-lo de duas formas:

Opção 1 — Webhooks (recomendado)​

Opção 2 — API de Consultas​

Caso sua infraestrutura não permita receber webhooks, sua aplicação pode consultar periodicamente as execuções do monitoramento e recuperar os documentos encontrados.

1. Ative o monitoramento

O primeiro passo é criar um monitoramento para o CNPJ.

curl -X POST \
  'https://api.notagateway.com.br/v4/empresas/SEU_EMPRESA_ID/nf-e/monitoramento' \
  -H 'Authorization: Basic {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "nsuInicial": 0
  }'

O parâmetro nsuInicial define o ponto inicial da distribuição de documentos.

  • 0 inicia a captura desde o início do histórico disponível.
  • Qualquer outro valor inicia a captura a partir do NSU informado.

O monitoramento é criado apenas uma vez para cada empresa.

Para monitorar NFS-e, basta substituir nf-e por nfs-e na URL.

2. Configure um webhook (recomendado)

Depois que o monitoramento estiver ativo, configure um webhook para receber automaticamente os documentos encontrados.

Sempre que uma nova nota fiscal for localizada, a Nota Gateway enviará uma requisição HTTP POST para a URL configurada.

POST https://suaaplicacao.com/webhooks/notas

O corpo da requisição contém o JSON completo da NF-e ou NFS-e, exatamente no mesmo formato retornado pelas APIs de consulta.

Consulte o Schema JSON dos documentos para conhecer todos os campos disponíveis.

Exemplo resumido:

{
  "tipo": "NFSe",
  "papel": "Tomador",
  "numero": "4821",
  "chaveAcesso": "35260812345678000199550010000048211234567890123",
  "status": "Autorizada",
  "dataCompetencia": "2026-08-15T30:00:00Z",
  "dataAutorizacao": "2026-08-15T14:32:18Z",
  "linkDownloadPDF": "https://api.notagateway.com.br/v4/file/eyJhbGciOi.../pdf",
  "linkDownloadXML": "https://api.notagateway.com.br/v4/file/eyJhbGciOi.../xml",

  "emitente": {
    ...
  },

  "tomador": {
    ...
  },

  "...": "demais campos do documento"
}

Seu endpoint deve responder com HTTP 2xx para confirmar o recebimento do evento.

Os webhooks são a forma recomendada de integração porque reduzem a latência e eliminam a necessidade de consultas periódicas.

Consulte o guia de Webhooks para mais informações.

3. Integrando sem webhooks​

Quando sua aplicação não puder receber webhooks, ela poderá consultar periodicamente as execuções do monitoramento.

Nesse modelo, o fluxo é dividido em duas etapas:

  1. sua aplicação lista as consultas executadas;
  2. para cada consulta concluída, busca os documentos e eventos encontrados.

3.1 Liste as consultas executadas​

Consulte as execuções do monitoramento em um intervalo de datas:

curl -G \
  'https://api.notagateway.com.br/v4/empresas/SEU_EMPRESA_ID/nfs-e/monitoramento/consultas' \
  --data-urlencode 'From=2026-07-20T00:00:00Z' \
  --data-urlencode 'To=2026-07-20T23:59:59Z' \
  -H 'Authorization: Basic {API_KEY}'

A resposta contém as consultas realizadas pelo monitoramento:

{
  "hasMorePages": false,
  "continuationToken": null,
  "consultas": [
    {
      "id": "019f8154-a17b-7ed1-9353-757627b488e8",
      "status": "Concluída",
      "motivoStatus": null,
      "dataInicio": "2026-07-20T21:02:24.875612Z",
      "dataFim": "2026-07-20T21:05:21.817662Z",
      "nsuInicial": 0,
      "nsuFinal": 50,
      "totalItensEncontrados": 50,
      "dataHoraCriacao": "2026-07-20T21:00:35.06745Z",
      "dataHoraUltimaAlteracao": "2026-07-20T21:05:39.579851Z"
    }
  ]
}

Cada item representa uma execução do monitoramento.

Os principais campos são:

  • id: identificador da consulta, utilizado para buscar os documentos encontrados;
  • status: estado atual da execução;
  • motivoStatus: descrição adicional quando a consulta falhar ou for interrompida;
  • nsuInicial e nsuFinal: intervalo de NSUs processado;
  • totalItensEncontrados: quantidade total de notas e eventos encontrados;
  • dataInicio e dataFim: período de execução da consulta.

Processe apenas consultas com status igual a Concluída.

Se hasMorePages for true, faça uma nova chamada informando o valor de continuationToken para recuperar a próxima página.

Guarde as consultas já processadas

Armazene o id de cada consulta processada para evitar o processamento duplicado.

O id identifica a execução, mas não representa uma sequência. Para acompanhar a evolução da distribuição, utilize também o nsuFinal.

3.2 Consulte os documentos encontrados​

Depois de obter o id de uma consulta concluída, consulte as notas e os eventos encontrados naquela execução:

curl \
  'https://api.notagateway.com.br/v4/empresas/SEU_EMPRESA_ID/nfs-e/monitoramento/consultas/019f8154-a17b-7ed1-9353-757627b488e8/documentos' \
  -H 'Authorization: Basic {API_KEY}'

A resposta separa os documentos fiscais dos eventos relacionados:

{
  "notas": [
    {
      "tipo": "NFSe",
      "papel": "Tomador",
      "numero": "4821",
      "chaveAcesso": "31062002684421782000125000000000482126081123456789",
      "status": "Autorizada",
      "ambienteEmissao": "Producao",
      "numeroDps": 4821,
      "serieDps": "1",
      "dataCompetencia": "2026-08-15T00:00:00Z",
      "dataCriacao": "2026-08-15T14:30:42Z",
      "dataUltimaAlteracao": "2026-08-15T14:32:20Z",
      "dataAutorizacao": "2026-08-15T14:32:18Z",
      "linkDownloadPDF": "https://api.notagateway.com.br/v4/file/eyJhbGciOi.../pdf",
      "linkDownloadXML": "https://api.notagateway.com.br/v4/file/eyJhbGciOi.../xml",
      "emitente": {
        ...
      },
      "tomador": {
        ...
      },
      "...": "demais campos da NFS-e"
    }
  ],
  "eventos": [
    {
      "tipo": "Cancelamento",
      "chaveAcesso": "3106200268442178200012500000000048212608112345678901101001",
      "sequencial": 1,
      "ambienteEmissao": "Producao",
      "dataProcessamento": "2026-08-16T09:22:23-03:00",
      "autor": {
        "tipoPessoa": "J",
        "cpfCnpj": "68442178200012"
      },
      "...": "demais campos do evento"
    }
  ]
}

O campo notas contém o JSON completo das NF-e ou NFS-e encontradas.

O campo eventos contém eventos relacionados aos documentos, como cancelamentos e outros eventos fiscais disponibilizados pelo ambiente de origem.

Os links linkDownloadXML e linkDownloadPDF podem ser utilizados diretamente para baixar os arquivos do documento.

Consulte o schema JSON dos documentos para conhecer todos os campos disponíveis.

3.3 Fluxo recomendado​

Em uma integração baseada em consultas, o fluxo normalmente é:

  1. Consulte as execuções do monitoramento em um intervalo de datas.
  2. Considere apenas as consultas com status Concluída.
  3. Ignore consultas que já foram processadas anteriormente.
  4. Para cada nova consulta, recupere as notas e os eventos encontrados.
  5. Processe os documentos na sua aplicação.
  6. Caso existam mais páginas, continue utilizando o continuationToken até recuperar todas as consultas do período.

O intervalo entre as chamadas depende da latência esperada pela sua aplicação. Evite consultas excessivamente frequentes, pois o monitoramento já executa as buscas nos ambientes oficiais de forma automática.

Webhook continua sendo o caminho recomendado

A API de Consultas oferece todos os dados necessários para uma integração completa sem webhooks.

Ainda assim, recomendamos webhooks sempre que possível, porque sua aplicação recebe os novos documentos automaticamente, sem precisar consultar continuamente a API.

4. Baixando XML e outros documentos

Depois que um documento for encontrado, você poderá acessar recursos adicionais disponibilizados pela API.

Dependendo do tipo de documento, estarão disponíveis:

  • XML autorizado;
  • PDF;
  • Eventos fiscais;
  • Manifestação do destinatário (NF-e).

As particularidades de NF-e e NFS-e são diferentes e são detalhadas nos guias específicos de cada documento.

Próximos passos

Agora que seu monitoramento está ativo, recomendamos a seguinte sequência de leitura:

  • Webhooks — configuração, assinatura, tentativas de reenvio e boas práticas.
  • Monitorando NF-e — distribuição de documentos, manifestação e XML completo.
  • Monitorando NFS-e — particularidades do monitoramento de serviços.
  • Consultas — histórico de execuções, recuperação de documentos e integração via polling.
  • Referência REST — documentação completa da API.