@dwast/verifactu-lib 0.1.0-beta.0 → 0.1.0-beta.2

package/src/aeat/client.ts

@@ -1,3 +1,72 @@
+import https from 'node:https';
+import { buildRemisionEnvelope, AEAT_INFORMACION_NAMESPACE } from '../core/xml/generator.js';
+import { parseSoapResponse, type SoapResponse, type RegistroResponse, type ConsultaResponse, type EventoResponse } from './response.js';
+
+/**
+ * URL base del servicio AEAT en PRODUCCIÓN (Verifactu v1.0).
+ * Fuente: Veri-Factu_Descripcion_SWeb.pdf (Anexo I, entorno de producción).
+ */
+export const AEAT_PRODUCTION_BASE_URL = 'https://www2.agenciatributaria.gob.es';
+
+/**
+ * URL base del servicio AEAT en PRUEBAS/desarrollo (Verifactu v1.0).
+ * Fuente: Veri-Factu_Descripcion_SWeb.pdf (Anexo I, entorno de pruebas).
+ */
+export const AEAT_TEST_BASE_URL = 'https://prewww2.aeat.es';
+
+/**
+ * Ruta del WSDL del servicio SistemaFacturacion (Verifactu v1.0).
+ */
+export const AEAT_WSDL_PATH =
+  '/static_files/common/internet/dep/aplicaciones/es/aeat/tikeV1.0/cont/ws/SistemaFacturacion.wsdl';
+
+/**
+ * Endpoint SOAP de remisión voluntaria (VerifactuSOAP).
+ * - Producción: `https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP`
+ * - Pruebas:    `https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP`
+ */
+export const AEAT_PRODUCTION_SOAP_URL =
+  'https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP';
+export const AEAT_TEST_SOAP_URL =
+  'https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP';
+
+/**
+ * Endpoint SOAP de remisión bajo requerimiento (RequerimientoSOAP).
+ */
+export const AEAT_PRODUCTION_REQUERIMIENTO_URL =
+  'https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/RequerimientoSOAP';
+export const AEAT_TEST_REQUERIMIENTO_URL =
+  'https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/RequerimientoSOAP';
+
+/**
+ * Operación SOAP de alta/anulación de registros.
+ */
+export const AEAT_OPERATION_REGISTRO = 'RegFactuSistemaFacturacion';
+
+/**
+ * Operación SOAP de consulta.
+ */
+export const AEAT_OPERATION_CONSULTA = 'ConsultaFactuSistemaFacturacion';
+
+/**
+ * Namespace del servicio (targetNamespace del WSDL).
+ */
+export const AEAT_SOAP_NAMESPACE =
+  'https://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/tike/cont/ws/SistemaFacturacion.wsdl';
+
+/**
+ * Namespace del elemento de consulta (`ConsultaLR.xsd`).
+ */
+export const AEAT_CONSULTA_NAMESPACE =
+  'https://www2.agenciatributaria.gob.es/static_files/common/internet/dep/aplicaciones/es/aeat/tike/cont/ws/ConsultaLR.xsd';
+
+/**
+ * Entorno de ejecución del cliente AEAT.
+ * - `production`: usa la URL de producción.
+ * - `test` / `development`: usa la URL de pruebas (si se aporta).
+ */
+export type VerifactuEnv = 'production' | 'test' | 'development';
+
 /**
  * Cliente para los servicios web de AEAT (Verifactu).
  *
@@ -5,24 +74,54 @@
  * (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.
+ * Soporta autenticación por certificado digital (mTLS): se pasan `cert` y
+ * `key` (PEM) extraídos de un `.p12` (ver `readP12` en `integration/p12.ts`).
  */
 export interface VerifactuClientConfig {
-  /** URL base del servicio AEAT. */
-  baseUrl: string;
-  /** Token de autenticación (OAuth) o certificado. */
+  /** URL del endpoint SOAP del servicio AEAT en PRODUCCIÓN. */
+  baseUrl?: string;
+  /** URL del endpoint SOAP del servicio AEAT en PRUEBAS/desarrollo. */
+  testBaseUrl?: string;
+  /** Entorno de ejecución. Si no es `production`, se usa `testBaseUrl`. */
+  env?: VerifactuEnv;
+  /** Token de autenticación (OAuth) alternativo al certificado. */
   authToken?: string;
-  /** Ruta del endpoint de envío de registros. */
-  sendPath?: string;
-  /** Ruta del endpoint de consulta de estado. */
-  statusPath?: string;
+  /** Certificado de cliente en PEM (mTLS). */
+  cert?: string;
+  /** Clave privada del cliente en PEM (mTLS). */
+  key?: string;
+  /** Operación SOAP (por defecto `RegFactuSistemaFacturacion`). */
+  operation?: string;
+  /** Namespace del servicio SOAP. */
+  namespace?: string;
   /** Timeout de petición en ms. */
   timeoutMs?: number;
 }
 
+/**
+ * Resuelve la URL base efectiva según el entorno.
+ *
+ * Regla: **por defecto se usa producción** (la app real factura en prod).
+ * - Si `env` es `production` (o no se indica), usa `baseUrl`.
+ * - Si `env` es `test`/`development`, usa `testBaseUrl`.
+ *
+ * Los tests se ejecutan aparte y fijan `env: 'test'` + `testBaseUrl` para
+ * usar desarrollo (sin necesidad de indicar la URL de producción).
+ */
+export function resolveBaseUrl(config: Pick<VerifactuClientConfig, 'baseUrl' | 'testBaseUrl' | 'env'>): string {
+  const env = config.env ?? 'production';
+  if (env !== 'production') {
+    if (config.testBaseUrl) {
+      return config.testBaseUrl;
+    }
+    throw new Error('env no es "production" y no se ha proporcionado testBaseUrl.');
+  }
+  if (!config.baseUrl) {
+    throw new Error('env es "production" y no se ha proporcionado baseUrl.');
+  }
+  return config.baseUrl;
+}
+
 export interface SendResult {
   /** Identificador de la operación devuelto por AEAT. */
   operationId: string;
@@ -34,13 +133,25 @@ export interface SendResult {
   errorCode?: string;
   /** Cuerpo completo de la respuesta (para auditoría). */
   rawResponse?: string;
+  /** Respuesta completa parseada de AEAT (todo lo recibido, OK o error). */
+  data?: Record<string, unknown>;
+  /** Respuesta SOAP normalizada a JSON (XML → JSON). */
+  response?: SoapResponse;
+  /** Respuesta tipada de registro (si la operación es de registro). */
+  registro?: RegistroResponse;
+  /** Respuesta tipada de consulta (si la operación es de consulta). */
+  consulta?: ConsultaResponse;
+  /** Respuesta tipada de evento (si la operación es de evento). */
+  evento?: EventoResponse;
 }
 
 interface ResolvedConfig {
   baseUrl: string;
   authToken?: string;
-  sendPath: string;
-  statusPath: string;
+  cert?: string;
+  key?: string;
+  operation: string;
+  namespace: string;
   timeoutMs: number;
 }
 
@@ -49,89 +160,219 @@ interface ResolvedConfig {
  */
 export class VerifactuClient {
   private readonly config: ResolvedConfig;
+  private readonly agent: https.Agent;
 
   constructor(config: VerifactuClientConfig) {
     this.config = {
-      sendPath: '/verifactu/registro',
-      statusPath: '/verifactu/estado',
+      operation: AEAT_OPERATION_REGISTRO,
+      namespace: AEAT_SOAP_NAMESPACE,
       timeoutMs: 10_000,
       ...config,
+      baseUrl: resolveBaseUrl(config),
     };
+
+    // Si hay certificado y clave, se usan en el handshake TLS (mTLS).
+    this.agent = new https.Agent(
+      this.config.cert && this.config.key
+        ? { cert: this.config.cert, key: this.config.key }
+        : undefined,
+    );
   }
 
   /**
-   * Envía un registro (factura o evento) a AEAT.
+   * Envía un registro (factura o evento) a AEAT mediante SOAP.
    */
   async sendRecord(xml: string): Promise<SendResult> {
-    const url = `${this.config.baseUrl}${this.config.sendPath}`;
+    const envelope = buildRemisionEnvelope(xml);
+    const url = new URL(this.config.baseUrl);
     const headers: Record<string, string> = {
-      'Content-Type': 'application/xml',
-      Accept: 'application/json',
+      'Content-Type': 'text/xml; charset=utf-8',
+      SOAPAction: '',
+      Accept: 'application/xml',
     };
     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);
-    }
+    return this.request(url, 'POST', headers, envelope);
   }
 
   /**
-   * Consulta el estado de una operación enviada.
+   * @deprecated La consulta por ID de operación no está soportada por el
+   * esquema `ConsultaLR.xsd` de AEAT (devuelve error 4118). Usa
+   * {@link queryInvoice} para consultar registros por número de factura.
    */
   async getOperationStatus(operationId: string): Promise<SendResult> {
-    const url = `${this.config.baseUrl}${this.config.statusPath}/${encodeURIComponent(operationId)}`;
-    const headers: Record<string, string> = { Accept: 'application/json' };
+    const consultaXml = `<ConsultaFactuSistemaFacturacion xmlns="${this.config.namespace}"><ID>${operationId}</ID></ConsultaFactuSistemaFacturacion>`;
+    const envelope = buildRemisionEnvelope(consultaXml);
+    const url = new URL(this.config.baseUrl);
+    const headers: Record<string, string> = {
+      'Content-Type': 'text/xml; charset=utf-8',
+      SOAPAction: '',
+      Accept: 'application/xml',
+    };
     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);
+    return this.request(url, 'POST', headers, envelope);
+  }
+
+  /**
+   * Consulta un registro de facturación por número de factura y devuelve la
+   * respuesta completa (incluida la huella confirmada por AEAT).
+   *
+   * Usa la operación `ConsultaFactuSistemaFacturacion` (mismo endpoint SOAP).
+   */
+  async queryInvoice(params: {
+    /** Obligado a la emisión (quien consulta). */
+    obligado: { nombreRazon: string; nif: string };
+    /** Nº serie + nº factura a consultar (opcional: consulta por periodo). */
+    numSerieFactura?: string;
+    /** Ejercicio (año) del periodo de imputación, p. ej. `2026`. */
+    ejercicio: string;
+    /** Periodo de imputación, p. ej. `01` (enero) o `12` (diciembre). */
+    periodo: string;
+  }): Promise<SendResult> {
+    const consultaXml = [
+      `<sfLRC:ConsultaFactuSistemaFacturacion xmlns:sfLRC="${AEAT_CONSULTA_NAMESPACE}" xmlns:sf="${AEAT_INFORMACION_NAMESPACE}">`,
+      '  <sfLRC:Cabecera>',
+      '    <sf:IDVersion>1.0</sf:IDVersion>',
+      '    <sf:ObligadoEmision>',
+      `      <sf:NombreRazon>${params.obligado.nombreRazon}</sf:NombreRazon>`,
+      `      <sf:NIF>${params.obligado.nif}</sf:NIF>`,
+      '    </sf:ObligadoEmision>',
+      '  </sfLRC:Cabecera>',
+      '  <sfLRC:FiltroConsulta>',
+      '    <sfLRC:PeriodoImputacion>',
+      `      <sf:Ejercicio>${params.ejercicio}</sf:Ejercicio>`,
+      `      <sf:Periodo>${params.periodo}</sf:Periodo>`,
+      '    </sfLRC:PeriodoImputacion>',
+      ...(params.numSerieFactura
+        ? [`    <sfLRC:NumSerieFactura>${params.numSerieFactura}</sfLRC:NumSerieFactura>`]
+        : []),
+      '  </sfLRC:FiltroConsulta>',
+      '</sfLRC:ConsultaFactuSistemaFacturacion>',
+    ].join('\n');
+    const envelope = buildRemisionEnvelope(consultaXml);
+    const url = new URL(this.config.baseUrl);
+    const headers: Record<string, string> = {
+      'Content-Type': 'text/xml; charset=utf-8',
+      SOAPAction: '',
+      Accept: 'application/xml',
+    };
+    if (this.config.authToken) {
+      headers.Authorization = `Bearer ${this.config.authToken}`;
     }
+
+    return this.request(url, 'POST', headers, envelope);
+  }
+
+  /**
+   * Realiza la petición HTTPS usando el agente (con mTLS si hay certificado).
+   */
+  private request(
+    url: URL,
+    method: 'GET' | 'POST',
+    headers: Record<string, string>,
+    body?: string,
+  ): Promise<SendResult> {
+    return new Promise((resolve, reject) => {
+      const req = https.request(
+        {
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: `${url.pathname}${url.search}`,
+          method,
+          headers,
+          agent: this.agent,
+        },
+        (res) => {
+          let raw = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => {
+            raw += chunk;
+          });
+          res.on('end', () => {
+            resolve(this.parseResponse(raw, res.statusCode ?? 0));
+          });
+        },
+      );
+
+      req.on('error', reject);
+      req.setTimeout(this.config.timeoutMs, () => {
+        req.destroy(new Error(`Timeout tras ${this.config.timeoutMs}ms`));
+      });
+
+      if (body) {
+        req.write(body);
+      }
+      req.end();
+    });
   }
 
   /**
    * Parsea la respuesta de AEAT. La estructura exacta depende del servicio;
    * este es un mapeo base que el consumidor puede sobrescribir.
+   *
+   * Devuelve SIEMPRE todo lo recibido: la respuesta completa parseada en
+   * `data` y el cuerpo crudo en `rawResponse`, tanto si es OK como error.
    */
   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;
+    let data: Record<string, unknown> | undefined;
+    let response: SoapResponse | 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;
+    // AEAT responde en SOAP/XML: se normaliza a JSON.
+    const soap = parseSoapResponse(raw);
+    if (soap) {
+      response = soap;
+      data = soap.body;
+      operationId = String(soap.body['ID'] ?? soap.body['IdPeticion'] ?? '');
+      // Estado según el registro/consulta/evento mapeado.
+      const reg = soap.registro;
+      const con = soap.consulta;
+      const ev = soap.evento;
+      const estado = reg?.estadoRegistro ?? con?.estado ?? ev?.estadoEvento;
+      if (estado) {
+        status = /OK|ACEPTAD|CONFIRMAD|CORRECT/i.test(estado) ? 'OK' : 'ERROR';
+      }
+      errorCode = reg?.codigoErrorRegistro ?? con?.codigoError ?? ev?.codigoErrorEvento;
+      message =
+        reg?.descripcionErrorRegistro ??
+        con?.descripcionError ??
+        ev?.descripcionErrorEvento ??
+        estado;
+    } else {
+      // Respuesta no XML/JSON: se conserva el cuerpo como mensaje.
+      try {
+        const json = JSON.parse(raw) as Record<string, unknown>;
+        data = json;
+        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 {
+        message = raw;
       }
-      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 };
+    return {
+      operationId,
+      status,
+      message,
+      errorCode,
+      rawResponse: raw,
+      data,
+      response,
+      registro: response?.registro,
+      consulta: response?.consulta,
+      evento: response?.evento,
+    };
   }
 }

package/src/aeat/index.ts

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

package/src/aeat/response.ts

@@ -0,0 +1,195 @@
+import { XMLParser } from 'fast-xml-parser';
+
+/**
+ * Respuesta de AEAT para un registro de facturación (alta/anulación).
+ *
+ * AEAT devuelve un SOAP XML; este tipo es el resultado normalizado a JSON
+ * para que el sistema consumidor lo persista y lo maneje con facilidad.
+ */
+export interface RegistroResponse {
+  /** Estado del registro devuelto por AEAT. */
+  estadoRegistro?: string;
+  /** Código de error del registro (si lo hay). */
+  codigoErrorRegistro?: string;
+  /** Descripción del error del registro (si lo hay). */
+  descripcionErrorRegistro?: string;
+  /** CSV (Código Seguro de Verificación) si AEAT lo devuelve. */
+  csv?: string;
+  /** Huella (hash) del registro confirmado por AEAT. */
+  huella?: string;
+  /** Fecha/hora de generación del registro en AEAT. */
+  fechaHoraHusoGenRegistro?: string;
+  /** Identificador de la factura (si AEAT lo devuelve). */
+  idFactura?: string;
+}
+
+/**
+ * Respuesta de AEAT para una consulta de estado de operación.
+ */
+export interface ConsultaResponse {
+  /** Estado de la operación consultada. */
+  estado?: string;
+  /** Código de error (si lo hay). */
+  codigoError?: string;
+  /** Descripción del error (si lo hay). */
+  descripcionError?: string;
+  /** CSV de la operación consultada. */
+  csv?: string;
+  /** Huella (hash) de la operación consultada. */
+  huella?: string;
+  /** Registros devueltos por la consulta. */
+  registros?: RegistroResponse[];
+}
+
+/**
+ * Respuesta de AEAT para un registro de evento.
+ */
+export interface EventoResponse {
+  /** Estado del evento devuelto por AEAT. */
+  estadoEvento?: string;
+  /** Código de error del evento (si lo hay). */
+  codigoErrorEvento?: string;
+  /** Descripción del error del evento (si lo hay). */
+  descripcionErrorEvento?: string;
+  /** CSV del evento si AEAT lo devuelve. */
+  csv?: string;
+  /** Huella (hash) del evento confirmado por AEAT. */
+  huella?: string;
+}
+
+/**
+ * Resultado normalizado de una respuesta SOAP de AEAT.
+ */
+export interface SoapResponse {
+  /** Nombre del elemento raíz del body SOAP (p. ej. `RespuestaRegFactuSistemaFacturacion`). */
+  operation: string;
+  /** Objeto JSON completo parseado del body SOAP. */
+  body: Record<string, unknown>;
+  /** Respuesta tipada de registro (si la operación es de registro). */
+  registro?: RegistroResponse;
+  /** Respuesta tipada de consulta (si la operación es de consulta). */
+  consulta?: ConsultaResponse;
+  /** Respuesta tipada de evento (si la operación es de evento). */
+  evento?: EventoResponse;
+}
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  removeNSPrefix: true,
+  parseTagValue: false,
+  trimValues: true,
+});
+
+/**
+ * Convierte un XML SOAP de AEAT a un objeto JSON normalizado.
+ *
+ * Extrae el body del sobre SOAP y mapea los campos a las interfaces tipadas
+ * (`RegistroResponse`, `ConsultaResponse`, `EventoResponse`). Si el XML no
+ * es parseable, devuelve `null`.
+ */
+export function parseSoapResponse(xml: string): SoapResponse | null {
+  // Solo procesar si parece XML (evita parsear JSON u otros textos).
+  if (typeof xml !== 'string' || !xml.trim().startsWith('<')) {
+    return null;
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = parser.parse(xml) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  // Navegar hasta el body del sobre SOAP (removeNSPrefix elimina el prefijo).
+  const envelope = (parsed['Envelope'] ?? parsed) as Record<string, unknown>;
+  const body = (envelope['Body'] ?? envelope) as Record<string, unknown>;
+
+  // El body contiene un único elemento de operación.
+  const keys = Object.keys(body).filter((k) => k !== 'Body');
+  const operation = keys[0] ?? '';
+  const opBody = body[operation] as Record<string, unknown> | undefined;
+
+  const result: SoapResponse = {
+    operation,
+    body: (opBody ?? body) as Record<string, unknown>,
+  };
+
+  // Mapear según el tipo de operación.
+  if (/RegFactu|Registro/i.test(operation)) {
+    result.registro = mapRegistro(opBody);
+  } else if (/Consulta/i.test(operation)) {
+    result.consulta = mapConsulta(opBody);
+  } else if (/Evento/i.test(operation)) {
+    result.evento = mapEvento(opBody);
+  }
+
+  return result;
+}
+
+function mapRegistro(opBody: Record<string, unknown> | undefined): RegistroResponse | undefined {
+  if (!opBody) return undefined;
+  const rf = (opBody['RegistroFactura'] ?? opBody) as Record<string, unknown>;
+  return {
+    estadoRegistro: str(rf['EstadoRegistro']),
+    codigoErrorRegistro: str(rf['CodigoErrorRegistro']),
+    descripcionErrorRegistro: str(rf['DescripcionErrorRegistro']),
+    csv: str(rf['CSV']),
+    huella: str(rf['Huella']),
+    fechaHoraHusoGenRegistro: str(rf['FechaHoraHusoGenRegistro']),
+    idFactura: str(rf['IDFactura']),
+  };
+}
+
+function mapConsulta(opBody: Record<string, unknown> | undefined): ConsultaResponse | undefined {
+  if (!opBody) return undefined;
+  // La consulta devuelve los registros en `RegistroRespuestaConsultaFactuSistemaFacturacion`
+  // (o `RegistroFactura`/`Registros` en otros formatos).
+  const registrosRaw =
+    opBody['RegistroRespuestaConsultaFactuSistemaFacturacion'] ??
+    opBody['RegistroFactura'] ??
+    opBody['Registros'];
+  const registros = Array.isArray(registrosRaw)
+    ? registrosRaw.map((r) => mapRegistroConsulta(r as Record<string, unknown>)).filter(Boolean)
+    : registrosRaw
+      ? [mapRegistroConsulta(registrosRaw as Record<string, unknown>)]
+      : undefined;
+  return {
+    estado: str(opBody['Estado']),
+    codigoError: str(opBody['CodigoError']),
+    descripcionError: str(opBody['DescripcionError']),
+    csv: str(opBody['CSV']),
+    huella: registros?.[0]?.huella,
+    registros: registros as RegistroResponse[] | undefined,
+  };
+}
+
+/** Mapea un registro de la respuesta de consulta (con `DatosRegistroFacturacion`). */
+function mapRegistroConsulta(
+  raw: Record<string, unknown>,
+): RegistroResponse | undefined {
+  const datos = (raw['DatosRegistroFacturacion'] ?? raw) as Record<string, unknown>;
+  const estado = (raw['EstadoRegistro'] ?? {}) as Record<string, unknown>;
+  return {
+    estadoRegistro: str(estado['EstadoRegistro']),
+    huella: str(datos['Huella']),
+    fechaHoraHusoGenRegistro: str(datos['FechaHoraHusoGenRegistro']),
+    idFactura: str(raw['IDFactura']),
+  };
+}
+
+function mapEvento(opBody: Record<string, unknown> | undefined): EventoResponse | undefined {
+  if (!opBody) return undefined;
+  return {
+    estadoEvento: str(opBody['EstadoEvento']),
+    codigoErrorEvento: str(opBody['CodigoErrorEvento']),
+    descripcionErrorEvento: str(opBody['DescripcionErrorEvento']),
+    csv: str(opBody['CSV']),
+    huella: str(opBody['Huella']),
+  };
+}
+
+function str(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  return String(value);
+}