facturacion-electronica-peru

Librería NPM para facturación electrónica peruana (SUNAT), conectándose a la API de Conflux.

Agnóstica al framework — sin dependencias de React, Redux ni DOM.

Instalación

npm install facturacion-electronica-peru

Uso rápido

Cliente API

import { ConfluxClient } from 'facturacion-electronica-peru';

const client = new ConfluxClient({
  baseURL: 'https://see.conflux.pe/',
  token: 'mi-token-jwt',
});

// Crear factura
const resultado = await client.invoices.create({
  enviar_automaticamente_a_la_sunat: false,
  enviar: true,
  verificar_fecha: true,
  hora_de_emision: '10:00:00',
  tipo_de_operacion: '0101',
  tipo_de_comprobante: '01',
  porcentaje_de_igv: '18.00',
  cliente_tipo_de_documento: '6',
  cliente_numero_de_documento: '20100130204',
  cliente_denominacion: 'EMPRESA SAC',
  cliente_direccion: 'Av. Principal 123',
  serie: 'F001',
  fecha_de_emision: '2025-01-15',
  moneda: 'PEN',
  items: [{
    gratuito: false,
    cantidad: 1,
    unidad_de_medida: 'ZZ',
    codigo: 'SRV001',
    descripcion: 'Servicio de consultoría',
    igv: 18,
    inc_igv: true,
    precio_unitario: '118',
    tipo_de_igv: '10',
    valor_unitario: 100,
    total: 118,
    subtotal: 100,
    descuento_base: 0,
    descuento_factor: 0,
    descuento_importe: 0,
  }],
  // ... más campos
});

// Listar comprobantes
const comprobantes = await client.invoices.list({ page: 1, limit: 20 });

// Firmar comprobante
await client.invoices.sign({ invoice: 'uid-del-comprobante' });

// Anular comprobante
await client.invoices.void({ invoice: 'uid-del-comprobante' });

Motor de cálculo (standalone, sin API)

import { InvoiceCalculator } from 'facturacion-electronica-peru';

const calc = new InvoiceCalculator({ porcentajeIgv: 18 });

// Calcular item con IGV incluido
const item = calc.calculateItem({
  precio_venta_unitario: 118,
  cantidad: 2,
  inc_igv: true,
  tipo_de_igv: '10',
});
// → { valorVenta: 200, igv: 36, precioVenta: 236, valorUnitario: 100 }

// Calcular totales del comprobante
const totales = calc.calculateTotals([
  { tipo_de_igv: '10', igv: 36, valor_venta: 200, precio_venta: 236 },
]);
// → { total: 236, total_gravada: 200, total_igv: 36, ... }

// Calcular detracción
const detraccion = calc.calculateDetraction(1000, 12);
// → 120

// Calcular retención
const retencion = calc.calculateRetention(1000, '01'); // 3%
// → 30

Validar comprobante antes de enviar

import { validateInvoice } from 'facturacion-electronica-peru';

const errors = validateInvoice(invoicePayload);
// → null (válido) o { message: 'descripción del error' }

// Con validación de emisor ≠ receptor
const errors2 = validateInvoice(invoicePayload, '20123456789');

Catálogos SUNAT

import { catalogs } from 'facturacion-electronica-peru';

catalogs.tiposIgv();          // Tipos de IGV (Catálogo 07)
catalogs.unidadesMedida();     // Unidades de medida
catalogs.motivosNotaCredito(); // Motivos de nota de crédito
catalogs.tiposOperacion();     // Tipos de operación
catalogs.monedas();            // PEN, USD
catalogs.motivosTraslado();    // Motivos de traslado (guías)
// ... y más

Utilidades

import { validateRuc, formatCurrency, zeroFill } from 'facturacion-electronica-peru';

validateRuc('20100130204'); // true
formatCurrency(1180.50, 'PEN'); // "S/1180.50"
zeroFill(1, 3); // "001"

Módulos disponibles

| Módulo | Servicio | Descripción | |--------|----------|-------------| | client.invoices | InvoiceService | Facturas, boletas, notas de crédito/débito | | client.guides | GuideService | Guías de remisión | | client.retentions | RetentionService | Retenciones electrónicas | | client.perceptions | PerceptionService | Percepciones electrónicas | | client.summaries | SummaryService | Resúmenes diarios de boletas | | client.batches | BatchService | Comunicación de baja | | client.liquidations | LiquidationService | Liquidaciones de compra | | client.products | ProductService | Gestión de productos | | client.partners | PartnerService | Gestión de clientes/proveedores | | client.series | SerialService | Gestión de series | | client.categories | CategoryService | Categorías de productos | | client.app | AppService | Consulta RUC, tipo de cambio |

Tipos de comprobante soportados

| Código | Tipo | |--------|------| | 01 | Factura | | 03 | Boleta de Venta | | 04 | Liquidación de Compra | | 07 | Nota de Crédito | | 08 | Nota de Débito |

Tipos de IGV (Catálogo SUNAT 07)

| Código | Descripción | Afectación | |--------|-------------|------------| | 10 | Gravado - Operación Onerosa | Aplica IGV | | 11-16 | Gravado - Retiros | Gratuito | | 20 | Exonerado - Operación Onerosa | Sin IGV | | 21 | Exonerado - Transferencia Gratuita | Gratuito | | 30 | Inafecto - Operación Onerosa | Sin IGV | | 31-36 | Inafecto - Retiros | Gratuito | | 40 | Inafecto - Exportación | Sin IGV |

Porcentajes de IGV soportados

• 18% — Estándar
• 10.5% — Ley 31556 y 32387
• 10% — Ley 31556
• 4% — IVAP

Validaciones de negocio incluidas

• Emisor ≠ Receptor
• Serie obligatoria
• Al menos un item con descripción y UOM
• Factura requiere RUC válido (módulo 11)
• Tipo de IGV vs tipo de operación (exportación, selva)
• Notas crédito/débito: formato serie-número, tipo compatible
• Detracción: código obligatorio, datos de transporte para código 027
• Moneda extranjera: tipo de cambio > 0
• Crédito: cuotas válidas (montos > 0, fechas posteriores a emisión)
• Observaciones sin caracteres especiales

Requisitos

• Node.js >= 16
• Compatible con ESM y CommonJS

Desarrollo

npm install
npm test        # Ejecutar tests
npm run build   # Compilar para distribución
npm run lint    # Verificar tipos

Licencia

MIT

facturacion-electronica-peru