NFe-Utils

Biblioteca de utilitários para parse e processamento de NFe.

Instalação

npm install
npm run build

Uso

Método 1: Parse de XML NFe

import { NFEUtils } from 'nfewizard-utils';

// Instanciar sem certificado (apenas parse)
const nfeUtils = new NFEUtils();

// Instanciar com certificado (parse + assinatura)
const nfeUtilsComCert = new NFEUtils({
    certPath: '/caminho/para/certificado.pfx',
    certPassword: 'senha_do_certificado',
    useOpenSSL: true, // opcional, padrão true
    schemasPath: '/caminho/para/schemas', // opcional
    logger: { // opcional - configuração do logger
        exibirLogNoConsole: true,  // Exibe logs no console (padrão: false)
        armazenarLogs: true,       // Salva logs em arquivos (padrão: false)
        pathLogs: './logs'         // Diretório dos logs
    }
});

// Usar o método
const nfeData = {
    idLote: 1,
    indSinc: 1,
    NFe: {
        infNFe: {
            // dados da NFe...
        }
    }
};

// Parse sem assinatura (padrão)
const result = await nfeUtils.parseXMLNFe(nfeData);

// Parse com assinatura (somente se certificado estiver configurado)
const resultComAssinatura = await nfeUtils.parseXMLNFe(nfeData, { assinarXml: true });

if (result.success) {
    console.log('XML gerado:', result.xml);
} else {
    console.error('Erro:', result.message);
}

Opções do parseXMLNFe

O método parseXMLNFe aceita um segundo parâmetro opcional opcoes com as seguintes propriedades:

• assinarXml (boolean, padrão: false): Define se o XML deve ser assinado digitalmente

// Parse sem assinatura
const result = await nfeUtils.parseXMLNFe(nfeData);

// Parse com assinatura
const resultComAssinatura = await nfeUtils.parseXMLNFe(nfeData, { assinarXml: true });

Nota: Para usar a assinatura (assinarXml: true), é obrigatório configurar certPath e certPassword na inicialização da classe NFEUtils. Se assinarXml for true mas não houver certificado configurado, o XML será gerado sem assinatura.

Método 2: Assinatura de XML

import { NFEUtils } from 'nfewizard-utils';

// Instanciar COM certificado (obrigatório para assinatura)
const nfeUtils = new NFEUtils({
    certPath: '/caminho/para/certificado.pfx',
    certPassword: 'senha_do_certificado'
});

// Assinar XML (funciona com NFe individual ou envelope enviNFe)
const xmlParaAssinar = '<NFe>...</NFe>';
const result = await nfeUtils.signXML(xmlParaAssinar, 'infNFe');

if (result.success) {
    console.log('XML assinado:', result.signedXml);
} else {
    console.error('Erro:', result.message);
}

Comportamento do signXML:

• Se o XML for uma NFe individual (<NFe>...</NFe>), a assinatura será colocada dentro da tag <NFe> após <infNFe>
• Se o XML for um envelope enviNFe (<enviNFe>...</enviNFe>), cada NFe individual será assinada separadamente
• A assinatura sempre fica no local correto conforme o padrão da NFe

Método 3: Validação de Schemas

import { NFEUtils } from 'nfewizard-utils';

const nfeUtils = new NFEUtils({
    schemasPath: '/caminho/para/schemas' // opcional
});

// Validação baseada em JavaScript (libxmljs2)
const resultJs = await nfeUtils.validateSchemaJsBased(xmlString, 'NFEAutorizacao');

// Validação baseada em Java (xsd-schema-validator)
const resultJava = await nfeUtils.validateSchemaJavaBased(xmlString, 'NFEAutorizacao');

if (resultJs.success) {
    console.log('XML válido!');
} else {
    console.error('Erro de validação:', resultJs.message);
}

Métodos Auxiliares

// Configurar novo caminho para schemas
nfeUtils.setSchemasPath('/novo/caminho/schemas');

// Obter caminho atual dos schemas
const currentPath = nfeUtils.getSchemasPath();

Configuração de Logging

A biblioteca inclui um sistema de logging completo que pode ser configurado de duas formas:

Opção 1: Configuração Integrada (Recomendado)

import { NFEUtils } from 'nfewizard-utils';

const nfeUtils = new NFEUtils({
    certPath: 'certificado.pfx',
    certPassword: '1234',
    useOpenSSL: false,
    schemasPath: 'src/schemas',
    logger: {
        exibirLogNoConsole: true,  // Exibir logs no console
        armazenarLogs: true,       // Salvar logs em arquivos
        pathLogs: './logs'         // Diretório dos logs
    }
});

Opção 2: Configuração Manual

import { NFEUtils, logger } from 'nfewizard-utils';

// Configure o logger manualmente antes de usar a biblioteca
logger.initialize({
    exibirLogNoConsole: true,
    armazenarLogs: true,
    pathLogs: './logs'
});

const nfeUtils = new NFEUtils({
    certPath: 'certificado.pfx',
    certPassword: '1234'
});

Estrutura dos Logs

Os logs seguem padrões específicos para cada contexto:

Logs de Informação:

logger.info('Salvando arquivos gerados', {
    context: 'XmlBuilder',
    method: 'assinarXML',
    totalFiles: 5,
    timestamp: Date.now()
});

Logs de Erro:

logger.error('💥Erro ao processar certificado', {
    context: 'CertificateLoader',
    method: 'loadCertificate',
    error: error.message,
    stack: error.stack,
    timestamp: Date.now()
});

Arquivos de Log

Quando armazenarLogs: true, os logs são salvos em:

• app.jsonl: Todos os logs (info, warn, debug) exceto HTTP
• error.jsonl: Apenas logs de erro
• http.jsonl: Apenas logs HTTP (se houver)

Uso Individual dos Módulos

Você também pode usar os módulos individualmente:

import { 
    CertificateLoader, 
    XmlBuilder, 
    SchemaValidator,
    ValidaCPFCNPJ,
    NFECalculadora,
    logger 
} from 'nfewizard-utils';

// Configurar logger para módulos individuais
logger.initialize({
    exibirLogNoConsole: true,
    armazenarLogs: false
});

// Carregamento de certificado
const certLoader = new CertificateLoader();
const certResult = await certLoader.loadCertificate('cert.pfx', 'senha');

// Construção de XML
const xmlBuilder = new XmlBuilder(certResult.certificate, certResult.cert_key);
const xml = xmlBuilder.gerarXml(objeto, 'rootTag');

// Validação de schemas
const validator = new SchemaValidator('/path/schemas');
const isValid = await validator.validateSchemaJsBased(xml, 'NFEAutorizacao');

// Validação de CPF/CNPJ
const cpfCnpjValidator = new ValidaCPFCNPJ();
const result = cpfCnpjValidator.validarCpfCnpj('12345678901');

// Cálculos NFe
const calculadora = new NFECalculadora();
const { chaveAcesso, dv } = calculadora.calcularDigitoVerificador(nfeData);

Características

Método 1 - Parse NFe

• Assinatura Opcional: Assina o XML apenas se certificado for fornecido na inicialização
• Cálculo de DV: Calcula automaticamente o dígito verificador da chave de acesso
• Compatibilidade: Mantém total compatibilidade com os tipos existentes em nfewizard-io
• Logging Integrado: Logs automáticos para todas as operações de parse

Método 2 - Assinatura XML

• Standalone: Assina qualquer XML independentemente
• Flexível: Permite especificar qual tag assinar (padrão: 'infNFe')
• Certificado Obrigatório: Verifica se certificado está configurado
• Logging Detalhado: Rastreamento completo do processo de assinatura

Método 3 - Validação Schemas

• Dupla Implementação: JavaScript (libxmljs2) e Java (xsd-schema-validator)
• Configurável: Permite personalizar caminho dos schemas
• Logging de Validação: Logs detalhados dos resultados de validação

Sistema de Logging

• Configuração Flexível: Configure via parâmetros da NFEUtils ou manualmente
• Múltiplos Destinos: Console e/ou arquivos JSONL
• Contextos Organizados: Logs categorizados por contexto e método
• Padrões Consistentes: Estrutura padronizada para todos os logs
• Tipos de Log: Info, Warning, Error, Debug e HTTP

Licença

GPL-3.0