NFEWizard-NFe-lite

Biblioteca simplificada para transmissão de NFe pré-assinada e validada.

Descrição

Esta biblioteca foi criada como uma versão simplificada do NFEWizard-io, focada exclusivamente na transmissão de NFe que já foram validadas e assinadas. Ela remove a complexidade de validação de schemas e assinatura digital, concentrando-se apenas na comunicação com os webservices da SEFAZ.

✨ Funcionalidades

🚀 Principais Recursos

• Transmissão de NFE: Método principal para envio de XMLs pré-assinados e validados
• Configuração de Certificados: Suporte completo a certificados PFX e cadeia de CAs
• HTTPS Agent Seguro: Comunicação segura com a SEFAZ usando certificados
• Processamento Assíncrono: Consulta automática de retorno com nRec e sistema de retry
• Sistema de Logging Estruturado: Logs categorizados (app.jsonl, error.jsonl, http.jsonl)
• Validação de Retorno: Processamento das respostas da SEFAZ
• TypeScript Nativo: Tipagem completa e intellisense
• Suporte ES/CJS: Compatibilidade com módulos ES6 e CommonJS

Instalação

npm install nfewizard-nfe

Uso Básico

import { transmitNFE } from 'nfewizard-nfe';
import * as fs from 'fs';

// Configuração
const config = {
  tpAmb: 2, // 1 = Produção, 2 = Homologação
  cUF: '35', // Código da UF (35 = São Paulo)
  certificate: {
    pfx: fs.readFileSync('./certificado.pfx'), // Buffer do certificado
    password: 'senha-do-certificado'
  },
  logger: {
    exibirLogNoConsole: true,    // Exibir logs no console
    armazenarLogs: true,         // Salvar logs em arquivos
    pathLogs: './logs'           // Diretório para os logs
  }
};

// XML da NFe já assinado e validado
const xmlAssinado = `<?xml version="1.0" encoding="UTF-8"?>
<NFe xmlns="http://www.portalfiscal.inf.br/nfe">
  <!-- Seu XML NFe completo aqui -->
</NFe>`;

// Opções de transmissão
const options = {
  saveFiles: true,
  pathXMLAutorizacao: './output/xmls',
  incluirTimestampNoNomeDosArquivos: true,
  saveLogs: true
};

// Transmissão
async function transmitir() {
  try {
    const resultado = await transmitNFE(xmlAssinado, config, options);
    
    if (resultado.success) {
      console.log('NFe transmitida com sucesso!');
      console.log('Motivos:', resultado.xMotivo);
    } else {
      console.log('Erro na transmissão:', resultado.errors);
    }
  } catch (error) {
    console.error('Erro:', error);
  }
}

transmitir();

🔐 Certificados Pré-Processados (Recomendado para Produção)

Para melhorar a performance e facilitar o uso em ambientes como AWS Lambda, você pode fornecer o certificado já processado em formato PEM:

Vantagens

• ⚡ Performance: Não processa o PFX a cada requisição
• 🔒 Segurança: Armazene certPem e certKey em AWS Secrets Manager, variáveis de ambiente, etc.
• ☁️ Cloud-Friendly: Ideal para Lambda e outros ambientes serverless
• 💾 Cache: Processe uma vez e reutilize

Uso com Certificado Pré-Processado

import { transmitNFE } from 'nfewizard-nfe';

const config = {
  tpAmb: 2,
  cUF: '35',
  certificate: {
    // Forneça o certificado e chave já em formato PEM
    certPem: process.env.CERT_PEM,  // Certificado em PEM
    certKey: process.env.CERT_KEY   // Chave privada em PEM
  }
};

const resultado = await transmitNFE(xmlAssinado, config);

Como Obter certPem e certKey

Você pode processar o PFX uma vez e armazenar os valores:

import { CertificateManager } from 'nfewizard-nfe';
import * as fs from 'fs';

// Processar o PFX uma vez
const config = {
  tpAmb: 2,
  cUF: '35',
  certificate: {
    pfx: fs.readFileSync('./certificado.pfx'),
    password: 'senha-do-certificado'
  }
};

const certManager = new CertificateManager(config);
const { certificate, cert_key } = await certManager.loadCertificate();

// Agora você pode armazenar esses valores:
console.log('CERT_PEM:', certificate);
console.log('CERT_KEY:', cert_key);

// Salve em variáveis de ambiente, AWS Secrets Manager, etc.
// e use nas próximas requisições sem processar o PFX novamente

Exemplo Completo AWS Lambda

import { transmitNFE } from 'nfewizard-nfe';

export const handler = async (event: any) => {
  // Certificados armazenados em variáveis de ambiente ou Secrets Manager
  const config = {
    tpAmb: 2,
    cUF: '35',
    certificate: {
      certPem: process.env.CERT_PEM!,
      certKey: process.env.CERT_KEY!
    },
    logger: {
      exibirLogNoConsole: true,
      armazenarLogs: false  // Não salvar em arquivos no Lambda
    }
  };

  const resultado = await transmitNFE(event.xml, config);
  
  return {
    statusCode: resultado.success ? 200 : 400,
    body: JSON.stringify(resultado)
  };
};

Para mais exemplos, veja: examples/certificado-preprocessado.ts

Uso Avançado com Classes

import { NFETransmissionService } from 'nfewizard-nfe';

const service = new NFETransmissionService(config);

const resultado = await service.transmitNFE(xmlAssinado, {
  saveFiles: true,
  pathXMLAutorizacao: './arquivos-gerados'
});

Sistema de Logs

A biblioteca possui um sistema completo de logs estruturados, similar ao NFEWizard-io original, com três tipos de logs:

Tipos de Logs

1. app.jsonl - Logs gerais da aplicação (info, warn, debug, error - exceto http)
2. error.jsonl - Apenas logs de erro
3. http.jsonl - Apenas logs de comunicação HTTP com webservices

Configuração de Logs

import { transmitNFE, logger } from 'nfewizard-nfe';

// Configuração via config principal
const config = {
  // ... outras configurações
  logger: {
    exibirLogNoConsole: true,    // true = exibe no console, false = silencioso
    armazenarLogs: true,         // true = salva em arquivos, false = não salva
    pathLogs: './logs'           // diretório onde salvar os logs
  }
};

// Override via options de transmissão
const resultado = await transmitNFE(xml, config, {
  logger: {
    exibirLogNoConsole: false,   // Override apenas para esta operação
    pathLogs: './logs-especifico'
  }
});

Uso do Logger Diretamente

import { logger } from 'nfewizard-nfe';

// Inicializar logger
logger.initialize({
  exibirLogNoConsole: true,
  armazenarLogs: true,
  pathLogs: './meus-logs'
});

// Usar logger
logger.info('Operação iniciada', { 
  context: 'MeuModulo', 
  usuario: 'admin' 
});

logger.http('Requisição HTTP', { 
  url: 'https://...', 
  method: 'POST' 
});

logger.error('Erro capturado', error, { 
  context: 'MeuModulo' 
});

logger.warn('Aviso importante', { 
  motivo: 'Certificado próximo do vencimento' 
});

logger.debug('Informação de debug', { 
  detalhes: {...} 
});

Estrutura dos Logs

Os logs são salvos em formato JSONL (JSON Lines), onde cada linha é um objeto JSON:

{"timestamp":"2025-09-23T10:30:15.123Z","level":"info","message":"NFe transmitida com sucesso","context":"NFETransmissionService","method":"transmitNFE","totalXMLs":1}
{"timestamp":"2025-09-23T10:30:15.456Z","level":"http","message":"Comunicação concluída","context":"WebServiceConnector","url":"https://...","duration":"1250ms"}
{"timestamp":"2025-09-23T10:30:15.789Z","level":"error","message":"Erro na validação","context":"ValidationUtils","error":{"message":"XML inválido","stack":"..."}}

Configuração

NFEConfig

interface NFEConfig {
  /**
   * Ambiente: 1 para produção, 2 para homologação
   */
  tpAmb: 1 | 2;
  
  /**
   * Código da UF (Unidade Federativa)
   */
  cUF: string;
  
  /**
   * Dados do certificado digital
   */
  certificate: {
    // Opção 1: Fornecer o certificado PFX (será processado automaticamente)
    pfx?: Buffer;      // Arquivo PFX como Buffer
    password?: string; // Senha do certificado
    
    // Opção 2: Fornecer o certificado já processado (recomendado para Lambda/produção)
    certPem?: string;  // Certificado em formato PEM
    certKey?: string;  // Chave privada em formato PEM
    
    // Nota: Se certPem e certKey forem fornecidos, eles terão prioridade
    // e o processamento do PFX será ignorado
  };

  /**
   * Cadeia de Autoridades Certificadoras (opcional)
   */
  ca?: {
    /**
     * Caminho para diretório com certificados CA (padrão: './ca')
     */
    path?: string;
    /**
     * Buffers de certificados CA customizados
     */
    certificates?: Buffer[];
  };

  /**
   * Configuração do sistema de logs
   */
  logger?: {
    exibirLogNoConsole?: boolean; // Exibir logs no console (padrão: false)
    armazenarLogs?: boolean;      // Salvar logs em arquivos (padrão: false)
    pathLogs?: string;            // Caminho para salvar logs (padrão: './logs')
  };
  
  /**
   * Opções de salvamento de arquivos DFe
   */
  dfe?: {
    // === Salvamento de XMLs Finais (NFe + protNFe) ===
    /** Habilitar salvamento do XML final autorizado (padrão: false) */
    armazenarXMLAutorizacao?: boolean;
    /** Caminho para salvar XMLs finais autorizados (padrão: './tmp/Autorizacao') */
    pathXMLAutorizacao?: string;
    /** Salvar XMLs finais também em formato JSON (padrão: false) */
    armazenarJSONAutorizacao?: boolean;
    
    // === Logs de Consulta (XML enviado para SEFAZ) ===
    /** Habilitar salvamento de logs de consulta (padrão: false) */
    armazenarXMLConsulta?: boolean;
    /** Caminho para salvar logs de consulta (padrão: './tmp/RequestLogs') */
    pathXMLConsulta?: string;
    /** Salvar XML de consulta com envelope SOAP (padrão: false) */
    armazenarXMLConsultaComTagSoap?: boolean;
    
    // === Logs de Retorno (XML recebido da SEFAZ) ===
    /** Habilitar salvamento de logs de retorno (padrão: false) */
    armazenarXMLRetorno?: boolean;
    /** Caminho para salvar logs de retorno (padrão: './tmp/RequestLogs') */
    pathXMLRetorno?: string;
    /** Salvar retornos também em formato JSON (padrão: false) */
    armazenarRetornoEmJSON?: boolean;
    
    // === Opções Gerais ===
    /** Incluir timestamp nos nomes dos arquivos (padrão: false) */
    incluirTimestampNoNomeDosArquivos?: boolean;
    
    /** Habilitar retry automático para autorização assíncrona quando status = 105 (padrão: false) */
    habilitarRetryAutorizacaoAssincrona?: boolean;
  };

  /**
   * Opções da biblioteca
   */
  lib?: {
    /**
     * Usar OpenSSL (PEM library) em vez de node-forge (padrão: true)
     * true = usa PEM (mais rápido)
     * false = usa node-forge
     */
    useOpenSSL?: boolean;
  };
}

TransmissionOptions

interface TransmissionOptions {
  /**
   * Se deve salvar os arquivos gerados
   */
  saveFiles?: boolean;
  
  /**
   * Caminho para salvar XMLs de autorização
   */
  pathXMLAutorizacao?: string;
  
  /**
   * Se deve incluir timestamp nos nomes dos arquivos
   */
  incluirTimestampNoNomeDosArquivos?: boolean;
  
  /**
   * Se deve salvar logs de requisição e resposta
   */
  saveLogs?: boolean;
  
  /**
   * Caminho para salvar arquivos de log
   */
  pathLogs?: string;

  /**
   * Override de configuração de logger para esta operação
   */
  logger?: {
    exibirLogNoConsole?: boolean;
    armazenarLogs?: boolean;
    pathLogs?: string;
  };
}

Resposta da Transmissão

interface TransmissionResult {
  success: boolean;           // Se a transmissão foi bem-sucedida
  xMotivo: GenericObject[];   // Motivos/mensagens de retorno
  xmls: GenericObject[];      // XMLs processados
  errors?: string[];          // Erros, se houver
}

Requisitos

• Node.js 16+
• Certificado digital A1 (arquivo .pfx)

Diferenças do NFEWizard-io Completo

Esta biblioteca NÃO inclui:

• ❌ Validação de schemas XSD
• ❌ Assinatura digital de XMLs
• ❌ Geração de XMLs NFe a partir de objetos
• ❌ Geração de DANFE
• ❌ Eventos (cancelamento, carta de correção, etc.)
• ❌ Consultas (status serviço, protocolo, etc.)

Esta biblioteca INCLUI APENAS:

• ✅ Transmissão de XMLs NFe pré-processados
• ✅ Comunicação com webservices SEFAZ
• ✅ Processamento de retornos
• ✅ Salvamento de arquivos resultantes

Exemplo de XML de Entrada Esperado

O XML deve estar completamente pronto para transmissão:

<?xml version="1.0" encoding="UTF-8"?>
<NFe xmlns="http://www.portalfiscal.inf.br/nfe">
  <infNFe versao="4.00" Id="NFe35200608819185000172550051111111181650832219">
    <!-- Dados da NFe já validados -->
  </infNFe>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <!-- Assinatura digital já aplicada -->
  </Signature>
</NFe>

Licença

GPL-3.0

Suporte

Para suporte completo de NFe, utilize a biblioteca principal NFEWizard-io.