Manutenção administrativa da captura de NFS-e
Há um conjunto de endpoints operacionais sob .../inbound/nfse/maintenance:
fetch-now— força a captura imediata da própria empresa. Acessível com uma API Key de cliente (papelNota Fiscal/NFSeDist) ou com o papelManagement(ops). O disparo é escopado ao próprio tenant: a empresa precisa pertencer à conta da API Key, senão retorna404.notifications,statistics,reactivate— administrativos, restritos ao papelManagement(chamadas sem ele retornam403).
Todas as rotas abaixo são prefixadas por
https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/maintenance.
Forçar captura imediata
curl -X POST ".../maintenance/fetch-now" \
-H "Authorization: SUA_API_KEY"
Dispara um ciclo de captura fora da cadência normal de polling, continuando do currentNsu da empresa. Resposta 202 Accepted.
O corpo opcional aceita forcedStartNsu, que reposiciona o cursor de NSU da empresa. Informar um NSU 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).
Para uma busca normal, não envie forcedStartNsu — o sistema continua a partir do currentNsu e não re-cobra o que já foi capturado. Use forcedStartNsu apenas quando souber exatamente o efeito.
# ⚠️ forcedStartNsu reposiciona o cursor de NSU — pode gerar novas cobranças (ver aviso acima)
curl -X POST ".../maintenance/fetch-now" \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "forcedStartNsu": 10000 }'
Consultar notificações operacionais
curl ".../maintenance/notifications?severity=Critical" \
-H "Authorization: SUA_API_KEY_MANAGEMENT"
Filtros: severity (Info / Warning / Critical) e type.
Estatísticas
curl ".../maintenance/statistics" \
-H "Authorization: SUA_API_KEY_MANAGEMENT"
Retorna contadores operacionais da empresa.
Reativar empresa
Empresas desativadas automaticamente pelo circuit breaker (ex.: falhas consecutivas) podem ser reativadas:
curl -X POST ".../maintenance/reactivate" \
-H "Authorization: SUA_API_KEY_MANAGEMENT"
Alterar a data de corte da captura
O corte (startFromDate) define a partir de quando a empresa recebe seus documentos. Ele é normalmente informado no cadastro — veja Ativar via API.
Alterá-lo depois, em uma empresa que já captura, é operação restrita ao papel Management:
curl -X PUT ".../maintenance/start-from-date" \
-H "Authorization: SUA_API_KEY_MANAGEMENT" \
-H "Content-Type: application/json" \
-d '{ "startFromDate": "2026-01-01T00:00:00Z" }'
Envie null para remover o corte.
Cada documento é marcado como histórico no momento da captura, e essa marcação não é recalculada. Mudar o corte depois vale apenas para o que vier a seguir — o que já entrou permanece classificado pela regra anterior.
Não é possível remover o corte de uma empresa com o histórico liberado: revogue a liberação antes (400 Bad Request caso contrário).
Liberar o histórico anterior ao corte
A entrega dos documentos anteriores ao corte é contratada à parte. Uma vez liberada, eles passam a aparecer na listagem e são entregues por webhook:
curl -X POST ".../maintenance/backfill/release" \
-H "Authorization: SUA_API_KEY_MANAGEMENT" \
-H "Content-Type: application/json" \
-d '{ "enabled": true }'
A liberação dispara uma varredura assíncrona que reenvia os webhooks do histórico, em páginas, retomável de onde parou. Enviar enabled: false revoga a liberação — os documentos históricos voltam a ficar ocultos, mas o que já foi entregue não é desfeito.
A resposta é 202 Accepted com released, releasedAt e backfillDocumentsCount (quantos documentos entram na varredura). Repetir a chamada com enabled: true republica a varredura de propósito: ela seleciona apenas o que ainda não foi entregue, então repetir é o caminho de retomada quando uma varredura para no meio.
Liberar exige que a empresa tenha um startFromDate configurado — sem corte não há histórico a liberar, e a chamada retorna 400 Bad Request.
Consultar o histórico retido
Antes de liberar, para saber o tamanho do que está retido — este endpoint é acessível ao próprio cliente (papel NFSeDist), não exige Management:
curl "https://api.nfse.io/v2/companies/{companyId}/inbound/nfse/backfill" \
-H "Authorization: SUA_API_KEY"
{
"startFromDate": "2026-01-01T00:00:00Z",
"released": false,
"hiddenDocumentsCount": 1842
}
| Campo | Significado |
|---|---|
startFromDate | Corte vigente. null = sem corte |
released | Se o histórico já foi liberado. Enquanto false, os documentos contados não aparecem na listagem |
hiddenDocumentsCount | Quantidade de documentos anteriores ao corte. Enquanto released: false, é exatamente quantos documentos o cliente não enxerga. 0 quando não há corte configurado |
A resposta traz apenas contagem e configuração — nunca identificadores ou metadados dos documentos retidos.
Empresa sem corte configurado também responde 200, com startFromDate: null e hiddenDocumentsCount: 0 — não há histórico retido a contar.
404 em toda porta de leituraDocumentos retidos são tratados como inexistentes em todas as consultas: listagem, GET .../{id}, XML/PDF/JSON, reenvio de webhook, reprocesso, captura sob demanda por chave e os endpoints de manifestação por chave. É 404 e não 403 de propósito — confirmar a existência já entregaria parte do que está retido. Use GET .../backfill para diagnosticar.