📋 Módulo de Homologação SEFAZ - NF-e Brasil

Projeto de exemplo demonstrando a implementação da biblioteca NFeWizard.io em uma aplicação Next.js para emissão e gestão de Notas Fiscais Eletrônicas (NF-e).

Projeto de Demonstração - Não Pronto para Produção

AVISO IMPORTANTE

PROJETO EM DESENVOLVIMENTO - NÃO PRONTO PARA PRODUÇÃO

Este é um projeto de exemplo/demonstração para fins educacionais e de aprendizado.

❌ NÃO utilize este código diretamente em ambiente de produção

✅ USE COMO: Referência de implementação, base para estudos, ponto de partida para seu próprio projeto

Limitações conhecidas:

Suporte limitado a apenas 1 produto por NF-e
Validações fiscais simplificadas
Sem sistema de autenticação/autorização de usuários
Sem persistência em banco de dados
Motor fiscal local básico
Funcionalidades incompletas para cenários complexos
Sem testes automatizados abrangentes

Antes de usar em produção, você DEVE:

Consultar um contador ou consultor fiscal
Implementar validações completas de negócio
Adicionar sistema robusto de autenticação
Implementar persistência adequada (banco de dados)
Adicionar logs de auditoria completos
Implementar tratamento de erros robusto
Realizar testes extensivos em homologação
Revisar completamente a segurança do sistema
Adequar às regras específicas do seu estado/município

📑 Índice

LEIA PRIMEIRO - Disclaimer Completo
Sobre o Projeto
Funcionalidades
Tecnologias
Requisitos
Instalação
Configuração
Como Usar
Mapeamento de APIs
Estrutura do Projeto
Motor Fiscal
Scripts Disponíveis
Créditos
Contribuindo
Licença

Sobre o Projeto

Este é um projeto de demonstração e exemplo que mostra como implementar a biblioteca NFeWizard.io em uma aplicação Next.js 16 com TypeScript para realizar operações básicas com o sistema SEFAZ (Secretaria da Fazenda) brasileiro.

Objetivo Principal

Servir como referência de implementação para desenvolvedores que desejam integrar NF-e em suas aplicações usando NFeWizard.io e Next.js.

Ideal para:

Aprendizado: Desenvolvedores estudando integração com SEFAZ
Prototipagem: Criação rápida de provas de conceito
Testes: Ambiente de experimentação em homologação
Referência: Base de código para projetos próprios
Estudo de Caso: Entendimento de arquitetura de integração fiscal

NÃO é ideal para:

Uso direto em ambiente de produção sem adaptações
Sistemas corporativos mission-critical
Alto volume de emissões sem otimização
Ambientes multi-tenant sem modificações

Funcionalidades

Operações NF-e Completas

Consulta Status do Serviço SEFAZ - Verifica disponibilidade dos servidores
Consulta de Protocolo - Busca detalhes de NF-e autorizadas
Autorização de NF-e - Emissão completa de notas fiscais (entrada/saída)
Cancelamento de NF-e - Cancelamento de notas autorizadas
Carta de Correção Eletrônica (CC-e) - Correção de dados de NF-e
Inutilização de Numeração - Inutiliza faixas de numeração

Motor Fiscal Inteligente

Motor Fiscal Local Gratuito - Cálculo de impostos sem APIs externas
Autocomplete de CFOP - Sugestões de operações tributárias
Autocomplete de NCM - Base completa de códigos NCM
Sugestão Inteligente de CST/ICMS - Baseada em contexto e regras
Validação de Regras Tributárias - Motor local com presets configuráveis

Interface Moderna

Wizard de Emissão em 5 Passos - Processo guiado e intuitivo
Modo Sandbox e Produção - Alternância fácil entre ambientes
Interface Responsiva - Design moderno e adaptável
Persistência Local - Configurações salvas no navegador
Visualizador de XML/JSON - Inspeção detalhada de retornos

Segurança e Controle

Certificado Digital A1 - Autenticação via certificado .pfx
Trava de Homologação - Proteção contra emissão acidental em produção
Armazenamento Organizado - Notas e logs separados por ambiente
Logs Estruturados - Rastreamento completo de operações

Tecnologias

Next.js 16 - Framework React com App Router
TypeScript - Tipagem estática e IntelliSense
NFeWizard.io - Biblioteca core para comunicação SEFAZ
React - Biblioteca UI declarativa
Tailwind CSS - Estilização moderna e responsiva
Node.js 18+ - Runtime JavaScript server-side

Requisitos

Obrigatórios

Node.js 18+ (Download)
npm ou yarn
Certificado Digital A1 (arquivo .pfx e senha)
Inscrição Estadual ativa (para emissão em produção)

Instalação

1. Clone o repositório

git clone https://github.com/unkdevv/modulo-next-sefaz.git
cd modulo-next-sefaz

2. Instale as dependências

# Instalação completa com Java/JDK (recomendado na primeira vez)
npm run setup

# OU, se você já tiver Java instalado
npm install

3. Inicie o servidor de desenvolvimento

npm run dev

4. Acesse a aplicação

Abra seu navegador em: http://localhost:3000

Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Trava emissão em produção (recomendado para desenvolvimento)
NFE_ENFORCE_HOMOLOGACAO=true

Configuração do Certificado

No formulário da aplicação, configure:

Ambiente: Homologação ou Produção
UF: Estado de emissão (ex: SP, RJ, MG)
Certificado: Upload do arquivo .pfx
Senha: Senha do certificado digital

💡 Dica: As configurações são salvas automaticamente no navegador.

Como Usar

Modo Sandbox (Homologação)

Acesse: http://localhost:3000

Configure seu certificado digital
Selecione Ambiente: Homologação
Escolha a operação desejada
Preencha os dados do formulário
Execute a operação

Modo Produção

Acesse: http://localhost:3000/producao

⚠️ ATENÇÃO: Emissões em produção geram documentos fiscais legais válidos.

Wizard de Emissão

Acesse: http://localhost:3000/producao/emissao

Processo guiado em 5 etapas:

Módulo e Identificação - Tipo de nota (entrada/saída)
Emitente - Dados da empresa emissora
Destinatário - Dados do cliente/fornecedor
Produto e Impostos - Itens e tributação
Motor Fiscal - Cálculo automático de impostos

Mapeamento de APIs

Rotas de Saúde e Configuração

Endpoint	Método	Descrição
`/api/health`	GET	Status da aplicação
`/api/config`	GET	Configurações do sistema (motor fiscal, ambiente)

Rotas de Operações NF-e

Endpoint	Método	Função	Biblioteca
`/api/status`	POST	Consulta status do serviço SEFAZ	`NFE_ConsultaStatusServico()`
`/api/protocolo`	POST	Consulta protocolo de NF-e autorizada	`NFE_ConsultaProtocolo()`
`/api/autorizacao`	POST	Autoriza emissão de NF-e	`NFE_Autorizacao()`
`/api/cancelamento`	POST	Cancela NF-e autorizada	`NFE_Cancelamento()`
`/api/carta-correcao`	POST	Emite Carta de Correção Eletrônica	`NFE_CartaDeCorrecao()`
`/api/inutilizacao`	POST	Inutiliza faixa de numeração	`NFE_Inutilizacao()`

Rotas de Catálogos e Motor Fiscal

Endpoint	Método	Descrição	Parâmetros
`/api/ncm`	GET	Busca códigos NCM	`q` (query), `limit` (max 50)
`/api/operacoes-tributarias`	GET	Lista operações tributárias (CFOP)	-
`/api/operacoes-tributarias`	POST	Sugere operações por contexto	JSON com UF, CRT, etc
`/api/fiscal/operation-codes`	GET	Lista códigos de operação fiscal	`q`, `limit`
`/api/fiscal/calculate`	POST	Calcula impostos (motor local)	JSON com dados do produto

Funções Core (lib/nfe.ts)

Função	Descrição	Retorno
`buildConfig(input)`	Valida e constrói configuração SEFAZ	`Config` validado
`consultaStatus(config)`	Consulta status do serviço	Resultado SEFAZ
`consultaProtocolo(config, chave)`	Busca protocolo por chave (44 dígitos)	Protocolo + XML
`autorizacao(config, emissao)`	Autoriza NF-e completa	Resultado + Chave de Acesso
`cancelamento(config, dados)`	Cancela NF-e (evento 110111)	Resultado do evento
`cartaCorrecao(config, dados)`	Emite CC-e (evento 110110)	Resultado do evento
`inutilizacao(config, dados)`	Inutiliza numeração	Resultado SEFAZ

Funções Motor Fiscal (lib/fiscal-engine/index.ts)

Função	Descrição	Retorno
`getFiscalEngineRuntime()`	Retorna configuração do motor	Provider local (gratuito)
`listFiscalOperationCodes(params)`	Lista códigos de operação	Array de códigos + CFOP
`calculateFiscalTaxes(input)`	Calcula ICMS, CFOP, CST	Resultado detalhado + summary

Funções de Operações Tributárias (lib/tax-operations/index.ts)

Função	Descrição	Retorno
`listTaxOperations()`	Catálogo completo de CFOPs	Array com descrições
`suggestTaxOperations(context)`	Sugestões ranqueadas por contexto	Top 6 com score e motivos

Funções de Catálogo NCM (lib/ncm-catalog/index.ts)

Função	Descrição	Retorno
`searchNcm(params)`	Busca NCM por código/descrição	Array com score + metadados

📁 Estrutura do Projeto

modulo-next-sefaz/
├── app/                              # Next.js App Router
│   ├── (workspace)/                  # Rotas principais
│   │   ├── page.tsx                  # Página inicial (sandbox)
│   │   ├── producao/
│   │   │   ├── page.tsx              # Modo produção
│   │   │   └── emissao/page.tsx      # Wizard de emissão
│   │   └── emissao/page.tsx          # Wizard sandbox
│   ├── api/                          # Rotas API REST
│   │   ├── health/route.ts
│   │   ├── config/route.ts
│   │   ├── status/route.ts
│   │   ├── protocolo/route.ts
│   │   ├── autorizacao/route.ts
│   │   ├── cancelamento/route.ts
│   │   ├── carta-correcao/route.ts
│   │   ├── inutilizacao/route.ts
│   │   ├── ncm/route.ts
│   │   ├── operacoes-tributarias/route.ts
│   │   └── fiscal/
│   │       ├── calculate/route.ts
│   │       └── operation-codes/route.ts
│   ├── layout.tsx                    # Layout global
│   └── globals.css                   # Estilos globais
├── components/
│   └── nfe-console/                  # Console principal NF-e
│       ├── index.tsx                 # Componente principal
│       ├── types.ts                  # Tipos TypeScript
│       ├── defaults.ts               # Valores padrão
│       └── utils.ts                  # Utilitários
├── lib/                              # Bibliotecas core
│   ├── nfe.ts                        # Funções NF-e (wrapper NFeWizard)
│   ├── storage.ts                    # Persistência local
│   ├── fiscal-engine/                # Motor fiscal local
│   │   └── index.ts
│   ├── ncm-catalog/                  # Catálogo NCM
│   │   └── index.ts
│   └── tax-operations/               # Operações tributárias
│       └── index.ts
├── data/
│   └── banco-de-informacoes/         # Bases de dados locais
│       ├── tabelas-fiscais/
│       │   ├── cfop.json             # CFOPs brasileiros
│       │   └── ncm.json              # NCMs completos
│       ├── operacoes-tributarias/
│       │   └── regras.json           # Regras de sugestão
│       └── status-sefaz/
│           └── cstat.json            # Status SEFAZ
├── notas-fiscais/                    # Armazenamento de NF-es
│   ├── homologacao/
│   │   ├── xml-autorizacao/
│   │   ├── danfe/
│   │   └── wizard/
│   └── producao/
│       ├── xml-autorizacao/
│       └── danfe/
├── logs-erros/                       # Logs estruturados
│   ├── app.jsonl
│   ├── error.jsonl
│   └── http.jsonl
├── .env                              # Variáveis de ambiente
├── next.config.mjs                   # Configuração Next.js
├── tsconfig.json                     # Configuração TypeScript
├── eslint.config.mjs                 # Configuração ESLint
└── package.json                      # Dependências e scripts

Motor Fiscal

O motor fiscal local e gratuito calcula automaticamente:

✅ CFOP - Código Fiscal de Operações e Prestações
✅ CST/CSOSN - Código de Situação Tributária
✅ Base de Cálculo ICMS
✅ Alíquota ICMS (por UF e regime tributário)
✅ Valor do ICMS
✅ Regras para Simples Nacional
✅ Operações Interestaduais

Contextos Suportados

Vendas Internas e Interestaduais
Operações com Contribuintes e Não-Contribuintes
Regimes: Simples Nacional, Lucro Presumido, Lucro Real
Entrada e Saída de Mercadorias
Devolução e Remessa

Presets Disponíveis

Código	Descrição	CFOP	ICMS
121	Venda Interna - Contribuinte	5102	Alíquota UF
122	Venda Interna - Não Contribuinte	5102	Alíquota UF
221	Venda Interestadual - Contribuinte	6102	Alíquota destino
222	Venda Interestadual - Não Contrib.	6108	Alíquota destino

Scripts Disponíveis

# Desenvolvimento
npm run dev           # Next.js + Webpack (recomendado)
npm run dev:turbo     # Next.js + Turbopack (experimental)

# Build e Produção
npm run build         # Build otimizado (Webpack)
npm run build:turbo   # Build com Turbopack
npm run start         # Inicia servidor de produção

# Qualidade de Código
npm run lint          # ESLint (next/core-web-vitals)
npm run typecheck     # Verificação TypeScript strict

# Instalação
npm run setup         # Instala deps + Java/JDK automaticamente

Créditos

Este projeto foi desenvolvido utilizando a biblioteca NFeWizard.io, uma solução robusta e completa para integração com o sistema SEFAZ brasileiro.

📦 NFeWizard.io

Repositório: https://github.com/nfewizard-org/nfewizard-io
Documentação: https://nfewizard.io/docs
NPM: https://www.npmjs.com/package/nfewizard-io

Agradecimentos especiais aos mantenedores do NFeWizard.io por disponibilizarem uma biblioteca de qualidade profissional que simplifica drasticamente a integração com o complexo sistema de NF-e brasileiro.

🌟 Por que NFeWizard.io?

✅ Suporte completo a NF-e 4.0
✅ Certificado Digital A1/A3
✅ Validação de schemas XML
✅ Assinatura digital integrada
✅ Comunicação SOAP com SEFAZ
✅ Tratamento de erros padronizado
✅ Suporte a múltiplos ambientes (homologação/produção)

Contribuindo

Contribuições são bem-vindas! Para contribuir:

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
Push para a branch (git push origin feature/MinhaFeature)
Abra um Pull Request

📝 Diretrizes

Mantenha o código TypeScript com tipagem forte
Siga os padrões ESLint configurados
Adicione testes quando aplicável
Documente funções públicas
Use commits semânticos

Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Links Úteis

⭐ Se este projeto foi útil, considere dar uma estrela!

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github		.github
app		app
components/nfe-console		components/nfe-console
data/banco-de-informacoes		data/banco-de-informacoes
lib		lib
logs-erros		logs-erros
notas-fiscais		notas-fiscais
.env.example		.env.example
.gitignore		.gitignore
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DISCLAIMER.md		DISCLAIMER.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo

Folders and files

Latest commit

History

Repository files navigation

📋 Módulo de Homologação SEFAZ - NF-e Brasil

AVISO IMPORTANTE

PROJETO EM DESENVOLVIMENTO - NÃO PRONTO PARA PRODUÇÃO

📑 Índice

Sobre o Projeto

Objetivo Principal

Ideal para:

NÃO é ideal para:

Funcionalidades

Operações NF-e Completas

Motor Fiscal Inteligente

Interface Moderna

Segurança e Controle

Tecnologias

Requisitos

Obrigatórios

Recomendados

Instalação

1. Clone o repositório

2. Instale as dependências

3. Inicie o servidor de desenvolvimento

4. Acesse a aplicação

Configuração

Variáveis de Ambiente

Configuração do Certificado

Como Usar

Modo Sandbox (Homologação)

Modo Produção

Wizard de Emissão

Mapeamento de APIs

Rotas de Saúde e Configuração

Rotas de Operações NF-e

Rotas de Catálogos e Motor Fiscal

Funções Core (lib/nfe.ts)

Funções Motor Fiscal (lib/fiscal-engine/index.ts)

Funções de Operações Tributárias (lib/tax-operations/index.ts)

Funções de Catálogo NCM (lib/ncm-catalog/index.ts)

📁 Estrutura do Projeto

Motor Fiscal

Contextos Suportados

Presets Disponíveis

Scripts Disponíveis

Créditos

📦 NFeWizard.io

🌟 Por que NFeWizard.io?

Contribuindo

📝 Diretrizes

Licença

Links Úteis

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages