@dwast/verifactu-lib 0.1.0-beta.1 → 0.1.0-beta.3

package/readme.md

@@ -1,89 +1,782 @@
 # @dwast/verifactu-lib
 
-Librería privada (npm) para la gestión de **Verifactu** (Ley 18/2022 y RD 1007/2023) en un stack MERN (JS/TS).
+Librería npm privada para la gestión de **Verifactu** (Ley 18/2022 y RD 1007/2023) en un stack MERN (JS/TS). Genera facturas en formato Verifactu, calcula el encadenado hash (huella), genera el QR, se comunica con AEAT (SOAP + mTLS) y define la capa de integración que el sistema consumidor debe implementar.
+
+> **Verifactu es obligatorio desde el 1 de julio de 2025** para todos los sistemas de facturación en España.
 
 ## ¿Qué resuelve?
 
-Verifactu no es solo "endpoints": el núcleo es la generación de facturas en formato XML con los campos obligatorios, el **encadenado hash** (SHA-256) que garantiza integridad e inmutabilidad, el **QR Verifactu** y el registro de eventos. La comunicación con AEAT es solo una parte.
+Verifactu no es solo "endpoints": el núcleo es la generación de facturas en XML con los campos obligatorios, el **encadenado hash** (SHA-256) que garantiza integridad e inmutabilidad, el **QR Verifactu** y el registro de eventos. La comunicación con AEAT es solo una parte.
 
 La librería se divide en tres capas:
 
 - **`core`** — Núcleo puro, sin dependencias de red ni de framework. Fácil de testear y de usar en cualquier parte del stack.
-- **`aeat`** — Cliente para los servicios de AEAT (depende de credenciales y entornos).
-- **`integration`** — Capa de orquestación que define los **requisitos del sistema consumidor** (persistencia de registros y respuestas en tablas) y une núcleo + AEAT.
+- **`aeat`** — Cliente para los servicios de AEAT (SOAP, soporta mTLS con certificado digital).
+- **`integration`** — Capa de orquestación: persistencia, servicio de facturación, lectura de `.p12` y accountability (contabilidad).
+
+## Instalación
+
+```bash
+npm install @dwast/verifactu-lib
+```
 
 ## Estructura
 
 ```
 src/
 ├── core/
-│   ├── models/     # Tipos: Invoice, Emisor, Desglose, Event, etc.
-│   ├── hash/       # Encadenado hash (SHA-256)
-│   ├── xml/        # Generación XML Verifactu (RegistroFactura)
-│   └── qr/         # Generación QR Verifactu
-├── aeat/           # Cliente de servicios AEAT
-├── integration/    # Repositorio, servicio de orquestación y schema.sql
+│   ├── models/        # Tipos: Invoice, Emisor, Desglose, SistemaInformatico
+│   ├── hash/          # Encadenado hash (SHA-256)
+│   ├── xml/           # Generación XML Verifactu (RegistroAlta, Anulacion, Evento, Suministro)
+│   ├── qr/            # Generación QR Verifactu
+│   ├── validation/    # Validación de facturas
+│   └── utils/         # Utilidades (fecha/hora con huso)
+├── aeat/              # Cliente de servicios AEAT (SOAP + mTLS)
+├── integration/       # Repositorio, servicio, p12, accountability
 └── index.ts
 ```
 
-## Requisitos del sistema consumidor
+**Subpaths de importación** (definidos en `package.json`):
+
+| Subpath | Contenido |
+|---------|-----------|
+| `@dwast/verifactu-lib` | Todo (re-exporta core + aeat + integration) |
+| `@dwast/verifactu-lib/core` | Núcleo puro (modelos, hash, xml, qr, utils) |
+| `@dwast/verifactu-lib/aeat` | Cliente AEAT + parser de respuesta |
+| `@dwast/verifactu-lib/integration` | Repositorio, servicio, p12, accountability |
+
+---
+
+## Cómo usar
 
-La capa `integration` define qué debe aportar el sistema que use la librería:
+Guía práctica paso a paso. La receta recomendada es **`VerifactuService`** (se encarga de validar, generar el hash, el XML, encadenar con la huella anterior, enviar y persistir). Para casos "de bajo nivel" usa el `VerifactuClient` directamente.
 
-1. **Persistencia de registros y respuestas.** El sistema DEBE implementar la interfaz `VerifactuRepository` (ver `src/integration/repository.ts`) y disponer de las tablas de `src/integration/schema.sql` (`verifactu_records`, `verifactu_responses`, `verifactu_events`). La AEAT exige conservar la respuesta de cada envío para acreditar la remisión.
-2. **Cliente AEAT configurado.** El sistema DEBE proporcionar un `VerifactuClient` con las credenciales y el entorno adecuados.
+### 0. Configuración inicial (certificado `.p12` → cliente)
 
-### Ejemplo de uso
+Extrae `cert` + `key` del `.p12` y construye el cliente (aquí en entorno de **pruebas**; en producción usa `baseUrl` y no pases `env`).
 
 ```ts
+import { readFileSync } from 'node:fs';
+import { readP12 } from '@dwast/verifactu-lib/integration';
+import { VerifactuClient, AEAT_TEST_SOAP_URL } from '@dwast/verifactu-lib/aeat';
 import { VerifactuService } from '@dwast/verifactu-lib/integration';
-import { VerifactuClient } from '@dwast/verifactu-lib/aeat';
-import { MyMongoRepository } from './my-repo'; // implementa VerifactuRepository
+import type { VerifactuRepository } from '@dwast/verifactu-lib/integration';
+
+// 1. Leer el .p12 y extraer certificado + clave (PEM).
+const { certificates, keys } = readP12(
+  readFileSync('mi-certificado.p12'),
+  'contraseña-del-p12',
+);
+
+// 2. Cliente AEAT con mTLS. env:'test' → usa testBaseUrl (pruebas).
+const client = new VerifactuClient({
+  testBaseUrl: AEAT_TEST_SOAP_URL, // https://prewww1.aeat.es/.../VerifactuSOAP
+  env: 'test',
+  cert: certificates[0],
+  key: keys[0],
+  timeoutMs: 15_000,
+});
+
+// 3. Servicio de orquestación (repositorio implementado por tu app + cliente).
+//    El 3er arg (cert PEM) sirve para detectar representante en la cabecera.
+const repo: VerifactuRepository = /* tu implementación (Mongoose, Prisma...) */;
+const service = new VerifactuService(repo, client, certificates[0]);
+```
+
+> **Producción:** omite `env` y `testBaseUrl`, usa `baseUrl`:
+> `new VerifactuClient({ baseUrl: AEAT_PRODUCTION_SOAP_URL, cert, key })`.
 
-const repo = new MyMongoRepository();
-const client = new VerifactuClient({ baseUrl: 'https://...', authToken: '...' });
-const service = new VerifactuService(repo, client);
+### 1. Enviar 1 factura (alta)
 
-await service.registerInvoice({
-  id: { serie: 'A', numero: '2025-001', fechaExpedicion: '2025-07-01' },
-  emisor: { nif: 'B12345678', nombreRazon: 'Empresa S.L.' },
+```ts
+import type { Invoice } from '@dwast/verifactu-lib/core';
+
+const invoice: Invoice = {
+  id: { serie: 'A', numero: '2026-0001', fechaExpedicion: '07-09-2026' }, // DD-MM-YYYY
+  emisor: { nif: 'B18579458', nombreRazon: 'MOVVIENDO TOURISM GROUP SL' },
   tipoFactura: 'F1',
   tipoDesglose: 'S1',
+  descripcion: 'Servicios de consultoria',
+  destinatarios: [{ nombreRazon: 'CLIENTE SL', nif: 'B12345678' }],
   desglose: {
-    tipoOperaciones: [
-      { tipoOperacion: '01', detallesIva: [{ tipoImpositivo: 21, baseImponible: 100, cuotaRepercutida: 21 }] },
+    detalles: [
+      { calificacionOperacion: 'S1', claveRegimen: '01', tipoImpositivo: 21, baseImponible: 100, cuotaRepercutida: 21 },
     ],
     cuotaTotal: 21,
     importeTotal: 121,
   },
+  sistemaInformatico: {
+    nombreRazon: 'MOVVIENDO TOURISM GROUP SL',
+    nif: 'B18579458',
+    nombreSistemaInformatico: 'SIF-PROD',
+    idSistemaInformatico: '01',   // máx 2 caracteres
+    version: '1.0',
+    numeroInstalacion: '1',
+  },
+  fechaHoraHusoGenRegistro: new Date().toISOString().replace(/\.\d+Z/, 'Z'), // o nowIsoWithOffset()
+  huella: '',  // la calcula el servicio
+};
+
+const record = await service.registerInvoice(invoice);
+
+console.log(record.status);        // 'CONFIRMED' | 'REJECTED'
+console.log(record.hash);          // huella SHA-256 (64 hex)
+console.log(record.hashVerified);  // true/false (si AEAT devolvió huella que coincide)
+console.log(record.qrPayload);     // URL del QR
+console.log(record.xml);           // XML Verifactu que se envió (persistir)
+```
+
+> La **fecha/hora** debe ser la actual (margen AEAT de 240s). Usa `nowIsoWithOffset()` de `@dwast/verifactu-lib/core` en vez de `toISOString()`.
+
+### 2. Enviar varias facturas encadenadas
+
+`VerifactuService` **encadena automáticamente** la huella: cada alta usa como `huellaAnterior` el hash del último registro guardado en `getLastRecord()`. Solo encadena **dentro del mismo obligado + sistema informático**.
+
+```ts
+const f1 = await service.registerInvoice(invoice1);   // PrimerRegistro
+const f2 = await service.registerInvoice(invoice2);   // usa f1.hash como huellaAnterior
+const f3 = await service.registerInvoice(invoice3);   // usa f2.hash
+console.log(f2.previousHash === f1.hash);             // true
+```
+
+> **Importante:** el sistema informático (`numeroInstalacion`/`idSistemaInformatico`) debe ser **el mismo** en toda la cadena. Para empezar una cadena nueva por cada sistema, usa un `numeroInstalacion` único.
+
+### 3. Anular una factura
+
+```ts
+await service.annulInvoice(invoiceId, invoice);
+// - Genera el registro de anulación (encadena con el último hash).
+// - Envía a AEAT.
+// - Marca la factura original como 'ANNULLED'.
+```
+
+`invoiceId` es la **referencia de la original** (serie + número, p. ej. `A2026-0001`), que debe existir en el repositorio. Pasa la `invoice` completa si quieres que use su `sistemaInformatico` y sus fechas; si no, usa los valores por defecto de la librería.
+
+### 4. Modificar una factura
+
+Verifactu **no tiene "modificación"**: se hace como anulación + nuevo alta. `modifyInvoice` lo hace por ti.
+
+```ts
+const original: Invoice = /* la factura ya enviada */;
+await service.registerInvoice(original);
+
+const corregida: Invoice = { ...original, id: { ...original.id, numero: '2026-0002' }, /* cambios */ };
+await service.modifyInvoice(`${original.id.serie ?? ''}${original.id.numero}`, corregida);
+// Anula la original y emite la corregida como nuevo alta (CONFIRMED si AEAT la acepta).
+```
+
+### 5. Consultar la huella de un registro enviado
+
+En lugar de guardar la huella, puedes pedirla a AEAT. Necesitas el **número de factura** y el **mes** real.
+
+```ts
+const res = await client.queryInvoice({
+  obligado: { nombreRazon: 'MOVVIENDO TOURISM GROUP SL', nif: 'B18579458' },
+  numSerieFactura: 'A2026-0001',
+  ejercicio: '2026',
+  periodo: '09',          // 01–12, el mes real de la factura
+});
+
+const huella = res.consulta?.huella;        // hash confirmado por AEAT
+const pagSiguiente = res.consulta?.clavePaginacion; // pasar como clavePaginacion en la siguiente consulta
+```
+
+> **Recomendación:** para encadenar la siguiente factura es más fiable **guardar la huella localmente** (`getLastRecord()`). `queryInvoice` es útil para auditoría o recuperación puntual. Consultar "por periodo" sin número devuelve registros de todos los sistemas y ejecuciones (poco fiable).
+
+### 6. Enviar un evento (`RegistroEvento`)
+
+```ts
+import { computeRegistroEvento } from '@dwast/verifactu-lib/core';
+
+const last = await repo.getLastRecord();                 // último registro (para encadenar)
+const fechaHora = nowIsoWithOffset();
+const hash = computeRegistroEvento({
+  nifSistemaInformatico: 'B18579458',
+  id: '',                          // IDOtro del software (vacío si usa NIF)
+  idSistemaInformatico: '01',
+  version: '1.0',
+  numeroInstalacion: '1',
+  nifObligado: 'B18579458',
+  tipoEvento: '01',                // 01–10, 90 (ver EventosSIF.xsd)
+  huellaAnterior: last?.hash ?? null,
+  fechaHoraHusoGenEvento: fechaHora,
+});
+
+await service.registerEvent({
+  sistemaInformatico: { /* igual que en la factura */ },
+  obligadoEmision: { nombreRazon: 'MOVVIENDO TOURISM GROUP SL', nif: 'B18579458' },
+  fechaHoraHusoGenEvento: fechaHora,
+  tipoEvento: '01',
+  huellaEvento: hash,
+  // eventoAnterior: { tipoEvento, fechaHoraHusoGenEvento, huellaEvento } // para el 2º evento en adelante
+});
+```
+
+> **⚠️ Envío de eventos.** La generación del XML (`generateEventoXml`) es correcta y está cubierta por unit tests, pero **el envío real necesita un endpoint/operación SOAP específica de eventos** que el cliente actual (`VerifactuSOAP`) todavía no cubre (AEAT devuelve error 4118). Úsalo cuando se añada ese endpoint.
+
+---
+
+## Núcleo (`core`)
+
+### Modelos (`core/models`)
+
+```ts
+import type { Invoice } from '@dwast/verifactu-lib/core';
+
+const invoice: Invoice = {
+  id: { serie: 'A', numero: '2025-001', fechaExpedicion: '07-09-2026' },
+  emisor: { nif: 'B18579458', nombreRazon: 'MOVVIENDO TOURISM GROUP SL' },
+  tipoFactura: 'F1',        // F1–F9
+  tipoDesglose: 'S1',       // S1–S6
+  descripcion: 'Servicios de consultoria',
+  destinatarios: [{ nombreRazon: 'CLIENTE SL', nif: 'B12345678' }],
+  desglose: {
+    detalles: [
+      {
+        calificacionOperacion: 'S1',   // S1/S2/N1/N2...
+        claveRegimen: '01',            // obligatorio si Impuesto es IVA/IPSI/IGIC
+        tipoImpositivo: 21,
+        baseImponible: 100,
+        cuotaRepercutida: 21,
+      },
+    ],
+    cuotaTotal: 21,
+    importeTotal: 121,
+  },
+  sistemaInformatico: {
+    nombreRazon: 'MOVVIENDO TOURISM GROUP SL',
+    nif: 'B18579458',
+    nombreSistemaInformatico: 'SIF-TEST',
+    idSistemaInformatico: '01',   // TextMax2Type: máx 2 caracteres
+    version: '1.0',
+    numeroInstalacion: '1',
+  },
+  fechaHoraHusoGenRegistro: '2026-09-07T10:00:00+02:00',
+  huella: 'ABC123',   // se rellena con computeRegistroAlta
+};
+```
+
+> **⚠️ Fechas.** El XSD `fecha` de AEAT usa el formato **`DD-MM-YYYY`** (no ISO). `FechaExpedicionFactura` y `FechaExpedicionFacturaAnulada` van en `DD-MM-YYYY`. En cambio `FechaHoraHusoGenRegistro` es `dateTime` (ISO 8601 con huso).
+
+> **⚠️ Importes.** AEAT **sí pide los importes**: el XML incluye el bloque `Desglose` con `BaseImponibleOimporteNoSujeto`, `CuotaRepercutida`, `CuotaTotal` e `ImporteTotal`. Además, la **huella (hash)** se calcula sobre `CuotaTotal` e `ImporteTotal` (los totales), no sobre el desglose línea a línea. Ver [Hash](#hash-corehash).
+
+### Hash (`core/hash`)
+
+La huella **no se calcula sobre el XML**, sino sobre una cadena canónica de campos concatenados (`nombreCampo=valor&...`). Resultado: **SHA-256 en hexadecimal MAYÚSCULA** (64 caracteres). Verificado contra los [vectores oficiales de la AEAT](https://www.agenciatributaria.es/static_files/AEAT_Desarrolladores/EEDD/IVA/VERI-FACTU/Veri-Factu_especificaciones_huella_hash_registros.pdf).
+
+**Campos por tipo de registro:**
+
+| Registro | Campos (en orden) |
+|----------|-------------------|
+| **Alta (8)** | `IDEmisorFactura`, `NumSerieFactura`, `FechaExpedicionFactura`, `TipoFactura`, `CuotaTotal`, `ImporteTotal`, `Huella`, `FechaHoraHusoGenRegistro` |
+| **Anulación (5)** | `IDEmisorFacturaAnulada`, `NumSerieFacturaAnulada`, `FechaExpedicionFacturaAnulada`, `Huella`, `FechaHoraHusoGenRegistro` |
+| **Evento (9)** | `NIF`, `ID`, `IdSistemaInformatico`, `Version`, `NumeroInstalacion`, `NIF`, `TipoEvento`, `HuellaEvento`, `FechaHoraHusoGenEvento` (el `NIF` aparece dos veces: sistema informático y obligado a emitir) |
+
+```ts
+import {
+  computeRegistroAlta,
+  computeRegistroAnulacion,
+  computeRegistroEvento,
+  verifyRegistroAlta,
+  concatenateRegistroAlta,
+  HashChain,
+} from '@dwast/verifactu-lib/core';
+
+// Huella de un registro de alta
+const hash = computeRegistroAlta({
+  idEmisorFactura: 'B18579458',
+  numSerieFactura: 'A2025-001',
+  fechaExpedicionFactura: '07-09-2026',   // DD-MM-YYYY
+  tipoFactura: 'F1',
+  cuotaTotal: '21.00',
+  importeTotal: '121.00',
+  huellaAnterior: null,          // hash del registro anterior (o null si es el primero)
+  fechaHoraHusoGenRegistro: '2026-09-07T10:00:00+02:00',
+});
+
+// Verificar que un hash coincide
+const ok = verifyRegistroAlta({ ... }, hash);
+
+// Cadena con estado (encadena automáticamente)
+const chain = new HashChain();
+const h1 = chain.pushAlta({ /* ... */ });
+const h2 = chain.pushAlta({ /* ... */ });  // encadena con h1
+```
+
+**Funciones exportadas:**
+
+| Función | Descripción |
+|---------|-------------|
+| `sha256(data)` | SHA-256 en hex MAYÚSCULA |
+| `concatenateFields(fields)` | Concatena `nombreCampo=valor&...` (trim, vacíos como `campo=`) |
+| `concatenateRegistroAlta(input)` | Cadena canónica de un alta |
+| `concatenateRegistroAnulacion(input)` | Cadena canónica de una anulación |
+| `concatenateRegistroEvento(input)` | Cadena canónica de un evento |
+| `computeRegistroAlta(input)` | Huella de un alta |
+| `computeRegistroAnulacion(input)` | Huella de una anulación |
+| `computeRegistroEvento(input)` | Huella de un evento |
+| `verifyRegistroAlta(input, hash)` | Comprueba la huella de un alta |
+| `verifyRegistroAnulacion(input, hash)` | Comprueba la huella de una anulación |
+| `verifyRegistroEvento(input, hash)` | Comprueba la huella de un evento |
+| `HashChain` | Cadena con estado (`pushAlta`, `pushAnulacion`, `pushEvento`, `reset`) |
+
+### XML (`core/xml`)
+
+```ts
+import {
+  generateInvoiceXml,        // alias de generateRegistroAltaXml
+  generateRegistroAltaXml,
+  generateAnulacionXml,
+  generateEventoXml,
+  generateSuministroXml,
+  buildCabecera,
+  buildRemisionEnvelope,
+} from '@dwast/verifactu-lib/core';
+
+// 1. XML del registro de alta (RegistroAlta)
+const registroAltaXml = generateInvoiceXml(invoice, previousHash);
+
+// 2. Cabecera (ObligadoEmision + Representante si el certificado es de representante)
+const cabecera = buildCabecera(
+  { nombreRazon: invoice.emisor.nombreRazon, nif: invoice.emisor.nif },
+  certificatePem,          // opcional
+  extractCertificateInfo,   // opcional, para detectar representante
+);
+
+// 3. Envolver en el suministro (RegFactuSistemaFacturacion)
+const xml = generateSuministroXml(registroAltaXml, cabecera);
+
+// 4. Sobre SOAP para el envío a AEAT
+const envelope = buildRemisionEnvelope(xml);
+```
+
+**Funciones exportadas:**
+
+| Función | Descripción |
+|---------|-------------|
+| `generateRegistroAltaXml(invoice, previousHash)` | XML `<sf:RegistroAlta>` de un alta |
+| `generateInvoiceXml(invoice, previousHash)` | Alias de `generateRegistroAltaXml` |
+| `generateAnulacionXml(anulacion, previousHash)` | XML `<sf:RegistroAnulacion>` |
+| `generateEventoXml(evento)` | XML `<sf:RegistroEvento>` (estructura `EventosSIF.xsd`) |
+| `generateSuministroXml(registroXml, cabecera)` | Envuelve en `<sfLR:RegFactuSistemaFacturacion>` con `Cabecera` |
+| `buildCabecera(obligado, certPem?, extractInfo?)` | Construye la cabecera; añade `Representante` si el NIF del cert difiere del obligado |
+| `buildRemisionEnvelope(operationXml)` | Sobre SOAP Envelope/Body |
+
+**Namespaces (críticos):**
+
+| Prefijo | Namespace |
+|---------|-----------|
+| `sfLR` | `.../tike/cont/ws/SuministroLR.xsd` — `RegFactuSistemaFacturacion`, `Cabecera`, `RegistroFactura` |
+| `sf` | `.../tike/cont/ws/SuministroInformacion.xsd` — `ObligadoEmision`, `Representante`, `RegistroAlta` y todos sus hijos |
+| `sf` (eventos) | `.../tike/cont/ws/EventosSIF.xsd` — `RegistroEvento` (suministro independiente, no va dentro de `RegFactuSistemaFacturacion`) |
+
+**Eventos (`RegistroEvento`):** se envían como un suministro independiente (no dentro de `RegFactuSistemaFacturacion`). Estructura: `IDVersion` + `Evento` (`SistemaInformatico`, `ObligadoEmision`, `FechaHoraHusoGenEvento`, `TipoEvento`, `Encadenamiento`, `TipoHuella`, `HuellaEvento`). El hash del evento usa `NIF`, `ID` (= `IDOtro` del software, vacío si usa NIF), `IdSistemaInformatico`, `Version`, `NumeroInstalacion`, `NIF` (obligado), `TipoEvento`, `HuellaEvento` (anterior), `FechaHoraHusoGenEvento`.
+
+### QR (`core/qr`)
+
+```ts
+import { buildQrPayload } from '@dwast/verifactu-lib/core';
+
+const qr = buildQrPayload(hash);  // URL de verificación con el hash
+```
+
+### Fecha/hora (`core/utils`)
+
+```ts
+import { nowIsoWithOffset } from '@dwast/verifactu-lib/core';
+
+// Fecha/hora actual con el huso detectado automáticamente (no asume +02:00)
+const ts = nowIsoWithOffset();  // → 2026-09-07T10:29:05+02:00
+```
+
+AEAT exige que `FechaHoraHusoGenRegistro` sea la **fecha/hora actual** del sistema (margen de 240 segundos). Usa este helper en vez de hardcodear un huso.
+
+### Validación (`core/validation`)
+
+```ts
+import { validateInvoice } from '@dwast/verifactu-lib/core';
+
+const { valid, errors } = validateInvoice(invoice);
+if (!valid) {
+  console.error(errors);  // lista de campos obligatorios o con formato incorrecto
+}
+```
+
+Comprueba campos obligatorios, el formato `DD-MM-YYYY` de las fechas, `destinatarios` para F1/F3, y `claveRegimen` cuando hay `tipoImpositivo`. `VerifactuService.registerInvoice` la llama automáticamente y lanza un error si la factura es inválida.
+
+---
+
+## Cliente AEAT (`aeat`)
+
+Soporta autenticación por **certificado digital (mTLS)** o por token, y **dos entornos** (producción y pruebas). Por defecto se usa **producción**; los tests fijan `env: 'test'` para usar desarrollo.
+
+```ts
+import { VerifactuClient, AEAT_TEST_SOAP_URL } from '@dwast/verifactu-lib/aeat';
+
+const client = new VerifactuClient({
+  testBaseUrl: AEAT_TEST_SOAP_URL,   // https://prewww1.aeat.es/.../VerifactuSOAP
+  env: 'test',                       // 'production' | 'test' | 'development'
+  cert,                              // PEM (mTLS)
+  key,                               // PEM (mTLS)
+  timeoutMs: 15_000,
+});
+```
+
+**Config (`VerifactuClientConfig`):**
+
+| Campo | Descripción |
+|-------|-------------|
+| `baseUrl` | URL del endpoint SOAP en producción |
+| `testBaseUrl` | URL del endpoint SOAP en pruebas |
+| `env` | `production` (default) \| `test` \| `development` |
+| `authToken` | Token OAuth alternativo al certificado |
+| `cert` / `key` | Certificado y clave PEM (mTLS) |
+| `operation` | Operación SOAP (default `RegFactuSistemaFacturacion`) |
+| `namespace` | Namespace del servicio |
+| `timeoutMs` | Timeout de petición (default 10s) |
+
+**Regla de entorno:** por defecto se usa **producción**. Si `env` es `production` (o no se indica), usa `baseUrl`. Si `env` es `test`/`development`, usa `testBaseUrl` (o lanza error si no hay). Los tests fijan `env: 'test'` para usar desarrollo.
+
+### Métodos
+
+| Método | Descripción |
+|--------|-------------|
+| `sendRecord(xml)` | Envía un registro (alta/anulación/evento) a AEAT |
+| `queryInvoice({ obligado, numSerieFactura, ejercicio, periodo, clavePaginacion? })` | Consulta un registro por número de factura y devuelve su huella; acepta `clavePaginacion` para cursar las páginas siguientes |
+
+### `queryInvoice` — obtener la huella de un registro enviado
+
+En vez de guardar la huella localmente, puedes consultar AEAT y obtener la huella confirmada de un registro enviado:
+
+```ts
+const res = await client.queryInvoice({
+  obligado: { nombreRazon: 'MOVVIENDO TOURISM GROUP SL', nif: 'B18579458' },
+  numSerieFactura: 'A2026-...',
+  ejercicio: '2026',
+  periodo: '09',   // 01–12 (meses); no existe '13'
 });
+
+const huella = res.consulta?.huella;  // hash confirmado por AEAT
+```
+
+> **Nota:** `periodo` solo admite `01`–`12` (meses). Usa el mes real de la factura.
+
+> **⚠️ ¿Guardar la huella o pedirla a AEAT?** La cadena de huellas es **por obligado + sistema informático**. Para encadenar la siguiente factura necesitas la huella del último registro. **Lo recomendable es guardarla localmente** (en la BD, vía `VerifactuRepository.getLastRecord()`). Puedes recuperarla de AEAT con `queryInvoice`, pero necesitas saber el **número de factura** del último registro (que igualmente tendrías que guardar). Consultar "por periodo" sin número es poco fiable, porque devuelve registros de todos los sistemas y ejecuciones.
+
+### Formato de respuesta (`SendResult`)
+
+`sendRecord` y `queryInvoice` devuelven **todo lo recibido de AEAT**, sea OK o error:
+
+```ts
+interface SendResult {
+  operationId: string;                 // ID de la operación devuelto por AEAT
+  status: 'OK' | 'ERROR';              // estado HTTP/registro
+  message?: string;                    // mensaje de AEAT
+  errorCode?: string;                  // código de error de AEAT
+  rawResponse?: string;                // cuerpo crudo (para auditoría)
+  data?: Record<string, unknown>;      // body completo parseado
+  response?: SoapResponse;             // respuesta SOAP normalizada a JSON
+  registro?: RegistroResponse;        // si la operación es de registro
+  consulta?: ConsultaResponse;         // si la operación es de consulta
+  evento?: EventoResponse;             // si la operación es de evento
+}
 ```
 
+**Interfaces tipadas:**
+
+```ts
+interface RegistroResponse {
+  estadoRegistro?: string;
+  codigoErrorRegistro?: string;
+  descripcionErrorRegistro?: string;
+  csv?: string;                        // Código Seguro de Verificación
+  huella?: string;                     // hash confirmado por AEAT
+  fechaHoraHusoGenRegistro?: string;
+  idFactura?: string;
+}
+
+interface ConsultaResponse {
+  estado?: string;
+  codigoError?: string;
+  descripcionError?: string;
+  csv?: string;
+  huella?: string;                     // hash del primer registro devuelto
+  clavePaginacion?: string;            // cursor para la página siguiente
+  registros?: RegistroResponse[];
+}
+
+interface EventoResponse {
+  estadoEvento?: string;
+  codigoErrorEvento?: string;
+  descripcionErrorEvento?: string;
+  csv?: string;
+  huella?: string;
+}
+```
+
+**Ejemplo de respuesta OK (registro):**
+
+```json
+{
+  "operationId": "",
+  "status": "OK",
+  "response": {
+    "operation": "RespuestaRegFactuSistemaFacturacion",
+    "body": {
+      "CSV": "A-UAGWU4Y3GE47KR",
+      "EstadoEnvio": "Correcto",
+      "RespuestaLinea": {
+        "EstadoRegistro": "Correcto",
+        "IDFactura": { "NumSerieFactura": "A2026-..." }
+      }
+    },
+    "registro": { "estadoRegistro": "Correcto", "csv": "A-UAGWU4Y3GE47KR" }
+  }
+}
+```
+
+**Ejemplo de respuesta ERROR (validación de AEAT):**
+
+```json
+{
+  "status": "OK",
+  "response": {
+    "operation": "RespuestaRegFactuSistemaFacturacion",
+    "body": {
+      "EstadoEnvio": "Incorrecto",
+      "RespuestaLinea": {
+        "EstadoRegistro": "Incorrecto",
+        "CodigoErrorRegistro": "1189",
+        "DescripcionErrorRegistro": "Si TipoFactura es F1 o F3 o R1 o R2 o R3 o R4 el bloque Destinatarios tiene que estar cumplimentado."
+      }
+    },
+    "registro": {
+      "estadoRegistro": "Incorrecto",
+      "codigoErrorRegistro": "1189",
+      "descripcionErrorRegistro": "Si TipoFactura es F1 o F3 o R1 o R2 o R3 o R4 el bloque Destinatarios tiene que estar cumplimentado."
+    }
+  }
+}
+```
+
+> **Nota:** `data` contiene **todo** lo que AEAT devolvió. `rawResponse` es el cuerpo crudo tal cual, para conservarlo en auditoría. La AEAT exige guardar la respuesta de cada envío.
+
+### Parser XML→JSON (`parseSoapResponse`)
+
+```ts
+import { parseSoapResponse } from '@dwast/verifactu-lib/aeat';
+
+const soap = parseSoapResponse(xmlResponse);  // → SoapResponse | null
+```
+
+Convierte el SOAP XML de AEAT a JSON normalizado, mapeando a las interfaces tipadas. Devuelve `null` si la entrada no es XML.
+
+### URLs oficiales
+
+| Entorno | Endpoint SOAP (remisión voluntaria) |
+|---------|-------------------------------------|
+| Producción | `https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP` |
+| Pruebas | `https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP` |
+
+| Entorno | Endpoint SOAP (bajo requerimiento) |
+|---------|-------------------------------------|
+| Producción | `https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/RequerimientoSOAP` |
+| Pruebas | `https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/RequerimientoSOAP` |
+
+WSDL: `.../tikeV1.0/cont/ws/SistemaFacturacion.wsdl`. La operación de consulta (`ConsultaFactuSistemaFacturacion`) usa el **mismo endpoint** `VerifactuSOAP`.
+
+---
+
+## Integración (`integration`)
+
+### Requisitos del sistema consumidor
+
+1. **Persistencia.** El sistema DEBE implementar `VerifactuRepository` y disponer de las tablas de `src/integration/schema.sql` (`verifactu_records`, `verifactu_responses`). La AEAT exige conservar la respuesta de cada envío.
+2. **Credenciales.** Para el envío real, el sistema aporta el certificado (`.p12`) y el NIF.
+
+### Repositorio (`VerifactuRepository`)
+
+```ts
+import type { VerifactuRepository, StoredRecord, StoredResponse, RecordStatus } from '@dwast/verifactu-lib/integration';
+
+// El sistema consumidor implementa esta interfaz (Mongoose, Prisma, etc.)
+const repo: VerifactuRepository = {
+  saveRecord(record) { /* ... */ },
+  updateRecordStatus(id, status) { /* ... */ },
+  getRecord(id) { /* ... */ },
+  getLastRecord() { /* ... */ },
+  saveResponse(response) { /* ... */ },
+  getResponses(recordId) { /* ... */ },
+};
+```
+
+**Estados (`RecordStatus`):** `PENDING` → `SENT` → `CONFIRMED` / `REJECTED` → `ANNULLED`.
+
+### Servicio de facturación (`VerifactuService`)
+
+```ts
+import { VerifactuService } from '@dwast/verifactu-lib/integration';
+import { VerifactuClient } from '@dwast/verifactu-lib/aeat';
+
+const service = new VerifactuService(repo, client, certificatePem?);
+
+await service.registerInvoice(invoice);              // emitir (alta)
+await service.annulInvoice(invoiceId, invoice?);     // anular
+await service.modifyInvoice(invoiceId, corrected);   // modificar (anula + alta)
+```
+
+| Método | Descripción |
+|--------|-------------|
+| `registerInvoice(invoice)` | Valida, genera XML + hash, guarda el registro, lo envía a AEAT y persiste la respuesta |
+| `annulInvoice(invoiceId, invoice?)` | Genera un registro de anulación y marca la original como `ANNULLED` |
+| `modifyInvoice(invoiceId, correctedInvoice)` | Verifactu no tiene "modificación": anula la original + emite la corregida |
+| `registerEvent(evento)` | Genera el XML de un evento, calcula su huella encadenada, lo persiste y lo envía |
+
+### Lectura del `.p12` (`readP12`)
+
+Lee el `.p12` e itera **todos** sus campos, devolviéndolos. No interpreta qué campo es cada cosa.
+
+```ts
+import { readP12, extractCertificateInfo, extractNifFromCertificate } from '@dwast/verifactu-lib/integration';
+
+const content = readP12(buffer, password);
+// content.certificates[0] → cert PEM
+// content.keys[0]         → key PEM
+// content.bags            → todos los campos
+
+// Utilidades explícitas (para detección de representante)
+const info = extractCertificateInfo(certPem);   // { nif, nombreRazon } | null
+const nif = extractNifFromCertificate(certPem); // NIF del certificado | null
+```
+
+### Detección de representante
+
+Si el NIF del certificado difiere del NIF del obligado a emitir, el certificado actúa como **representante** y se añade el bloque `Representante` en la cabecera:
+
+```ts
+import { buildCabecera } from '@dwast/verifactu-lib/core';
+import { extractCertificateInfo } from '@dwast/verifactu-lib/integration';
+
+const cabecera = buildCabecera(
+  { nombreRazon: 'MOVVIENDO TOURISM GROUP SL', nif: 'B18579458' },
+  certificatePem,
+  extractCertificateInfo,
+);
+// cabecera.representante = { nombreRazon: 'ANTONIO JOSE RECHE MARTÍNEZ', nif: '74654958V' }
+```
+
+### Accountability (contabilidad) (`AccountabilityService`)
+
+Combina credenciales + cliente mTLS + persistencia. El NIF se aporta en el config (la librería no interpreta los campos del certificado).
+
+```ts
+import { AccountabilityService } from '@dwast/verifactu-lib/integration';
+
+const service = new AccountabilityService(repo, {
+  baseUrl: 'https://...aeat...',
+  nif: 'B18579458',
+  p12Buffer,          // o cert/key PEM
+  p12Password: '...',
+});
+
+await service.registerInvoice(invoice);
+```
+
+### Credenciales por tenant
+
+La librería **no gestiona el multitenancy**: solo recibe los datos (el `.p12`, la contraseña, la factura) y los envía. Cómo cada app guarda y administra las credenciales de cada tenant es problema suyo.
+
+Un patrón habitual en apps multitenant es pedir la contraseña del `.p12` **una vez** al iniciar el proceso de facturación y cachearla en memoria (nunca en la BD). Eso se implementa en la app, no en la librería.
+
+---
+
+## Tests
+
+La suite usa **vitest**. Ejecuta:
+
+```bash
+npm test
+```
+
+### Tests unitarios (sin red)
+
+| Archivo | Qué cubre |
+|---------|-----------|
+| `test/hash.test.ts` | Cálculo de huella (alta, anulación, evento), concatenación, verificación, cadena `HashChain` |
+| `test/xml.test.ts` | Generación de XML (RegistroAlta, Suministro, Cabecera, Representante) |
+| `test/qr.test.ts` | Generación del payload QR |
+| `test/p12.test.ts` | Lectura del `.p12`, extracción de NIF e info del certificado, detección de representante |
+| `test/client.test.ts` | Resolución de URL por entorno, parseo de respuesta |
+| `test/response.test.ts` | Parser SOAP→JSON y mapeo a interfaces tipadas |
+| `test/validation.test.ts` | Validación de facturas (campos obligatorios, formato de fechas) |
+| `test/integration.test.ts` | Servicio de orquestación (con repositorio mock) |
+
+### Test de integración real contra AEAT (`test/aeat-integration.test.ts`)
+
+Envía registros reales al **entorno de pruebas** de AEAT (`https://prewww1.aeat.es`). Requiere un certificado FNMT válido. Si la conexión falla por autenticación o red, el test se **salta** (no falla).
+
+**Casos cubiertos:**
+
+| Caso | Descripción |
+|------|-------------|
+| Envía 1 factura | Alta con `PrimerRegistro` |
+| Envía 2 facturas encadenadas | La 2ª usa la huella de la 1ª (`RegistroAnterior`) |
+| Anula una factura y emite una nueva | Alta → Anulación → Nueva alta |
+| Consulta la huella de un registro enviado | Usa `queryInvoice` en vez de guardar la huella localmente |
+
+**Detalles del test de integración:**
+
+- **Número de factura único** `YYYYMMDDHHMMSS` para evitar duplicados entre ejecuciones.
+- **Espera de 1s** al inicio de cada test para que los números no colisionen.
+- **Sistema informático único por test** (`numeroInstalacion`) para que `PrimerRegistro` sea válido aunque el entorno ya tenga facturas.
+- **`FechaHoraHusoGenRegistro`** = hora actual con huso detectado (`nowIsoWithOffset`).
+- **Cada test vuelca en `test/responses/aeat-integration.log`** (TXT, gitignored) lo que se **envía** (XML) y lo que se **recibe** de AEAT, para poder depurar si algo falla. Se añade (append) en cada ejecución, acumulando el historial completo.
+
+> **Nota:** `IdSistemaInformatico` es `TextMax2Type` (máx 2 caracteres). La unicidad por test va en `NumeroInstalacion` (hasta 100 caracteres).
+
+---
+
+## Autenticación ante AEAT
+
+La AEAT sabe de quién es cada factura por **tres mecanismos**:
+
+| Mecanismo | Qué garantiza |
+|-----------|---------------|
+| **NIF en el XML** (`IDEmisorFactura`) | De quién es la factura (identidad en el contenido) |
+| **Certificado digital en la conexión** (mTLS) | Quién envía (autenticación del canal) |
+| **Huella/hash** | Que no se ha manipulado (integridad) |
+
+El `.p12` se usa para el **handshake TLS (mTLS)**: se extraen `cert` + `key` y se pasan al cliente. El NIF se aporta por la app.
+
+---
+
+## Seguridad de credenciales
+
+| Enfoque | Seguridad |
+|---------|-----------|
+| `.p12` + contraseña en la BD | ❌ Mala (atacante lo tiene todo) |
+| `.p12` en la BD, contraseña en env/secret manager | ✅ Buena |
+| `.p12` en la BD, contraseña pedida en runtime y cacheada en memoria | ✅ Buena |
+| Solo certificado en la BD, clave privada en secret manager | ✅✅ La más segura |
+
+---
+
 ## Scripts
 
 ```bash
-npm run build       # compila a dist/
+npm run build       # compila ESM + CJS a dist/
 npm run typecheck   # typecheck sin emitir
 npm test            # ejecuta vitest
 ```
 
 ## Publicación
 
-Paquete privado (`"private": true`). Instálalo desde un registry privado (GitHub Packages, Verdaccio, GitLab Package Registry) o directamente desde el repo:
+Paquete público en npm. Instálalo con:
 
 ```bash
-npm install git+https://github.com/tu-org/verifactu-lib.git
+npm install @dwast/verifactu-lib
 ```
 
-## Algoritmo de huella (hash)
-
-La huella de un registro Verifactu **no se calcula sobre el XML**, sino sobre una cadena canónica de campos concatenados en el formato `nombreCampo=valor&...`:
-
-- **Alta (8 campos):** `IDEmisorFactura`, `NumSerieFactura`, `FechaExpedicionFactura`, `TipoFactura`, `CuotaTotal`, `ImporteTotal`, `Huella` (hash anterior), `FechaHoraHusoGenRegistro`.
-- **Anulación (5 campos):** `IDEmisorFacturaAnulada`, `NumSerieFacturaAnulada`, `FechaExpedicionFacturaAnulada`, `Huella`, `FechaHoraHusoGenRegistro`.
-
-Reglas: se recortan espacios al inicio/final, los campos vacíos van como `nombreCampo=`, **no se aplica URL-encoding**, y el resultado es **SHA-256 en hexadecimal MAYÚSCULA** (64 caracteres). El hash anterior se coloca en el campo `Huella` en su posición exacta. La implementación está verificada contra los [vectores oficiales de la AEAT](https://www.agenciatributaria.es/static_files/AEAT_Desarrolladores/EEDD/IVA/VERI-FACTU/Veri-Factu_especificaciones_huella_hash_registros.pdf).
-
 ## Nota sobre el esquema oficial
 
-El XML generado sigue la estructura del RD 1007/2023 y la documentación de la AEAT, pero **debe validarse contra el XSD oficial** (descargable desde el [portal de desarrolladores de la AEAT](https://www.agenciatributaria.es/AEAT.desarrolladores/Desarrolladores/_menu_/Documentacion/Sistemas_Informaticos_de_Facturacion_y_Sistemas_VERI_FACTU/Sistemas_Informaticos_de_Facturacion_y_Sistemas_VERI_FACTU.html)) antes de producción.
+El XML generado sigue la estructura del RD 1007/2023 y la documentación de la AEAT, y se ha validado contra el entorno de pruebas real. No obstante, **debe validarse contra el XSD oficial** (descargable desde el [portal de desarrolladores de la AEAT](https://www.agenciatributaria.es/AEAT.desarrolladores/Desarrolladores/_menu_/Documentacion/Sistemas_Informaticos_de_Facturacion_y_Sistemas_VERI_FACTU/Sistemas_Informaticos_de_Facturacion_y_Sistemas_VERI_FACTU.html)) antes de producción.