@dwast/verifactu-lib 0.1.0-beta.0

package/src/aeat/client.ts

@@ -0,0 +1,137 @@
+/**
+ * Cliente para los servicios web de AEAT (Verifactu).
+ *
+ * Capa de red, separada del núcleo puro. Depende de credenciales y entornos
+ * (producción vs. pruebas), por lo que no debe acoplarse a la lógica de
+ * negocio.
+ *
+ * NOTA: los endpoints y el formato de petición/respuesta deben ajustarse a
+ * la documentación oficial de la AEAT (remisión voluntaria / bajo
+ * requerimiento). Este cliente expone una implementación base con `fetch`
+ * y rutas configurables.
+ */
+export interface VerifactuClientConfig {
+  /** URL base del servicio AEAT. */
+  baseUrl: string;
+  /** Token de autenticación (OAuth) o certificado. */
+  authToken?: string;
+  /** Ruta del endpoint de envío de registros. */
+  sendPath?: string;
+  /** Ruta del endpoint de consulta de estado. */
+  statusPath?: string;
+  /** Timeout de petición en ms. */
+  timeoutMs?: number;
+}
+
+export interface SendResult {
+  /** Identificador de la operación devuelto por AEAT. */
+  operationId: string;
+  /** Estado de la respuesta. */
+  status: 'OK' | 'ERROR';
+  /** Mensaje de la AEAT. */
+  message?: string;
+  /** Código de error de AEAT (si lo hay). */
+  errorCode?: string;
+  /** Cuerpo completo de la respuesta (para auditoría). */
+  rawResponse?: string;
+}
+
+interface ResolvedConfig {
+  baseUrl: string;
+  authToken?: string;
+  sendPath: string;
+  statusPath: string;
+  timeoutMs: number;
+}
+
+/**
+ * Cliente de servicios AEAT para Verifactu.
+ */
+export class VerifactuClient {
+  private readonly config: ResolvedConfig;
+
+  constructor(config: VerifactuClientConfig) {
+    this.config = {
+      sendPath: '/verifactu/registro',
+      statusPath: '/verifactu/estado',
+      timeoutMs: 10_000,
+      ...config,
+    };
+  }
+
+  /**
+   * Envía un registro (factura o evento) a AEAT.
+   */
+  async sendRecord(xml: string): Promise<SendResult> {
+    const url = `${this.config.baseUrl}${this.config.sendPath}`;
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/xml',
+      Accept: 'application/json',
+    };
+    if (this.config.authToken) {
+      headers.Authorization = `Bearer ${this.config.authToken}`;
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: xml,
+        signal: controller.signal,
+      });
+      const raw = await res.text();
+      return this.parseResponse(raw, res.status);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Consulta el estado de una operación enviada.
+   */
+  async getOperationStatus(operationId: string): Promise<SendResult> {
+    const url = `${this.config.baseUrl}${this.config.statusPath}/${encodeURIComponent(operationId)}`;
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (this.config.authToken) {
+      headers.Authorization = `Bearer ${this.config.authToken}`;
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const res = await fetch(url, { method: 'GET', headers, signal: controller.signal });
+      const raw = await res.text();
+      return this.parseResponse(raw, res.status);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Parsea la respuesta de AEAT. La estructura exacta depende del servicio;
+   * este es un mapeo base que el consumidor puede sobrescribir.
+   */
+  protected parseResponse(raw: string, httpStatus: number): SendResult {
+    let operationId = '';
+    let status: 'OK' | 'ERROR' = httpStatus >= 200 && httpStatus < 300 ? 'OK' : 'ERROR';
+    let message: string | undefined;
+    let errorCode: string | undefined;
+
+    try {
+      const json = JSON.parse(raw) as Record<string, unknown>;
+      operationId = String(json.operationId ?? json.id ?? '');
+      if (json.status === 'OK' || json.status === 'ERROR') {
+        status = json.status;
+      }
+      message = json.message as string | undefined;
+      errorCode = json.errorCode as string | undefined;
+    } catch {
+      // Respuesta no JSON: se conserva el cuerpo como mensaje.
+      message = raw;
+    }
+
+    return { operationId, status, message, errorCode, rawResponse: raw };
+  }
+}

package/src/aeat/index.ts

@@ -0,0 +1 @@
+export * from './client.js';

package/src/core/hash/chain.ts

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Calcula el hash SHA-256 de un dato en hexadecimal MAYÚSCULA.
+ * Verifactu exige el hash en hexadecimal en mayúsculas (64 caracteres).
+ */
+export function sha256(data: string | Buffer): string {
+  return createHash('sha256').update(data).digest('hex').toUpperCase();
+}
+
+/**
+ * Concatena los campos de un registro en el formato Verifactu:
+ * `nombreCampo1=valor1&nombreCampo2=valor2&...`
+ *
+ * Reglas de normalización (AEAT):
+ * - Se eliminan los espacios al inicio y final de cada valor (trim).
+ * - Los campos vacíos o ausentes se incluyen como `nombreCampo=` (sin valor).
+ * - No se aplica URL-encoding ni escaping a caracteres especiales.
+ */
+export function concatenateFields(fields: Array<[string, string | null | undefined]>): string {
+  return fields
+    .map(([name, value]) => {
+      const trimmed = value ? value.trim() : '';
+      return `${name}=${trimmed}`;
+    })
+    .join('&');
+}
+
+/**
+ * Campos de un registro de alta (RegistroAlta) para el cálculo de la huella.
+ */
+export interface RegistroAltaInput {
+  /** Identificador del emisor (NIF). */
+  idEmisorFactura: string;
+  /** Número y serie de la factura. */
+  numSerieFactura: string;
+  /** Fecha de expedición de la factura. */
+  fechaExpedicionFactura: string;
+  /** Tipo de factura (F1, F2, ...). */
+  tipoFactura: string;
+  /** Cuota total. */
+  cuotaTotal: string;
+  /** Importe total. */
+  importeTotal: string;
+  /** Huella (hash) del registro anterior, o null para el primero. */
+  huellaAnterior: string | null;
+  /** Fecha/hora de generación con huso horario. */
+  fechaHoraHusoGenRegistro: string;
+}
+
+/**
+ * Campos de un registro de anulación (RegistroAnulacion).
+ */
+export interface RegistroAnulacionInput {
+  /** Identificador del emisor de la factura anulada. */
+  idEmisorFacturaAnulada: string;
+  /** Número y serie de la factura anulada. */
+  numSerieFacturaAnulada: string;
+  /** Fecha de expedición de la factura anulada. */
+  fechaExpedicionFacturaAnulada: string;
+  /** Huella (hash) del registro anterior. */
+  huellaAnterior: string | null;
+  /** Fecha/hora de generación con huso horario. */
+  fechaHoraHusoGenRegistro: string;
+}
+
+/**
+ * Construye la cadena canónica a hashear de un registro de alta.
+ */
+export function concatenateRegistroAlta(input: RegistroAltaInput): string {
+  return concatenateFields([
+    ['IDEmisorFactura', input.idEmisorFactura],
+    ['NumSerieFactura', input.numSerieFactura],
+    ['FechaExpedicionFactura', input.fechaExpedicionFactura],
+    ['TipoFactura', input.tipoFactura],
+    ['CuotaTotal', input.cuotaTotal],
+    ['ImporteTotal', input.importeTotal],
+    ['Huella', input.huellaAnterior],
+    ['FechaHoraHusoGenRegistro', input.fechaHoraHusoGenRegistro],
+  ]);
+}
+
+/**
+ * Construye la cadena canónica a hashear de un registro de anulación.
+ */
+export function concatenateRegistroAnulacion(input: RegistroAnulacionInput): string {
+  return concatenateFields([
+    ['IDEmisorFacturaAnulada', input.idEmisorFacturaAnulada],
+    ['NumSerieFacturaAnulada', input.numSerieFacturaAnulada],
+    ['FechaExpedicionFacturaAnulada', input.fechaExpedicionFacturaAnulada],
+    ['Huella', input.huellaAnterior],
+    ['FechaHoraHusoGenRegistro', input.fechaHoraHusoGenRegistro],
+  ]);
+}
+
+/**
+ * Calcula la huella (hash) de un registro de alta.
+ */
+export function computeRegistroAlta(input: RegistroAltaInput): string {
+  return sha256(concatenateRegistroAlta(input));
+}
+
+/**
+ * Calcula la huella (hash) de un registro de anulación.
+ */
+export function computeRegistroAnulacion(input: RegistroAnulacionInput): string {
+  return sha256(concatenateRegistroAnulacion(input));
+}
+
+/**
+ * Verifica que el hash de un registro de alta coincide con el esperado.
+ */
+export function verifyRegistroAlta(input: RegistroAltaInput, expectedHash: string): boolean {
+  return computeRegistroAlta(input).toLowerCase() === expectedHash.toLowerCase();
+}
+
+/**
+ * Verifica que el hash de un registro de anulación coincide con el esperado.
+ */
+export function verifyRegistroAnulacion(
+  input: RegistroAnulacionInput,
+  expectedHash: string,
+): boolean {
+  return computeRegistroAnulacion(input).toLowerCase() === expectedHash.toLowerCase();
+}
+
+/**
+ * Cadena de hash con estado, para encadenar registros de forma secuencial.
+ */
+export class HashChain {
+  private _lastHash: string | null = null;
+  private _count = 0;
+
+  /** Hash del último registro encadenado, o `null` si aún no hay ninguno. */
+  get lastHash(): string | null {
+    return this._lastHash;
+  }
+
+  /** Número de registros encadenados hasta ahora. */
+  get count(): number {
+    return this._count;
+  }
+
+  /**
+   * Encadena un nuevo registro de alta y devuelve su huella.
+   */
+  pushAlta(input: Omit<RegistroAltaInput, 'huellaAnterior'>): string {
+    const hash = computeRegistroAlta({ ...input, huellaAnterior: this._lastHash });
+    this._lastHash = hash;
+    this._count += 1;
+    return hash;
+  }
+
+  /**
+   * Encadena un nuevo registro de anulación y devuelve su huella.
+   */
+  pushAnulacion(input: Omit<RegistroAnulacionInput, 'huellaAnterior'>): string {
+    const hash = computeRegistroAnulacion({ ...input, huellaAnterior: this._lastHash });
+    this._lastHash = hash;
+    this._count += 1;
+    return hash;
+  }
+
+  /** Reinicia la cadena. */
+  reset(): void {
+    this._lastHash = null;
+    this._count = 0;
+  }
+}

package/src/core/hash/index.ts

@@ -0,0 +1 @@
+export * from './chain.js';

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from './models/index.js';
+export * from './hash/index.js';
+export * from './xml/index.js';
+export * from './qr/index.js';

package/src/core/models/event.ts

@@ -0,0 +1,25 @@
+/**
+ * Tipos de evento de registro Verifactu.
+ * - ALTA: alta de una factura.
+ * - ANULACION: anulación de una factura previamente registrada.
+ * - MODIFICACION: modificación de una factura.
+ */
+export type EventType = 'ALTA' | 'ANULACION' | 'MODIFICACION';
+
+/**
+ * Evento de registro Verifactu.
+ */
+export interface Event {
+  /** Tipo de evento. */
+  type: EventType;
+  /** Fecha/hora del evento en formato ISO 8601. */
+  fechaHora: string;
+  /** Referencia a la factura asociada. */
+  invoiceId: string;
+  /** Motivo de anulación (obligatorio si type === 'ANULACION'). */
+  motivoAnulacion?: string;
+  /** Referencia a la factura que se anula (para ANULACION). */
+  facturaAnulada?: string;
+  /** Metadatos adicionales. */
+  metadata?: Record<string, unknown>;
+}

package/src/core/models/index.ts

@@ -0,0 +1,2 @@
+export * from './invoice.js';
+export * from './event.js';

package/src/core/models/invoice.ts

@@ -0,0 +1,105 @@
+/**
+ * Datos identificativos del emisor de la factura.
+ * Verifactu exige identificar al emisor (NIF, nombre/razón social).
+ */
+export interface Emisor {
+  /** NIF del emisor. */
+  nif: string;
+  /** Nombre o razón social. */
+  nombreRazon: string;
+  /** Código de país (ISO 3166-1 alpha-2). Opcional si es España. */
+  pais?: string;
+  /** Código postal. */
+  codigoPostal?: string;
+  /** Municipio. */
+  municipio?: string;
+  /** Dirección. */
+  direccion?: string;
+}
+
+/**
+ * Identificación de la factura.
+ */
+export interface FacturaId {
+  /** Serie de la factura (opcional). */
+  serie?: string;
+  /** Número de la factura. */
+  numero: string;
+  /** Fecha de expedición en formato ISO (YYYY-MM-DD). */
+  fechaExpedicion: string;
+  /** Fecha de operación (opcional). */
+  fechaOperacion?: string;
+}
+
+/**
+ * Tipo de factura Verifactu (F1–F9).
+ */
+export type TipoFactura =
+  | 'F1' // factura completa
+  | 'F2' // factura simplificada
+  | 'F3' // factura rectificativa
+  | 'F4' // factura recapitulativa
+  | 'F5' // factura de importación
+  | 'F6' // operaciones de seguro
+  | 'F7' // operaciones de crédito
+  | 'F8' // arrendamiento de bienes inmuebles
+  | 'F9'; // transporte de viajeros
+
+/**
+ * Tipo de desglose Verifactu (S1–S6).
+ */
+export type TipoDesglose = 'S1' | 'S2' | 'S3' | 'S4' | 'S5' | 'S6';
+
+/**
+ * Detalle de IVA de una línea de desglose.
+ */
+export interface DetalleIva {
+  /** Tipo impositivo (%). */
+  tipoImpositivo: number;
+  /** Base imponible. */
+  baseImponible: number;
+  /** Cuota repercutida. */
+  cuotaRepercutida: number;
+}
+
+/**
+ * Desglose de la operación por tipo de operación e IVA.
+ */
+export interface DesgloseTipoOperacion {
+  /** Clave de tipo de operación (p. ej. '01'). */
+  tipoOperacion: string;
+  /** Detalles de IVA. */
+  detallesIva: DetalleIva[];
+}
+
+/**
+ * Desglose completo de la factura.
+ */
+export interface Desglose {
+  /** Desglose por tipo de operación. */
+  tipoOperaciones: DesgloseTipoOperacion[];
+  /** Cuota total de la factura. */
+  cuotaTotal: number;
+  /** Importe total de la factura. */
+  importeTotal: number;
+}
+
+/**
+ * Factura en el modelo de datos Verifactu.
+ */
+export interface Invoice {
+  /** Identificación de la factura. */
+  id: FacturaId;
+  /** Emisor de la factura. */
+  emisor: Emisor;
+  /** Desglose de la factura. */
+  desglose: Desglose;
+  /** Tipo de factura. */
+  tipoFactura: TipoFactura;
+  /** Tipo de desglose. */
+  tipoDesglose: TipoDesglose;
+  /** Descripción de la operación. */
+  descripcion?: string;
+  /** Metadatos adicionales libres. */
+  metadata?: Record<string, unknown>;
+}

package/src/core/qr/index.ts

@@ -0,0 +1 @@
+export * from './qr.js';

package/src/core/qr/qr.ts

@@ -0,0 +1,19 @@
+/**
+ * Construye el payload del QR Verifactu.
+ *
+ * El QR Verifactu codifica una URL de verificación que incluye el hash del
+ * registro, de modo que cualquier persona pueda verificar la integridad de
+ * la factura contra la AEAT.
+ *
+ * @param hash        Hash del registro (encadenado).
+ * @param baseUrl     URL base de verificación de la AEAT.
+ * @param extraParams Parámetros adicionales a incluir en la URL.
+ */
+export function buildQrPayload(
+  hash: string,
+  baseUrl = 'https://www2.agenciatributaria.gob.es/verifactu/verificar',
+  extraParams: Record<string, string> = {},
+): string {
+  const params = new URLSearchParams({ hash, ...extraParams });
+  return `${baseUrl}?${params.toString()}`;
+}

package/src/core/xml/generator.ts

@@ -0,0 +1,133 @@
+import type { Invoice } from '../models/invoice.js';
+
+/**
+ * Datos de la factura que se anula.
+ */
+export interface AnulacionInput {
+  /** NIF del emisor de la factura anulada. */
+  idEmisorFacturaAnulada: string;
+  /** Número y serie de la factura anulada. */
+  numSerieFacturaAnulada: string;
+  /** Fecha de expedición de la factura anulada. */
+  fechaExpedicionFacturaAnulada: string;
+  /** Huella (hash) de la factura anulada. */
+  huellaFacturaAnulada: string;
+}
+
+/**
+ * Escapa caracteres especiales para XML.
+ */
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Formatea un número con 2 decimales (formato Verifactu).
+ */
+function formatAmount(value: number): string {
+  return value.toFixed(2);
+}
+
+/**
+ * Genera el XML Verifactu de una factura (registro de alta).
+ *
+ * Estructura basada en el RD 1007/2023 y la documentación técnica de la
+ * AEAT. NOTA: el esquema XSD oficial debe validarse antes de producción;
+ * este esqueleto refleja los bloques principales (IDFactura, IDEmisorFactura,
+ * TipoFactura, TipoDesglose, Desglose, CuotaTotal, Encadenamiento, Huella).
+ */
+export function generateInvoiceXml(invoice: Invoice, previousHash: string | null): string {
+  const { id, emisor, desglose, tipoFactura, tipoDesglose } = invoice;
+
+  const detalles = desglose.tipoOperaciones
+    .map((op) => {
+      const iva = op.detallesIva
+        .map(
+          (d) =>
+            `      <DetalleIVA>` +
+            `<TipoImpositivo>${formatAmount(d.tipoImpositivo)}</TipoImpositivo>` +
+            `<BaseImponible>${formatAmount(d.baseImponible)}</BaseImponible>` +
+            `<CuotaRepercutida>${formatAmount(d.cuotaRepercutida)}</CuotaRepercutida>` +
+            `</DetalleIVA>`,
+        )
+        .join('\n');
+      return (
+        `    <DesgloseTipoOperacion>` +
+        `<TipoOperacion>${escapeXml(op.tipoOperacion)}</TipoOperacion>` +
+        `\n      <DesgloseIVA>\n${iva}\n      </DesgloseIVA>` +
+        `\n    </DesgloseTipoOperacion>`
+      );
+    })
+    .join('\n');
+
+  const xml = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<RegistroFactura>',
+    '  <IDFactura>',
+    '    <IDEmisorFactura>',
+    `      <NIF>${escapeXml(emisor.nif)}</NIF>`,
+    `      <NombreRazon>${escapeXml(emisor.nombreRazon)}</NombreRazon>`,
+    emisor.pais ? `      <Pais>${escapeXml(emisor.pais)}</Pais>` : '',
+    emisor.codigoPostal ? `      <CodigoPostal>${escapeXml(emisor.codigoPostal)}</CodigoPostal>` : '',
+    emisor.municipio ? `      <Municipio>${escapeXml(emisor.municipio)}</Municipio>` : '',
+    emisor.direccion ? `      <Direccion>${escapeXml(emisor.direccion)}</Direccion>` : '',
+    '    </IDEmisorFactura>',
+    id.serie ? `    <SerieFactura>${escapeXml(id.serie)}</SerieFactura>` : '',
+    `    <NumeroFactura>${escapeXml(id.numero)}</NumeroFactura>`,
+    `    <FechaExpedicionFactura>${id.fechaExpedicion}</FechaExpedicionFactura>`,
+    id.fechaOperacion ? `    <FechaOperacion>${id.fechaOperacion}</FechaOperacion>` : '',
+    '  </IDFactura>',
+    `  <TipoFactura>${tipoFactura}</TipoFactura>`,
+    `  <TipoDesglose>${tipoDesglose}</TipoDesglose>`,
+    '  <Desglose>',
+    detalles,
+    '  </Desglose>',
+    `  <CuotaTotal>${formatAmount(desglose.cuotaTotal)}</CuotaTotal>`,
+    '  <Encadenamiento>',
+    `    <HashAnterior>${previousHash ?? ''}</HashAnterior>`,
+    '  </Encadenamiento>',
+    '</RegistroFactura>',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+
+  return xml;
+}
+
+/**
+ * Genera el XML Verifactu de un registro de anulación.
+ *
+ * Referencia la factura anulada (IDFactura + Huella) y encadena con el hash
+ * anterior. Estructura basada en el RD 1007/2023; validar contra el XSD
+ * oficial antes de producción.
+ */
+export function generateAnulacionXml(
+  anulacion: AnulacionInput,
+  previousHash: string | null,
+): string {
+  const xml = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<RegistroFactura>',
+    '  <RegistroAnulacion>',
+    '    <IDFactura>',
+    '      <IDEmisorFactura>',
+    `        <NIF>${escapeXml(anulacion.idEmisorFacturaAnulada)}</NIF>`,
+    '      </IDEmisorFactura>',
+    `      <NumeroFactura>${escapeXml(anulacion.numSerieFacturaAnulada)}</NumeroFactura>`,
+    `      <FechaExpedicionFactura>${anulacion.fechaExpedicionFacturaAnulada}</FechaExpedicionFactura>`,
+    '    </IDFactura>',
+    `    <Huella>${anulacion.huellaFacturaAnulada}</Huella>`,
+    '  </RegistroAnulacion>',
+    '  <Encadenamiento>',
+    `    <HashAnterior>${previousHash ?? ''}</HashAnterior>`,
+    '  </Encadenamiento>',
+    '</RegistroFactura>',
+  ].join('\n');
+
+  return xml;
+}

package/src/core/xml/index.ts

@@ -0,0 +1 @@
+export * from './generator.js';

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './core/index.js';
+export * from './aeat/index.js';
+export * from './integration/index.js';

package/src/integration/index.ts

@@ -0,0 +1,2 @@
+export * from './repository.js';
+export * from './service.js';