# NFeWizard-io 🪄 ## 🛠️ Lib atualizada com NT 2025.002 v.1.35 - Reforma Tributária --- ## 📦 Pacote de Operações NFe Este é o pacote principal do ecossistema **NFeWizard**, responsável pelas **operações de NFe (Nota Fiscal Eletrônica - Modelo 55)**. A partir da versão 1.0.0, o NFeWizard foi modularizado em 7 pacotes independentes: | Pacote | Descrição | Tamanho | |--------|-----------|---------| | `nfewizard-io` | ✅ **Operações NFe** (este pacote) | 511.2 KB | | `@nfewizard/nfce` | Operações NFCe + Cancelamento | 997.7 KB | | `@nfewizard/nfse` | Operações NFSe | 578.0 KB | | `@nfewizard/danfe` | Geração de DANFE (NFe e NFCe) | 2.31 MB | | `@nfewizard/cte` | Operações CTe | 801.9 KB | | `@nfewizard/types` | Tipos TypeScript | 542.4 KB | | `@nfewizard/shared` | Utilitários compartilhados | 4.03 MB | --- ## 🚀 Instalação ```bash npm install nfewizard-io ``` --- ## 🎯 Sobre Este Pacote Este pacote fornece métodos para operações de NFe, incluindo: - ✅ **Autorização (Emissão de NFe)**: Submissão de Notas Fiscais Eletrônicas para autorização. Aceita tanto o **objeto tipado `NFe`** quanto uma **string XML** (com ou sem o envelope ``) - ✅ **Distribuição DFe**: Consulta e Download de documentos fiscais eletrônicos - ✅ **Consulta de Protocolo**: Verificação da situação da NFe na SEFAZ - ✅ **Inutilização**: Inutilização de números de NFe não utilizados - ✅ **Consulta de Status**: Monitoramento do status dos serviços da SEFAZ - ✅ **Recepção de Eventos**: - Cancelamento de NFe - Carta de Correção - Ciência da Operação - Confirmação da Operação - Desconhecimento da Operação - EPEC (Evento Prévio de Emissão em Contingência) - Operação Não Realizada - ✅ **Validação de Schema XSD (`NFE_SchemaValidate`)**: Valida qualquer XML fiscal contra o schema XSD oficial da SEFAZ, com relatório humanizado e `console.table` integrado > **⚠️ Importante**: > - Para **DANFE** (geração de PDF), instale separadamente: `npm install @nfewizard/danfe` > - Para **NFCe**, use o pacote: `npm install @nfewizard/nfce` > - Para **CTe**, use o pacote: `npm install @nfewizard/cte` > - Para **NFSe**, use o pacote: `npm install @nfewizard/nfse` --- ## 💡 Exemplo de Uso ```typescript import NFeWizard from 'nfewizard-io'; // Instanciar const nfeWizard = new NFeWizard(); // Inicializar await nfeWizard.NFE_LoadEnvironment({ config: { dfe: { baixarXMLDistribuicao: true, pathXMLDistribuicao: "tmp/DistribuicaoDFe", armazenarXMLAutorizacao: true, pathXMLAutorizacao: "tmp/Autorizacao", armazenarXMLRetorno: true, pathXMLRetorno: "tmp/RequestLogs", armazenarXMLConsulta: true, pathXMLConsulta: "tmp/RequestLogs", armazenarXMLConsultaComTagSoap: false, armazenarRetornoEmJSON: false, pathRetornoEmJSON: "tmp/DistribuicaoDFe", pathCertificado: "certificado.pfx", senhaCertificado: "1234", UF: "SP", CPFCNPJ: "99999999999999", }, nfe: { ambiente: 2, versaoDF: "4.00", idCSC: 1, tokenCSC: '99999999-9999-9999-9999-999999999999' }, email: { host: 'mail.provider.com.br', port: 465, secure: true, auth: { user: 'nfe.example@email.com.br', pass: '123456' }, emailParams: { from: 'Company ', to: 'customer.name@email.com.br', } }, lib: { connection: { timeout: 30000, }, log: { exibirLogNoConsole: true, armazenarLogs: true, pathLogs: 'tmp/Logs' }, useOpenSSL: false, useForSchemaValidation: 'validateSchemaJsBased', } } }); // Exemplo de Distribuição DFe por Chave const chaveNFe: DFePorChaveNFe = { cUFAutor: 35, CNPJ: '99999999999999', consChNFe: { chNFe: '00000000000000000000000000000000000000000000' }, } await nfeWizard.NFE_DistribuicaoDFePorChave(chaveNFe); ``` --- ## 🚧 Requisitos ### JDK (Opcional) Para algumas funções, o JDK é necessário. Caso esteja rodando em ambientes sem suporte ao JDK (Vercel, etc.), configure: ```typescript lib: { useForSchemaValidation: 'validateSchemaJsBased' } ``` ### Exemplo CJS (CommonJS) ```typescript const NFeWizard = require('nfewizard-io').default; ``` ### Serverless Framework Marque como dependência externa no `.yml`: ```yml build: esbuild: bundle: true minify: true sourcemap: true target: 'node20' format: 'cjs' external: - better-sqlite3 - mysql - mysql2 - oracledb - tedious - sqlite3 - pg-query-stream - nfewizard-io ``` --- ## 📖 Documentação - **Documentação completa**: [NFeWizard-io - Docs](https://nfewizard-org.github.io/) - **Guia de Migração v1.0.0**: [BREAKING_CHANGES.md](../../BREAKING_CHANGES.md) - **Exemplos de Uso**: Pasta [examples/](../../examples/) - [Exemplos de NFe](../../examples/NFe/) - [Guia de Build](../../examples/BUILD.md) - [Instalação Local para Testes](../../examples/INSTALACAO_LOCAL.md) - **CTe**: [Documentação CTe](../../DOCS_CTE.md) --- ## 🔄 Versão 1.0.0 - Modularização ### 🎉 Principais Mudanças - ✅ **NFe**: API 100% compatível (sem breaking changes nas operações) - ⚠️ **DANFE**: Removido deste pacote - use `@nfewizard/danfe` - ⚠️ **NFCe**: Movido para `@nfewizard/nfce` - ⚠️ **CTe**: Movido para `@nfewizard/cte` - 🆕 **NFSe**: Novo pacote `@nfewizard/nfse` (em testes) - 📉 **Redução de bundle**: Até 77% menor (4.37 MB vs 19.1 MB) - ✅ **NT 2025.002 v.130**: Suporte completo à Reforma Tributária 📋 **[Consulte o Guia Completo de Migração](../../BREAKING_CHANGES.md)** --- ## ✨ Novidades recentes (pós 1.0.0) ### Autorização aceita XML string `NFE_Autorizacao` agora aceita diretamente uma string XML (além do objeto tipado), tanto com o envelope `` quanto apenas com o elemento ``: ```typescript // Objeto tipado (comportamento original — mantido) await nfeWizard.NFE_Autorizacao(nfeObject); // String XML completa (com enviNFe) const xmlComEnvelope = '...'; await nfeWizard.NFE_Autorizacao(xmlComEnvelope); // String XML sem envelope (a lib adiciona automaticamente) const xmlSemEnvelope = '...'; await nfeWizard.NFE_Autorizacao(xmlSemEnvelope); ``` ### NFE_SchemaValidate — Validação de Schema XSD Novo método que valida qualquer XML fiscal contra o schema XSD oficial, retornando um relatório detalhado com erros humanizados: ```typescript import NFeWizard, { SchemaValidationResult } from 'nfewizard-io'; const result: SchemaValidationResult = await nfeWizard.NFE_SchemaValidate( xmlString, 'NFeAutorizacao', // SchemaValidateMethod // 'validateSchemaJsBased' // validador opcional — usa config da lib se omitido ); // result.success — boolean // result.message — resumo humanizado // result.errors[] — lista de SchemaValidationIssue com: raw, humanized, element, line, column, expected // result.report — string multilinha estilo SEFAZ-RS (já impressa automaticamente) // result.tableRows — prontos para console.table (já exibido automaticamente) // result.schema — nome do arquivo XSD utilizado ``` **Métodos (`SchemaValidateMethod`) disponíveis:** | Valor | Schema XSD | |-------|-----------| | `'NFeAutorizacao'` / `'NFEAutorizacao'` | `enviNFe_v4.00.xsd` | | `'NFEStatusServico'` | `consStatServ_v4.00.xsd` | | `'NFEConsultaProtocolo'` | `consSitNFe_v4.00.xsd` | | `'RecepcaoEvento'` | `envEvento_v1.00.xsd` | | `'NFeDistribuicaoDFe'` | `distDFeInt_v1.01.xsd` | | `'NFEInutilizacao'` | `inutNFe_v4.00.xsd` | | `'NFERetAutorizacao'` | `consReciNFe_v4.00.xsd` | | `'CTeDistribuicaoDFe'` | `cte/distDFeInt_v1.00.xsd` | | `'NFSe_Autorizacao'` | `nfse/DPS_v1.01.xsd` | | `'NFSe_Consulta'` / `'NFSe_Distribuicao'` | `nfse/NFSe_v1.01.xsd` | | `'NFSe_Eventos'` | `nfse/pedRegEvento_v1.01.xsd` | > **Nota**: para `NFeAutorizacao`/`NFEAutorizacao`, se o XML passado começar com ``, o envelope `` é adicionado automaticamente antes da validação. **Tratamento de erro:** ```typescript try { await nfeWizard.NFE_SchemaValidate(xml, 'NFeAutorizacao'); } catch (err: any) { // err.message — mensagem resumida // err.errors — SchemaValidationIssue[] // err.report — relatório completo // err.tableRows — linhas para console.table } ``` --- ## ⚙️ Configuração TypeScript ### tsconfig.json recomendado ```json { "compilerOptions": { "target": "es2020", "module": "nodenext", "outDir": "dist", "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "strict": true, "skipLibCheck": true, "sourceMap": true, "inlineSources": true, "inlineSourceMap": false, "declaration": true, "declarationMap": true, "moduleResolution": "nodenext" } } ``` ### Debug no VS Code (launch.json) ```json { "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Debug NFe Wizard", "skipFiles": ["/**"], "program": "${workspaceFolder}/src/testes.ts", "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx", "runtimeArgs": [], "console": "integratedTerminal", "env": { "NODE_ENV": "development" }, "sourceMaps": true, "restart": true, "protocol": "inspector", "outFiles": ["${workspaceFolder}/**/*.js"] } ] } ``` --- ## 📝 Observações - **Certificado**: Implementado apenas em certificados A1 - **Node.js**: Testado com versões 16 ou superiores - **UF**: Testado principalmente para São Paulo - reporte issues para outros estados --- ## 🐛 Reportando Issues Ao abrir uma issue, inclua: ```markdown ## Parametrização - UF: SP - Certificado: A1 - Método: NFE_ConsultaStatusServico - Status: ✅ Funcionando / ❌ Com erro ## Logs Relevantes Inclua logs de: app.jsonl, error.jsonl, http.jsonl ``` ```jsonl {"context":"NFE_ConsultaProtocolo","error":{"message":"Rejeição: Consumo Indevido",...} ``` --- ## 🤝 Contribua - **Issues**: [GitHub Issues](https://github.com/Maurelima/nfewizard-io/issues) - **Doações**: [GitHub Sponsors](https://github.com/sponsors/Maurelima) - **Pix**: `944ce2f2-e90f-400a-a388-bb1fe6719e02` (Marco Lima) ### Outras formas de contribuir - ⭐ Dar uma estrela no [GitHub](https://github.com/Maurelima/nfewizard-io) - 🐛 Reportar bugs e sugerir melhorias - 📝 Contribuir com código e documentação - 📢 Compartilhar o projeto --- ## 👨‍💻 Criador | [](https://github.com/Maurelima) | | :---: | | [Marco Lima](https://github.com/Maurelima) | --- ## 📄 Licença Projetado com ♥ por [Marco Lima](https://github.com/Maurelima). Licenciado sob a [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.pt-br.html).