NFe emitida no momento certo, com retry automático em falhas.
Provider configurável (NFe.io ou Kobana). 4 políticas de emissão. Retry com até 5 tentativas em delays escalonados. Sandbox + produção isolados.
Sistema
2
providers (NFe.io, Kobana)
4
políticas de emissão
5
tentativas de retry padrão
30min
intervalo do worker nfe-retry
Quando emitir a NFe
Disabled
Não emite NFe automaticamente. Operação 100% manual via API ou dashboard.
- Emissão manual
- Via API ou dashboard
On Finalization
Emite ao finalizar a fatura (transição draft → open). Independe do pagamento.
- Emissão antes do pagamento
- Cobranças B2B
- NFe precede caixa
On Full Payment (recomendado)
Emite quando fatura entra em status paid. Webhook invoice.paid dispara emissão.
- SaaS recorrente padrão
- Acompanha caixa
- Recomendado
Per Installment
Para carnês. Emite uma NFe por parcela conforme cada Installment é pago.
- Uma NFe por parcela
- Vendas parceladas
- Mensalidades escolares
Providers suportados
NFe.io
Provider parceiro com cobertura nacional. Integração via API key (criptografada).
- nfeioApiKey encrypt em AES-256-GCM
- nfeioCompanies cache das companies
- Suporte a milhares de municípios
Kobana próprio
Providers nativos para municípios específicos onde NFe.io não cobre.
- nfseAdn e nfseBarueri em lib/nfe/
- Sandbox via mock provider
- Roadmap para mais municípios
Recursos do NfeConfig
Retry Configurável
maxIssueAttempts (5), retryDelaysMinutes ([0, 30, 60, 180, 360]). Worker nfe-retry reprocessa a cada 30 minutos.
- Backoff escalonado
- Cancelamento também tem retry independente
- NfeRequestTry tracks cada tentativa com payload + response
Service Description Padrão
serviceDescription é prefixado/sufixado na descrição de cada item da NFe. Útil para frases obrigatórias por município.
- Prefixo/sufixo configurável
- Frases obrigatórias por município
Ambiente (NfeEnvironment)
SANDBOX para testes (não gera NFe real). PRODUCTION para emissão real.
- SANDBOX | PRODUCTION
- Sem NFe real em sandbox
Cancelamento via API
NFe emitida pode ser cancelada (status pending_cancel → canceling → canceled). Worker faz retry.
- Estados pending_cancel → canceling → canceled
- Worker faz retry
Histórico de Tentativas
NfeRequestTry com payload enviado, response recebida, statusCode, errorMessage. Útil para debug.
- Payload + response
- statusCode + errorMessage
- Debug completo