Skip to content

Latest commit

 

History

History
291 lines (237 loc) · 7.27 KB

README.md

File metadata and controls

291 lines (237 loc) · 7.27 KB

VeriFacTu Library

Una librería JavaScript/TypeScript para generar facturas electrónicas compatibles con VeriFacTu de la AEAT (Agencia Estatal de Administración Tributaria).

Características

  • ✅ Generación de facturas VeriFacTu
  • ✅ Anulación de facturas VeriFacTu
  • ✅ Generación automática de códigos QR
  • ✅ Encadenamiento de facturas
  • ✅ Validación de datos
  • ✅ Soporte TypeScript completo
  • ✅ Sin dependencias de certificados digitales

Instalación

npm install verifactu-node-lib

Uso Básico

Crear una factura

import { createVerifactuInvoice, Invoice, Software } from 'verifactu-node-lib';

// Configuración del software
const software: Software = {
    developerName: "Mi Empresa Desarrolladora S.L.",
    developerIrsId: "B12345678",
    name: "Mi Software de Facturación",
    id: "SOFT_001",
    version: "1.0.0",
    number: "12345",
    useOnlyVerifactu: true,
    useMulti: true,
    useCurrentMulti: false
};

// Datos de la factura
const invoice: Invoice = {
    issuer: {
        irsId: "99999990S",
        name: "Mi Empresa S.L."
    },
    recipient: {
        irsId: "B87654321",
        name: "Cliente S.A.",
        country: "ES"
    },
    id: {
        number: "FAC-100",
        issuedTime: new Date("2024-03-18T10:00:00.000Z")
    },
    type: "F1", // Factura completa
    description: {
        text: "Servicios de consultoría",
        operationDate: new Date("2024-03-18T09:00:00.000Z")
    },
    vatLines: [
        {
            vatOperation: "S1", // Operación sujeta
            base: 1000.00,
            rate: 21,
            amount: 210.00,
            vatKey: "01" // IVA general
        }
    ],
    total: 1210.00,
    amount: 210.00
};

// Crear la factura
const result = await createVerifactuInvoice(invoice, software);

console.log('QR Code:', result.qrcode);
console.log('XML base64:', result.verifactuXml);
console.log('Info encadenamiento:', result.chainInfo);

Anular una factura

import { cancelVerifactuInvoice, CancelInvoice } from 'verifactu-node-lib';

const cancelInvoice: CancelInvoice = {
    issuer: {
        irsId: "99999990S",
        name: "Mi Empresa S.L."
    },
    id: {
        number: "FAC-100",
        issuedTime: new Date("2024-03-18T10:00:00.000Z")
    }
};

const result = await cancelVerifactuInvoice(cancelInvoice, software);
console.log('Factura anulada:', result.chainInfo);

Factura con encadenamiento

import { PreviousInvoiceId } from 'verifactu-node-lib';

// Información de la factura anterior
const previousInvoice: PreviousInvoiceId = {
    issuerIrsId: "99999990S",
    number: "FAC-099",
    issuedTime: new Date("2024-03-17T10:00:00.000Z"),
    hash: "abc123def456789..."
};

// Crear factura con encadenamiento
const result = await createVerifactuInvoice(invoice, software, previousInvoice);

Tipos de Factura

Facturas Completas (F1)

Requieren destinatario identificado:

const invoice: Invoice = {
    // ...otros campos
    type: "F1",
    recipient: {
        irsId: "B87654321",
        name: "Cliente S.A.",
        country: "ES"
    }
    // ...
};

Facturas Simplificadas (F2)

No requieren destinatario:

const invoice: Invoice = {
    // ...otros campos
    type: "F2",
    // Sin campo recipient
    // ...
};

Facturas Rectificativas (R1, R2, R3, R4)

Para correcciones de facturas anteriores:

const invoice: Invoice = {
    // ...otros campos
    type: "R1",
    creditNote: {
        ids: [{
            number: "FAC-099",
            issuedTime: new Date("2024-03-17T10:00:00.000Z")
        }],
        style: "S", // Sustitución
        creditBase: 100.00,
        creditVat: 21.00
    }
    // ...
};

Líneas de IVA

Operación Sujeta (S1, S2)

{
    vatOperation: "S1",
    base: 1000.00,
    rate: 21,
    amount: 210.00,
    vatKey: "01"
}

Operación Exenta (E1-E6)

{
    vatOperation: "E1",
    base: 1000.00,
    rate: 0,
    amount: 0,
    vatKey: "02"
}

Operación No Sujeta (N1, N2)

{
    vatOperation: "N1",
    base: 1000.00,
    rate: 0,
    vatKey: "07"
}

Claves de Régimen de IVA

  • "01": Operación de régimen general
  • "02": Exportación
  • "03": Operaciones a las que se aplique el régimen especial de bienes usados, objetos de arte, antigüedades y objetos de colección
  • "04": Régimen especial del oro de inversión
  • "05": Régimen especial de las agencias de viajes
  • "06": Régimen especial grupo de entidades en IGIC (Nivel Avanzado)
  • "07": Régimen especial del criterio de caja
  • "08": Operaciones sujetas al IPSI / IVA (Impuesto sobre la Producción, los Servicios y la Importación / Impuesto sobre el Valor Añadido)
  • "09": Facturación de las prestaciones de servicios de agencias de viaje que actúan como mediadoras en nombre y por cuenta ajena (D.A.4ª RD1619/2012)
  • "10": Cobros por cuenta de terceros de honorarios profesionales o de derechos derivados de la propiedad industrial, de autor u otros por cuenta de sus socios, asociados o colegiados efectuados por sociedades, asociaciones, colegios profesionales u otras entidades que realicen estas funciones de cobro
  • "11": Operaciones de arrendamiento de local de negocio
  • "14": Factura con IGIC pendiente de devengo en certificaciones de obra cuyo destinatario sea una Administración Pública
  • "15": Factura con IGIC pendiente de devengo en operaciones de tracto sucesivo
  • "17": Régimen especial de comerciante minorista
  • "18": Régimen especial del pequeño empresario o profesional
  • "19": Operaciones interiores exentas por aplicación artículo 25 Ley 19/1994

Países Soportados

La librería soporta todos los códigos de país ISO 3166-1 alpha-2. Ejemplos:

  • "ES": España
  • "FR": Francia
  • "DE": Alemania
  • "PT": Portugal
  • "US": Estados Unidos

Validaciones

La librería incluye validaciones automáticas para:

  • ✅ Formato de NIF/CIF
  • ✅ Campos obligatorios
  • ✅ Tipos de factura válidos
  • ✅ Operaciones de IVA correctas
  • ✅ Importes numéricos
  • ✅ Fechas válidas

Resultado

Todas las operaciones devuelven un objeto VerifactuResult:

interface VerifactuResult {
    qrcode: string | null;        // Código QR en formato data URL (solo facturas)
    chainInfo: PreviousInvoiceId; // Información para el siguiente encadenamiento
    verifactuXml: string;         // XML codificado en base64
}

Manejo de Errores

try {
    const result = await createVerifactuInvoice(invoice, software);
    // Procesar resultado exitoso
} catch (error) {
    console.error('Error creando factura:', error.message);
    // Manejar el error
}

Ejemplos Completos

Consulta el archivo example.ts para ver ejemplos completos de uso.

Limitaciones

  • Esta librería NO firma digitalmente las facturas
  • NO envía las facturas a la AEAT
  • Se centra únicamente en la generación del XML VeriFacTu

Para el envío a la AEAT necesitarás:

  1. Certificado digital válido
  2. Implementar la comunicación SOAP con los servicios de la AEAT
  3. Firmar digitalmente el XML generado

Licencia

MIT

Contribuir

Las contribuciones son bienvenidas. Por favor, abre un issue o envía un pull request.

Soporte

Para soporte y preguntas, abre un issue en el repositorio.