NF-e / Documentos Fiscais

Visão Geral

A tela de documentos fiscais permite emitir, acompanhar e baixar NF-e (Nota Fiscal Eletrônica) e NFC-e vinculadas aos pedidos do restaurante, integrando com o serviço Focus NFe.

Localização

frontend-react/src/views/admin/FiscalView.tsx

Rota: /t/:slug/admin/fiscal

Funcionalidades

Lista de todos os documentos fiscais do tenant
Filtro por status (pendente, autorizada, rejeitada, cancelada)
Botão para baixar DANFE (PDF) e XML
Cancelamento de documentos autorizados
Emissão iniciada pela tela de Pedidos

Status dos Documentos

Status	Descrição
`pending`	Enviado à SEFAZ, aguardando retorno
`authorized`	Autorizado — chave e DANFE disponíveis
`rejected`	Rejeitado — ver detalhes do erro
`cancelled`	Cancelado pelo operador

Emissão de NF-e via Tela de Pedidos

Na tela Pedidos (/admin/orders), cada pedido entregue exibe botões de emissão:

Botão	Tipo	Uso
NFC-e	`nfce`	Consumidor final (sem CPF obrigatório)
NF-e	`nfe`	Pessoa jurídica / com CPF

Ao clicar, é feita a chamada POST /t/:slug/fiscal/emit com { orderId, tipo }.

Configuração Necessária (Settings)

Antes de emitir, o admin deve preencher em Configurações → Fiscal:

Campo	Obrigatório	Descrição
CNPJ	Sim	CNPJ do emitente (14 dígitos) — aceita CNPJ alfanumérico (letras A-Z nas 12 primeiras posições, prazo julho 2026)
Inscrição Estadual	Não	IE do estabelecimento
Token Focus NFe	Sim	Token da API Focus NFe
Ambiente	Sim	`homologacao` (testes) ou `producao`
Regime Tributário	Não	1=Simples, 2=Presumido, 3=Real
Endereço completo	Sim	Logradouro, número, bairro, cidade, UF, CEP

Grupos Fiscais

Grupos Fiscais são perfis tributários reutilizáveis que agrupam as modalidades e alíquotas de ICMS, PIS, COFINS, IBS e CBS. Cada item do cardápio pode ser vinculado a um grupo fiscal, garantindo que a NF-e gerada carregue os campos tributários corretos automaticamente.

Localização do Componente

frontend-react/src/features/fiscal/components/FiscalGroupModal.tsx

Acesso via: Configurações → Fiscal → Grupos Fiscais

Campos do Grupo Fiscal

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do grupo (ex: "Bebidas SN")
`description`	string	Não	Descrição livre
`cfop`	string	Não	Código Fiscal de Operações (padrão `5102`)
`ncmPadrao`	string	Não	NCM padrão dos itens deste grupo (ex: `2202.10.00`)
`icmsModalidade`	string	Não	CST ICMS: `102`, `103`, `400`, `900` (padrão `400`)
`icmsAliquota`	number	Não	Alíquota ICMS em %
`pisModalidade`	string	Não	CST PIS: `07`, `08`, `09` (padrão `07`)
`pisAliquota`	number	Não	Alíquota PIS em %
`cofinsModalidade`	string	Não	CST COFINS: `07`, `08`, `09` (padrão `07`)
`cofinsAliquota`	number	Não	Alíquota COFINS em %
`ibsAliquota`	number	Não	Alíquota IBS global (somente CRT 1/2)
`cbsAliquota`	number	Não	Alíquota CBS global

NT 2025.002 — Reforma Tributária (CRT 3 apenas)

O bloco NT 2025.002 é renderizado condicionalmente apenas quando regimeTributario === '3' (Lucro Real). Substitui os campos ibsAliquota/cbsAliquota simples pelo detalhamento completo exigido pela Reforma Tributária (IBS/CBS).

tsx

// frontend-react/src/features/fiscal/components/FiscalGroupModal.tsx
const isCrt3 = regimeTributario === '3';
// ...
{isCrt3 && (
  <div>/* Bloco NT 2025.002 */</div>
)}

Campos NT 2025.002

Campo	Tipo	Descrição
`ibsCst`	string	CST IBS/CBS — Tabela A, Apêndice III (ver tabela abaixo)
`ibsCClassTrib`	string	Classificação Tributária (`cClassTrib`) — ex: `1.01.01`
`ibsUfAliquota`	number	Alíquota IBS estadual (UF) em %
`ibsMunAliquota`	number	Alíquota IBS municipal em %
`cbsAliquota`	number	Alíquota CBS (federal) em %
`isDifPerc`	number	% de diferimento (`gDif`) — apenas para CST 02, 03, 04
`isRedAliq`	number	% de redução de alíquota (`gRed`) — apenas para CST 02, 03, 04

O preview ao vivo calcula: IBS UF + IBS Mun + CBS = total%.

Os campos isDifPerc e isRedAliq ficam ocultos atrás de um toggle "Avançado" e só são exibidos quando o CST selecionado é 02, 03 ou 04.

Tabela de CST IBS/CBS (Tabela A, Apêndice III — NT 2025.002)

Código	Descrição
`01`	Tributada integralmente
`02`	Tributada com diferimento
`03`	Tributada com redução de alíquota
`04`	Tributada com redução e diferimento
`06`	Imune
`07`	Isenta
`08`	Não incidência
`40`	Monofásica
`41`	Monofásica com diferimento
`70`	Suspensão

API

Método	Endpoint	Descrição
`GET`	`/t/:slug/fiscal/groups`	Lista grupos do tenant
`POST`	`/t/:slug/fiscal/groups`	Cria novo grupo
`PUT`	`/t/:slug/fiscal/groups/:id`	Atualiza grupo
`DELETE`	`/t/:slug/fiscal/groups/:id`	Remove grupo

Campos do Documento

Campo	Tipo	Descrição
`_id`	string	ID do documento
`order`	object	Pedido vinculado (número, total, cliente)
`tipo`	`nfe` \| `nfce`	Tipo de documento
`status`	string	Status atual
`nfeKey`	string	Chave de acesso 44 dígitos
`nfeNumber`	string	Número da nota
`serie`	string	Série
`danfeUrl`	string	URL do PDF DANFE
`xmlUrl`	string	URL do XML assinado
`focusNfeRef`	string	Referência interna Focus NFe
`customerCpf`	string	CPF do destinatário (opcional)
`emittedAt`	string	Data/hora de autorização

Fluxo Completo

Pedido entregue
    ↓
Admin clica "NFC-e" ou "NF-e" na tela de Pedidos
    ↓
POST /t/:slug/fiscal/emit
    ↓
FiscalService monta payload Focus NFe
(dados do pedido + CNPJ do tenant)
    ↓
POST https://api.focusnfe.com.br/v2/nfe (ou /nfce)
    ↓
Documento salvo com status pending
    ↓
Focus NFe retorna XML + DANFE (async ou sync)
    ↓
Status → authorized / rejected
    ↓
Admin baixa DANFE ou cancela

Homologação x Produção

Em homologação, as notas são enviadas ao ambiente de teste da SEFAZ — chaves começam com 35 (SP) mas não têm validade fiscal. Use para validar o fluxo antes de ir para produção.

Troque o campo Ambiente para producao apenas quando os dados do CNPJ e certificado estiverem corretamente configurados no Focus NFe.

Componentes Relacionados

NCM Autocomplete

O campo NCM nos itens do cardápio e nos Grupos Fiscais agora oferece busca fuzzy com autocomplete via trigram matching (coeficiente de Jaccard). O banco contém 60+ códigos NCM comuns para foodservice.

Componente: frontend-react/src/features/fiscal/components/NcmAutocomplete.tsx

Endpoint: GET /t/:slug/ncm/search?q=&category=&limit=

Auto-emissão (BullMQ)

Quando a opção autoEmitOnPayment está habilitada no tenant, a NF-e/NFC-e é emitida automaticamente ao fechar uma comanda ou ao receber um webhook de pagamento. Os jobs são enfileirados via BullMQ com retry exponential backoff. Um scheduler fallback roda a cada 5 minutos caso o Redis esteja indisponível.

Fiscal Queue Stats

O endpoint GET /t/:slug/fiscal/queue/stats retorna métricas da fila BullMQ:

Métrica	Descrição
`waiting`	Jobs aguardando processamento
`active`	Jobs em execução
`completed`	Jobs concluídos com sucesso
`failed`	Jobs com erro

Notificações Fiscais em Tempo Real

Eventos WebSocket fiscalStatusUpdate no namespace /kitchen notificam a UI admin quando uma NF-e é autorizada ou rejeitada. Notificações toast aparecem automaticamente no painel.

Certificado Digital A1

Upload e gerenciamento de certificados digitais A1 (.pfx). Um scheduler diário (9h) monitora a expiração e registra avisos nos limiares de 30/15/7/3/1 dias.

Portal do Contador

Portal somente-leitura para contadores acessarem documentos e relatórios fiscais.

Rota: /t/:slug/accountant/*

Views:

View	Descrição
Dashboard	Estatísticas mensais (autorizadas/rejeitadas/pendentes por tipo)
Documentos	Lista paginada com filtros e links DANFE/XML
Exportações	Download de XMLs em ZIP, EFD ICMS/IPI, EFD Contribuições
Split Payment	Simulação do impacto do Split Payment nos recebimentos
DeRE	Demonstração do Resultado do Exercício com detalhamento tributário

Convidar Contador

Administradores podem convidar contadores por email via o botão "Convidar Contador" na tela Fiscal. A ação cria o usuário e o vincula ao tenant com a role accountant.

Painel Fiscal (Admin)

Dashboard fiscal consolidado em /t/:slug/admin/fiscal-dashboard exibindo estatísticas mensais e status do certificado digital.

Módulos Relacionados

Os módulos abaixo complementam a área fiscal com funcionalidades de recebimento de notas, resultado financeiro e custo de produção:

Módulo	Rota	Descrição
NF-e Entrada	`/admin/inbound-nfe`	Consulta e manifestação de NF-es de fornecedores
DRE	`/admin/dre`	P&L por competência, despesas operacionais e Plano de Contas
Fichas Técnicas	`/admin/bom`	Custo de produção por prato, atualizado automaticamente

Backend

backend/src/fiscal/fiscal.module.ts
backend/src/fiscal/fiscal.service.ts
backend/src/fiscal/fiscal.controller.ts
backend/src/fiscal/schemas/fiscal-document.schema.ts
backend/src/fiscal/accountant.controller.ts
backend/src/fiscal-queue/ (módulo de fila BullMQ)
backend/src/ncm-lookup/ (módulo de busca NCM)
backend/src/tax-engine/ (serviço TaxEngine)
backend/src/certificates/certificate.scheduler.ts

NF-e / Documentos Fiscais ​

Visão Geral ​

Localização ​

Funcionalidades ​

Status dos Documentos ​

Emissão de NF-e via Tela de Pedidos ​

Configuração Necessária (Settings) ​

Grupos Fiscais ​

Localização do Componente ​

Campos do Grupo Fiscal ​

NT 2025.002 — Reforma Tributária (CRT 3 apenas) ​

Campos NT 2025.002 ​

Tabela de CST IBS/CBS (Tabela A, Apêndice III — NT 2025.002) ​

API ​

Campos do Documento ​

Fluxo Completo ​

Homologação x Produção ​

Componentes Relacionados ​

NCM Autocomplete ​

Auto-emissão (BullMQ) ​

Fiscal Queue Stats ​

Notificações Fiscais em Tempo Real ​

Certificado Digital A1 ​

Portal do Contador ​

Convidar Contador ​

Painel Fiscal (Admin) ​

Módulos Relacionados ​

Backend ​