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

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 <enviNFe>)
• ✅ 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

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: '[email protected]',
                pass: '123456' 
            },
            emailParams: {
                from: 'Company <[email protected]>',
                to: '[email protected]',
            }
        },
        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);

Nomes dos arquivos salvos na Distribuição DFe

Com baixarXMLDistribuicao habilitado, cada docZip é salvo com nome único para evitar sobrescrita quando existirem múltiplos documentos para a mesma chave no mesmo lote.

• Resumo (resNFe): <chave>-res-<nsu>.xml
• Documento processado (nfeProc): <chave>-proc-<nsu>.xml
• Evento (procEventoNFe): <chave>-event-<tpEvento>-<nsu>.xml

Exemplo:

3525...1234-res-000000000000101.xml
3525...1234-proc-000000000000102.xml
3525...1234-event-110110-000000000000103.xml

🚧 Requisitos

JDK (Opcional)

Para algumas funções, o JDK é necessário. Caso esteja rodando em ambientes sem suporte ao JDK (Vercel, etc.), configure:

lib: {
    useForSchemaValidation: 'validateSchemaJsBased'
}

Exemplo CJS (CommonJS)

const NFeWizard = require('nfewizard-io').default;

Serverless Framework

Marque como dependência externa no .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
• Guia de Migração v1.0.0: BREAKING_CHANGES.md
• Exemplos de Uso: Pasta examples/
  • Exemplos de NFe
  • Guia de Build
  • Instalação Local para Testes
• CTe: Documentação CTe

🔄 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

✨ 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 <enviNFe> quanto apenas com o elemento <NFe>:

// Objeto tipado (comportamento original — mantido)
await nfeWizard.NFE_Autorizacao(nfeObject);

// String XML completa (com enviNFe)
const xmlComEnvelope = '<enviNFe versao="4.00" ...>...</enviNFe>';
await nfeWizard.NFE_Autorizacao(xmlComEnvelope);

// String XML sem envelope (a lib adiciona <enviNFe> automaticamente)
const xmlSemEnvelope = '<NFe xmlns="http://www.portalfiscal.inf.br/nfe">...</NFe>';
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:

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 <NFe>, o envelope <enviNFe versao="4.00"> é adicionado automaticamente antes da validação.

Tratamento de erro:

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

{
  "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)

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug NFe Wizard",
            "skipFiles": ["<node_internals>/**"],
            "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:

## 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

{"context":"NFE_ConsultaProtocolo","error":{"message":"Rejeição: Consumo Indevido",...}

🤝 Contribua

• Issues: GitHub Issues
• Doações: GitHub Sponsors
• Pix: 944ce2f2-e90f-400a-a388-bb1fe6719e02 (Marco Lima)

Outras formas de contribuir

• ⭐ Dar uma estrela no GitHub
• 🐛 Reportar bugs e sugerir melhorias
• 📝 Contribuir com código e documentação
• 📢 Compartilhar o projeto

👨‍💻 Criador

| | | :---: | | Marco Lima |

📄 Licença

Projetado com ♥ por Marco Lima. Licenciado sob a GPL-3.0.