Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

Troubleshooting — NFe / CTe Inbound

Sinais de problema (e o que verificar)​

SintomaCausa provávelO que fazer
Último NSU não avançaSem documentos novos, ou captura pausadaConfirme se há documentos no período; verifique o status da empresa
Status Inativo (vermelho)Desativação automática (circuit breaker) — ex.: certificadoCorrija a causa e reative; veja Certificado digital
Webhooks não chegamURL inacessível, retornando ≠2xx, ou validação HMAC falhandoTeste a URL; valide a assinatura x-hub-signature; use o reprocessamento
rateLimitedUntil preenchidoLimite de taxa atingido no ambiente nacionalAguarde a data informada; reduza a frequência de chamadas
Só chega o resumo da NF-e, sem XML completoA NF-e ainda não foi manifestada — a SEFAZ só libera o XML completo (procNFe) após a manifestaçãoRegistre a Ciência (210210) ou outra manifestação; veja Manifestar NF-e
NF-e cancelada ficou só com resumo + cancelamentoA SEFAZ recusa a Ciência para NF-e cancelada (cStat 650), então o XML completo não é liberadoUse o XML do evento de cancelamento (110111, procEventoNFe) como registro fiscal
GET .../pdf responde 422O documento é um resumo ou um evento, sem DANFENão repita a chamada; manifeste a NF-e para obter o XML completo
Leituras de NF-e respondem 403 (e /xml responde 400)Inbound de NF-e não ativo na empresa (nunca habilitado ou desativado)Reative com POST .../inbound/productinvoices; os documentos já capturados continuam armazenados
Manifestação fica em PendingO envio à SEFAZ é assíncrono; não há webhook de conclusãoConsulte GET .../productinvoices/manifestation-events/{id} por polling
Manifestação terminou RejectedA SEFAZ recusou o evento (ex.: cStat 596, fora do prazo). errorCode = BadRequest ou VALIDATIONLeia errorMessage; corrija e reenvie — Rejected permite nova submissão
Manifestação terminou FailedFalha antes do envio (ex.: CERT_EXPIRED, CERT_NOT_FOUND, MAX_ATTEMPTS_EXCEEDED)Corrija a causa indicada em errorCode (ex.: renove o certificado) e reenvie
issuedOn do resumo difere da data de emissãoNos resumos, issuedOn é dhRecbto/dhEvento (recebimento na SEFAZ), não dhEmi — por desenhoUse o issuedOn do documento completo para a data de emissão
Ativei o CT-e e não chega nadaAtivação feita sem EnvironmentSEFAZ — nesse caso a NFE.io assume homologação (Test)Consulte a configuração; se estiver em Test, desative e ative de novo com Production
Erro ao ativar o CT-e: already have an active configurationJá existe configuração ativa para a empresa nesta contaNão é preciso reativar. Para trocar ambiente ou ponto de partida, desative e ative de novo; para trocar só o filtro de papéis no webhook do CT-e, use PUT .../inbound/transportationinvoices/webhook/filter, que não altera o resto da configuração

Reenviar um webhook​

Após esgotar as tentativas automáticas, o documento continua consultável. Reenvie manualmente:

curl -X POST "https://api.nfe.io/v2/companies/{company_id}/inbound/productinvoices/{access_key}/processwebhook" \
  -H "Authorization: SUA_API_KEY"

Erros de autenticação​

  • 401 — chave ausente/inválida. Envie a API Key no header Authorization sem prefixo (veja Autenticação).
  • 403 — chave sem o papel necessário (Nota Fiscal (api.nfe.io), ou NFeDist/CTeDist (dfe.nfe.io)). Nas rotas de NF-e, o 403 também indica empresa sem o inbound de NF-e ativo — veja Códigos HTTP.

Reconciliação automática de CT-e​

A NFE.io roda uma reconciliação diária que revisita os NSUs recentes de cada empresa com CT-e ativo e recupera documentos que tenham ficado para trás. Ela fecha lacunas recentes — não reconstrói histórico: para buscar documentos anteriores à ativação, use StartFromDate (limitado à retenção da SEFAZ, hoje cerca de 90 dias). Valores atuais: execução às 23h (horário de Brasília), revisitando os últimos 3 dias. São parâmetros de operação e podem ser ajustados.

Checklist de diagnóstico​

  • Empresa ativa para o tipo de documento?
  • Certificado A1 válido (NF-e/CT-e)?
  • Período consultado tem documentos? (SEFAZ guarda ~90 dias)
  • Webhook respondendo 2xx em <5s e validando HMAC?
  • API Key com o papel correto e sem prefixo no header?

Veja também​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.