Ativar a captura de NFS-e via API

Para receber automaticamente as NFS-e emitidas contra o CNPJ da sua empresa, cadastre-a no serviço de recepção. Todas as rotas exigem uma API Key com papel Nota Fiscal (api.nfe.io) ou NFSeDist (dfe.nfe.io) — veja Autenticação.

Base URL: https://api.nfse.io

Cadastrar a empresa

curl -X POST "https://api.nfse.io/v2/companies/inbound/nfse" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "SEU_COMPANY_ID",
    "initialNsu": 0,
    "webhookUrl": "https://seu-sistema.com/webhooks/nfse",
    "startFromDate": "2026-01-01T00:00:00Z",
    "outboundEnabled": false
  }'

initialNsu é obrigatório (use 0 para capturar desde o início disponível). Resposta 201 Created. Se a empresa já estiver cadastrada, a API retorna 409 Conflict.

Campo	Obrigatório	Descrição
companyId	Sim	ID da empresa no cadastro
initialNsu	Sim	NSU inicial (0 = desde o início disponível)
webhookUrl	Não	URL HTTPS que receberá as notificações
startFromDate	Não	Data de corte da captura — ver abaixo
outboundEnabled	Não	Default false. Ver Notas emitidas pela própria empresa
environment	Não	Production, Development ou Homologation (case-insensitive)
isActive	Não	Default true. false cadastra sem iniciar a captura

O campo environment é opcional. Quando omitido, herda o ambiente da inscrição municipal (TaxPayers); se ausente também ali, assume "Production" por padrão.

A partir de quando receber (startFromDate)

Ao ativar a captura, a consulta ao ambiente nacional parte do início e devolve todo o histórico do CNPJ. Se a sua empresa já emite ou recebe NFS-e há anos, isso significa receber de uma vez notas de competências há muito fechadas.

O startFromDate define a partir de quando você quer receber. Documentos anteriores ao corte continuam sendo capturados, mas não aparecem na listagem e não disparam webhook — e são cobrados à parte, como histórico.

Um documento só é tratado como histórico quando tanto a data de emissão quanto a data de registro no ambiente nacional são anteriores ao corte. Uma nota antiga que só foi registrada na ADN depois do corte entra como documento corrente.

Informe o corte já no cadastro

Definir startFromDate na mesma chamada que cadastra a empresa é o caminho recomendado: não existe intervalo em que a captura esteja ligada sem o corte valendo. Se a empresa for cadastrada sem corte e ele for definido depois, o histórico que chegar nesse intervalo é tratado como documento corrente — notificado e cobrado como tal, sem como reclassificar depois.

Data no futuro é recusada com 400. Um corte futuro faria todo documento capturado nascer suprimido — fora da listagem, sem webhook — e a marcação não é recalculada depois, então nem corrigir a data resolveria. O 400 troca essa falha silenciosa e irreversível por um erro na hora do cadastro.

Fuso horário: o valor é normalizado para UTC. Com offset explícito (2026-01-01T00:00:00-03:00) é convertido; sem offset (2026-01-01) é interpretado como UTC.

Para alterar o corte depois, fale com o suporte: a mudança em uma empresa que já captura é feita pela área de Manutenção. O motivo é que cada documento é classificado como histórico no momento da captura, e essa marcação não é recalculada — mudar o corte depois não reclassifica o que já entrou.

Enviar startFromDate no PUT .../details retorna 400 Bad Request, justamente para não dar a impressão de que o corte foi movido.

Se quiser receber o histórico anterior ao corte, a liberação é contratada à parte — veja Manutenção administrativa.

Notas emitidas pela própria empresa

Por padrão a empresa recebe apenas as NFS-e em que é tomadora (as notas que recebeu). As notas que ela mesma emitiu ficam fora do webhook e fora da listagem.

Para receber também as emitidas, envie outboundEnabled: true — no cadastro ou depois, pelo PUT .../details. Isso não altera o comportamento das notas recebidas.

Consultar a configuração

curl "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/details" \
  -H "Authorization: SUA_API_KEY"

Retorna a configuração atual: webhookUrl, isActive, currentNsu, environment, isAutomaticManifestationEnabled, outboundEnabled, startFromDate, backfillReleased, backfillReleasedAt, etc. O webhookVersion não é exposto na resposta (veja Versionamento de webhook).

Atualizar a configuração

curl -X PUT "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/details" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://seu-sistema.com/webhooks/nfse",
    "isAutomaticManifestationEnabled": true,
    "automaticManifestationDelaySeconds": 3600,
    "isActive": true,
    "outboundEnabled": true
  }'

• automaticManifestationDelaySeconds aceita de 0 a 604800 (7 dias).
• outboundEnabled liga/desliga o recebimento das notas emitidas pela própria empresa.
• startFromDate não é alterável por aqui: enviar o campo neste corpo retorna 400 Bad Request. Ele é definido no cadastro — veja A partir de quando receber.

Desativar

curl -X DELETE "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/details" \
  -H "Authorization: SUA_API_KEY"

A captura para, mas os documentos já recebidos continuam acessíveis.

Redefinir o cursor (reset-nsu)

Para reprocessar a partir de um NSU específico:

Risco de NOVAS COBRANÇAS ao alterar o NSU

Redefinir o NSU para um valor menor que o currentNsu faz o sistema re-capturar documentos já processados — e cada documento re-capturado é COBRADO NOVAMENTE (a bilhetagem do NFS-e Inbound é por documento capturado). O exemplo abaixo com "nsu": 0 re-captura todo o histórico da empresa. Só reposicione o NSU quando souber exatamente o efeito.

# ⚠️ "nsu": 0 re-captura TODO o histórico e re-cobra cada documento — ver aviso acima
curl -X POST "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/reset-nsu" \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nsu": 0 }'

Veja também

• Integração REST
• Captura sob demanda pela chave de acesso
• Ativar via painel
• Referência da API NFS-e Inbound