NF-e — Inutilização de Numeração

Visão Geral

A Inutilização de Numeração é o processo obrigatório de comunicar à SEFAZ que determinados números de NF-e não foram e não serão utilizados. É exigida pela legislação fiscal para manter a integridade da sequência numérica das notas.

Casos de uso típicos:

• Números pulados por falha de sistema
• Séries encerradas sem emissão de todas as numerações
• Cancelamento de bloco de numeração previamente reservado

Atenção: A inutilização é irreversível. Uma numeração inutilizada jamais poderá ser utilizada para emissão.

---

Localização

Camada	Arquivo
Serviço	backend/src/fiscal/inutilizacao.service.ts
Schema	backend/src/fiscal/schemas/inutilizacao-event.schema.ts
Endpoint	POST /t/:slug/admin/fiscal/inutilizar
Listagem	GET /t/:slug/admin/fiscal/inutilizacoes

Acesso na UI: Admin → Fiscal → Inutilização de Numeração

---

Schema InutilizacaoEvent

Campo	Tipo	Descrição
tenant	ObjectId	Tenant proprietário
serie	number	Série da NF-e (ex: 1)
startNumber	number	Primeiro número da faixa
endNumber	number	Último número da faixa (>= startNumber)
justification	string (15–255 chars)	Motivo da inutilização
status	pending | authorized | rejected	Estado junto à SEFAZ
protocolNumber	string?	Protocolo SEFAZ retornado
rejectionReason	string?	Mensagem de rejeição
requestedBy	ObjectId → User	Usuário que solicitou

Índice: { tenant, serie, startNumber } para consulta rápida por série.

---

API Endpoints

Método	Rota	Descrição
POST	/t/:slug/admin/fiscal/inutilizar	Inutilizar faixa de numeração
GET	/t/:slug/admin/fiscal/inutilizacoes	Listar eventos do tenant

Guards: JwtAuthGuard → TenantGuard

DTO — InutilizarRangeDto

{
  serie: number;          // Série NF-e
  startNumber: number;    // Número inicial
  endNumber: number;      // Número final (>= startNumber)
  justification: string;  // Justificativa (≥ 15 chars)
}

---

Fluxo de Inutilização

Admin preenche: série, faixa (início–fim), justificativa
    ↓
POST /t/:slug/admin/fiscal/inutilizar
    ↓
InutilizacaoService.inutilizar()
    ↓
1. Valida: endNumber >= startNumber
2. Lê CNPJ e UF do tenant (obrigatórios)
3. Persiste InutilizacaoEvent { status: 'pending' }
4. Chama SefazDirectProvider.inutilizar()
    ↓
SEFAZ retorna protocolNumber ou rejeição
    ↓
InutilizacaoEvent atualizado → 'authorized' ou 'rejected'

A persistência antes da chamada SEFAZ garante rastreabilidade mesmo em caso de timeout.

---

Pré-requisitos

Para inutilizar, o tenant deve ter:

• CNPJ configurado em Configurações → Fiscal
• UF (estado) configurado
• Ambiente (homologacao ou producao) definido

Se algum campo estiver faltando, o serviço lança 400 BadRequestException com mensagem descritiva.

---

Status dos Eventos

Status	Descrição
pending	Enviado à SEFAZ, aguardando retorno (estado transitório)
authorized	SEFAZ confirmou — números permanentemente inutilizados
rejected	SEFAZ rejeitou — ver rejectionReason para detalhes

---

Ambiente de Homologação

Em homologação, a inutilização segue o mesmo fluxo mas opera no ambiente de testes da SEFAZ. Use para validar o processo antes de ir para produção. Os eventos de homologação ficam separados dos de produção pelo campo ambiente no tenant.

---

Relacionados

• Fiscal / NF-e — Módulo fiscal completo
• Contingência NF-e — Emissão offline
• Configurações Fiscais — CNPJ, UF e token Focus NFe