@devlas/dte-sii 2.12.26 → 2.13.0

package/CafSolicitor.js

@@ -19,6 +19,7 @@ const SiiSession = require('./SiiSession');
 const SiiPortalAuth = require('./SiiPortalAuth');
 const SiiSessionStore = require('./SiiSessionStore');
 const { splitRut } = require('./utils/rut');
+const { resolveDataDir } = require('./utils/paths');
 
 /**
  * Registro global de sesiones SII (singleton por ambiente+rut).
@@ -58,7 +59,9 @@ class CafSolicitor {
 
     this.ambiente = options.ambiente.toLowerCase();
     this.rutEmisor = options.rutEmisor;
-    this.baseDir = options.baseDir || path.resolve(__dirname, '..', '..');
+    // Fallback neutral: antes era `__dirname/../..`, que en una instalación normal
+    // apunta dentro de node_modules — se escribían CAFs dentro de node_modules.
+    this.baseDir = options.baseDir || resolveDataDir();
     this.runStamp = options.runStamp || new Date().toISOString().replace(/[:.]/g, '-');
 
     // pfxBuffer tiene prioridad sobre pfxPath para evitar I/O a disco
@@ -280,7 +283,7 @@ class CafSolicitor {
    *   la simulación de certificación.
    * @returns {Promise<Object>} - { success, cafPath, xml, maxAutor, foliosDisp, error, errorCode }
    */
-  async solicitar({ tipoDte, cantidad = 1, minCantidad = null }) {
+  async solicitar({ tipoDte, cantidad = 1, minCantidad = null, soloConsultarTope = false }) {
     const { numero: rut, dv } = splitRut(this.rutEmisor);
     const debugDir = this._getDebugDir(tipoDte);
 
@@ -289,6 +292,10 @@ class CafSolicitor {
     this._lastFoliosDisp = null;
     this._maxAutorInsuficiente = false;
     this._minCantidad = minCantidad;
+    // Modo sondeo: recorre el flujo solo hasta el formulario que expone MAX_AUTOR y
+    // corta ahí, sin emitir nada. Permite saber si el SII está racionando este tipo
+    // ANTES de decidir si vale la pena anular folios.
+    this._soloConsultarTope = soloConsultarTope;
 
     // Rate limiting: mínimo 1001ms entre solicitudes para no saturar el portal SII.
     const _now = Date.now();
@@ -654,6 +661,13 @@ class CafSolicitor {
     // quien necesita N folios exactos (ej. simulación de certificación): el CAF chico
     // no se usa, suma +1 a FOLIOS_DISP y empeora el tope en el próximo intento.
     // Por eso, si el llamador declaró un mínimo, se aborta ANTES de emitir.
+    if (this._soloConsultarTope) {
+      // Se leyó lo único que interesaba (MAX_AUTOR/FOLIOS_DISP). Cortar acá es lo que
+      // hace barato el sondeo y, sobre todo, lo deja sin efectos: no se confirma folio,
+      // no se emite CAF, no sube FOLIOS_DISP.
+      return response;
+    }
+
     if (tieneMaxAutor && this._minCantidad && maxAutor < this._minCantidad) {
       this._maxAutorInsuficiente = true;
       console.warn(

package/DTE.js

@@ -11,6 +11,7 @@ const { XMLBuilder } = require('fast-xml-parser');
 const { DOMParser } = require('@xmldom/xmldom');
 const {
   sanitizeSiiText,
+  sanitizeTedText,
   formatBase64InXml,
   normalizeEmisor,
   normalizeReceptor,
@@ -264,8 +265,13 @@ class DTE {
     
     this.tmstFirma = timestampOverride || new Date().toISOString().replace(/\.\d{3}Z$/, '');
     
-    const rznRecepRaw = sanitizeSiiText((enc.Receptor.RznSocRecep || '').substring(0, 40));
-    const it1Raw = sanitizeSiiText((primerItem.NmbItem || 'Producto').substring(0, 40));
+    // sanitizeTedText (no sanitizeSiiText): pliega los acentos a ASCII porque el lector
+    // de PDF417 del SII no devuelve los bytes ≥128 tal como se codificaron, y como el TED
+    // va firmado, el SII valida la firma sobre lo que él leyó → "TED - Firma invalida".
+    // Se aplica ANTES de firmar, así la firma cubre exactamente los bytes del barcode.
+    // El DTE conserva el texto real con acentos; esto solo afecta al timbre.
+    const rznRecepRaw = sanitizeTedText((enc.Receptor.RznSocRecep || '').substring(0, 40));
+    const it1Raw = sanitizeTedText((primerItem.NmbItem || 'Producto').substring(0, 40));
     const rznRecepXml = this._escapeXmlText(rznRecepRaw);
     const it1Xml = this._escapeXmlText(it1Raw);
     

package/EnviadorSII.js

@@ -16,6 +16,7 @@ const https  = require('https');
 const crypto = require('crypto');
 const forge  = require('node-forge');
 const FormData = require('form-data');
+const { registrarHttpDebug, fetchRegistrado } = require('./utils/httpDebug');
 const { 
   saveEnvioArtifacts,
   siiError,
@@ -40,6 +41,9 @@ const {
 
 const log = createScopedLogger('EnviadorSII');
 
+/** `fetchRegistrado` con el cliente ya fijado, para no repetirlo en cada llamada. */
+const fetchRegistradoSII = (url, opciones) => fetchRegistrado(url, opciones, 'EnviadorSII');
+
 class EnviadorSII {
   /**
    * @param {Object} certificado - Instancia de Certificado (OBLIGATORIO)
@@ -113,11 +117,16 @@ class EnviadorSII {
           crypto.constants.SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION |
           crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT,
       };
+      const _t0 = Date.now();
       const req = https.request(opts, (res) => {
         const chunks = [];
         res.on('data', (c) => chunks.push(c));
         res.on('end', () => {
           const text = Buffer.concat(chunks).toString('latin1');
+          registrarHttpDebug({
+            url: urlStr, method: 'POST', status: res.statusCode, headers: res.headers,
+            body: text, reqBody: buf.toString('latin1'), ms: Date.now() - _t0, cliente: 'EnviadorSII',
+          });
           resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, text });
         });
       });
@@ -138,7 +147,7 @@ class EnviadorSII {
   async getSemilla() {
     const url = this.urls[this.ambiente].semilla;
     
-    const response = await fetch(url, {
+    const { response, text: xml } = await fetchRegistradoSII(url, {
       method: 'GET',
       headers: {
         'Accept': 'application/xml',
@@ -148,8 +157,7 @@ class EnviadorSII {
     if (!response.ok) {
       throw new Error(`Error obteniendo semilla: ${response.status}`);
     }
-    
-    const xml = await response.text();
+
     // Usar parser centralizado
     const data = parseXml(xml);
     
@@ -184,7 +192,7 @@ class EnviadorSII {
     
     const url = this.urls[this.ambiente].token;
     
-    const response = await fetch(url, {
+    const { response, text: xml } = await fetchRegistradoSII(url, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/xml',
@@ -194,11 +202,9 @@ class EnviadorSII {
     });
     
     if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`Error obteniendo token: ${response.status} - ${errorText}`);
+      throw new Error(`Error obteniendo token: ${response.status} - ${xml}`);
     }
-    
-    const xml = await response.text();
+
     // Usar parser centralizado con namespaces removidos
     const data = parseXmlNoNs(xml);
     
@@ -503,9 +509,17 @@ class EnviadorSII {
         },
       }, (res) => {
         let data = '';
+        const _t0 = Date.now();
         res.on('data', chunk => data += chunk);
         res.on('end', () => {
           log.log('HTTP Status:', res.statusCode);
+          // Es LA llamada que sube el DTE/BOLETA al SII. Se registra el multipart completo
+          // (incluye el XML enviado) porque cuando el SII rechaza, el motivo está ahí.
+          registrarHttpDebug({
+            url, method: 'POST', status: res.statusCode, headers: res.headers,
+            body: data, reqBody: formBuffer.toString('latin1'),
+            ms: Date.now() - _t0, cliente: 'EnviadorSII',
+          });
           resolve({ text: data, status: res.statusCode });
         });
       });
@@ -586,9 +600,17 @@ class EnviadorSII {
         },
       }, (res) => {
         let data = '';
+        const _t0 = Date.now();
         res.on('data', chunk => data += chunk);
         res.on('end', () => {
           log.log('HTTP Status:', res.statusCode);
+          // Es LA llamada que sube el DTE/BOLETA al SII. Se registra el multipart completo
+          // (incluye el XML enviado) porque cuando el SII rechaza, el motivo está ahí.
+          registrarHttpDebug({
+            url, method: 'POST', status: res.statusCode, headers: res.headers,
+            body: data, reqBody: formBuffer.toString('latin1'),
+            ms: Date.now() - _t0, cliente: 'EnviadorSII',
+          });
           resolve({ text: data, status: res.statusCode });
         });
       });
@@ -700,7 +722,7 @@ class EnviadorSII {
     
     log.log('Consultando estado:', url);
     
-    const response = await fetch(url, {
+    const { response, text: responseText } = await fetchRegistradoSII(url, {
       method: 'GET',
       headers: {
         'Cookie': `TOKEN=${this.token}`,
@@ -708,8 +730,6 @@ class EnviadorSII {
         'User-Agent': 'Mozilla/4.0 ( compatible; PROG 1.0; Windows NT)',
       },
     });
-    
-    const responseText = await response.text();
     log.log('Respuesta estado:', responseText);
     
     if (!response.ok) {

package/FolioRegistry.js

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { resolveDataDir } = require('./utils/paths');
 
 /**
  * Clase para manejar el registro de folios
@@ -28,7 +29,11 @@ class FolioRegistry {
     } else if (options.baseDir) {
       this.registryPath = path.join(options.baseDir, 'debug', 'folios.json');
     } else {
-      this.registryPath = path.resolve(__dirname, '..', '..', 'debug', 'folios.json');
+      // folios.json es estado FUNCIONAL (control de folios usados), no diagnóstico:
+      // si se pierde o se escribe en un lugar impredecible se pueden repetir folios
+      // ante el SII. Por eso el fallback es resolveDataDir() y no una ruta relativa
+      // a node_modules, que era donde caía `__dirname/../..`.
+      this.registryPath = path.join(resolveDataDir(), 'debug', 'folios.json');
     }
   }
 
@@ -414,7 +419,7 @@ class FolioRegistry {
       throw new Error(`findLatestCaf: ambiente inválido "${ambiente}"`);
     }
 
-    const base = baseDir || process.cwd();
+    const base = baseDir || resolveDataDir();
     
     // Buscar en estructura organizada: debug/caf/<ambiente>/<rut>/<tipoDte>/<fecha>/
     const rutClean = rutEmisor.replace(/\./g, '').toUpperCase();

package/FolioService.js

@@ -15,6 +15,7 @@ const SiiSession = require('./SiiSession');
 const FolioRegistry = require('./FolioRegistry');
 const CAF = require('./CAF');
 const CafSolicitor = require('./CafSolicitor');
+const { resolveDataDir } = require('./utils/paths');
 
 /**
  * Clase para gestión integral de folios
@@ -51,11 +52,28 @@ class FolioService {
 
     this.ambiente = options.ambiente;
     this.rutEmisor = options.rutEmisor;
-    this.baseDir = options.baseDir || path.resolve(__dirname, '..', '..');
+    // Fallback neutral: antes era `__dirname/../..`, que en una instalación normal
+    // apunta dentro de node_modules — se escribían artefactos dentro de la propia
+    // carpeta de dependencias.
+    this.baseDir = options.baseDir || resolveDataDir();
     
     // Directorios
     this.cafDir = options.cafDir || path.join(this.baseDir, 'debug', 'auto-caf');
     this.debugDir = options.debugDir || path.join(this.baseDir, 'debug');
+    /**
+     * Estado que debe SOBREVIVIR a la corrida, separado de `debugDir`.
+     *
+     * Acá vive el registro de folios que el SII ya reportó como anulados
+     * (`folios-anulados-{rut}-{tipo}.json`). Guardarlo en `debugDir` — que es por
+     * corrida — lo volvía inútil: nacía vacío en cada ejecución y se volvían a
+     * intentar anular los mismos folios una y otra vez.
+     *
+     * Medido el 11/08/2026 en una empresa con muchas pruebas encima: 87 intentos de
+     * anulación en una sola etapa, **0 anulados y 87 rechazados por "ya anulado"**.
+     * Como el camino bulk falla y cae a folio-a-folio, cada intento cuesta 2 requests
+     * al SII: varios minutos de la corrida gastados en no hacer nada.
+     */
+    this.stateDir = options.stateDir || this.debugDir;
     
     // Sesión SII — priorizar reutilización para evitar bans del SII
     // Orden: (1) sesión explícita, (2) registro de CafSolicitor, (3) nueva sesión
@@ -289,6 +307,31 @@ class FolioService {
    *   usar para destrabar el tope. Ponerlo en false lo deja en modo consulta.
    * @returns {Promise<Object>} { ok, cafPath, otorgados, maxAutor, foliosDisp, errorCode, error }
    */
+  /**
+   * Consulta cuánto autoriza el SII para un tipo, SIN emitir nada.
+   *
+   * Recorre el flujo de timbraje solo hasta el formulario que expone MAX_AUTOR y
+   * FOLIOS_DISP, y corta ahí. Sirve para decidir si hace falta anular folios antes de
+   * pedir, en vez de anular siempre por las dudas.
+   *
+   * ⚠️ Ausencia de MAX_AUTOR no es cero: el SII **solo publica esos campos cuando está
+   * racionando** ese tipo de documento (verificado 2026-07-22: tras anular folios, los
+   * tipos 56 y 61 dejaron de exponerlos). Por eso se devuelve `sinTope: true`, que
+   * significa "el SII no está limitando", no "no se pudo leer".
+   *
+   * @returns {Promise<{ sinTope: boolean, maxAutor: number|null, foliosDisp: number|null }>}
+   */
+  async consultarTope({ tipoDte }) {
+    if (!this.cafSolicitor) {
+      throw new Error('FolioService: CafSolicitor no inicializado (se requiere pfxPath y pfxPassword)');
+    }
+    await this.cafSolicitor.solicitar({ tipoDte, cantidad: 1, soloConsultarTope: true });
+    const maxAutor   = this.cafSolicitor._lastMaxAutor ?? null;
+    const foliosDisp = this.cafSolicitor._lastFoliosDisp ?? null;
+    // `_lastFoliosDisp` queda en null justamente cuando el SII no publicó los campos.
+    return { sinTope: foliosDisp === null, maxAutor, foliosDisp };
+  }
+
   async solicitarCafExacto({ tipoDte, cantidad, permitirAnular = true }) {
     if (!this.cafSolicitor) {
       throw new Error('FolioService: CafSolicitor no inicializado (se requiere pfxPath y pfxPassword)');
@@ -525,7 +568,7 @@ class FolioService {
    */
   _anuladosPath(tipoDte) {
     const rutLimpio = String(this.rutEmisor || '').replace(/[^0-9kK]/g, '');
-    return path.join(this.debugDir, `folios-anulados-${rutLimpio}-${tipoDte}.json`);
+    return path.join(this.stateDir, `folios-anulados-${rutLimpio}-${tipoDte}.json`);
   }
 
   /** Set de claves "desde-hasta" que el SII ya reportó como anuladas. */
@@ -543,7 +586,7 @@ class FolioService {
 
   _guardarAnulados(tipoDte, set) {
     try {
-      fs.mkdirSync(this.debugDir, { recursive: true });
+      fs.mkdirSync(this.stateDir, { recursive: true });
       fs.writeFileSync(this._anuladosPath(tipoDte), JSON.stringify([...set]), 'utf8');
     } catch (err) {
       console.warn(`[FolioService] No se pudo persistir registro de anulados: ${err.message}`);
@@ -695,6 +738,11 @@ class FolioService {
         if (!yaConflicto) {
           const razon = this._parseAnulacionResult(bodyBulk).reason || 'error';
           rechazados.push({ folioDesde: iniA, folioHasta: finA, count, reason: razon });
+          // Mismo criterio que en el camino folio-a-folio: solo se recuerdan los
+          // rechazos definitivos, no los transitorios.
+          if (razon === 'ya-anulado' || razon === 'recepcionado') {
+            yaAnulados.add(`${iniA}-${finA}`);
+          }
           console.warn(`[FolioService] ✗ Rango ${iniA}-${finA} rechazado: ${razon}`);
           continue;
         }
@@ -724,6 +772,17 @@ class FolioService {
           } else {
             const razon = this._parseAnulacionResult(bs).reason || 'error';
             rechazados.push({ folioDesde: folio, folioHasta: folio, count: 1, reason: razon });
+            // Un folio ya anulado, o ya recepcionado en un DTE enviado, NO va a volver
+            // a ser anulable nunca. Recordarlo es lo único que evita reintentarlo en
+            // cada corrida. Faltaba justo acá, en el camino folio-a-folio, que es donde
+            // caen casi todos los rechazos porque el bulk conflictúa siempre: en una
+            // etapa medida el 11/08/2026 se registró 1 rango de 33 rechazos, y los 32
+            // restantes se reintentaron desde cero en la corrida siguiente.
+            // `error-red`, `error-sii-500` y `desconocido` quedan fuera a propósito:
+            // son transitorios y sí conviene reintentarlos.
+            if (razon === 'ya-anulado' || razon === 'recepcionado') {
+              yaAnulados.add(`${folio}-${folio}`);
+            }
           }
         }
         console.log('');

package/README.md

@@ -35,6 +35,8 @@ npm install @devlas/dte-sii
 - [Referencia de clases](#referencia-de-clases)
 - [Estructura de archivos](#estructura-de-archivos)
 - [Certificación SII](#certificación-sii)
+- [Depuración: captura de llamadas al SII](#depuración-captura-de-llamadas-al-sii)
+- [Ambientes](#ambientes)
 - [Licencia](#licencia)
 
 ---
@@ -884,6 +886,45 @@ const { CertFolioHelper } = require('@devlas/dte-sii')
 
 ---
 
+## Depuración: captura de llamadas al SII
+
+Cuando el SII rechaza algo, el motivo viene en el HTML o el XML que devuelve, y sin ese
+cuerpo guardado no hay forma de saber qué pasó. `utils/httpDebug.js` graba **todas** las
+llamadas HTTP de la librería.
+
+Está **apagado por defecto**: solo actúa si defines `SII_HTTP_DEBUG_DIR`. Sin esa variable
+el costo es una comparación por request, así que se puede dejar el código como está en
+producción.
+
+```bash
+SII_HTTP_DEBUG_DIR=/tmp/sii-debug node tu-script.js
+```
+
+Deja en ese directorio:
+
+```
+001-POST-DTEUpload-200.html          <- respuesta (cabecera con URL, status, ms, cliente)
+001-POST-DTEUpload-200-request.txt   <- cuerpo enviado, si supera 2000 caracteres
+index.jsonl                          <- una línea por llamada, para grep/jq
+```
+
+```bash
+# ¿Qué llamadas hizo y cuánto tardó cada una?
+jq -r '"\(.n) \(.method) \(.url) -> \(.status) \(.ms)ms [\(.cliente)]"' /tmp/sii-debug/index.jsonl
+```
+
+Cubre los cinco clientes HTTP de la librería, que son independientes entre sí: `SiiSession`,
+`SiiPortalAuth`, `EnviadorSII`, `CertRunner`/`BoletaCert` y `WsReclamo`.
+
+**Se redactan** `set-cookie`, `cookie`, `authorization` y `<RSASK>` (la llave privada RSA del
+CAF). Aun así, el resto del contenido son documentos tributarios: trata ese directorio como
+material sensible y púrgalo.
+
+Para dirigir la captura por etapa, redefine la variable antes de cada bloque: se lee en cada
+llamada, no una sola vez al cargar el módulo.
+
+---
+
 ## Ambientes
 
 | Ambiente | Constante | Descripción |
@@ -893,6 +934,27 @@ const { CertFolioHelper } = require('@devlas/dte-sii')
 
 > Siempre verifica la variable de entorno `SII_AMBIENTE` (o el parámetro `ambiente`) antes de ejecutar código DTE para evitar envíos accidentales a producción.
 
+### `TZ` es obligatoria
+
+Define `TZ=America/Santiago` en el proceso que use esta librería.
+
+`CertRunner` construye fechas con la hora local al declarar avance y libros. Con el proceso
+en UTC, entre las ~20:00 y medianoche de Chile genera la fecha del **día siguiente**: un
+envío registrado el día 11 se declara como del 12 y el SII responde *"FECHA NO CORRESPONDE
+AL ENVIO"*, dejando el flujo esperando algo que nunca va a llegar.
+
+> Para comprobarlo no sirve `date`: dentro de un contenedor sin `tzdata` **miente**. Usa
+> `node -e "console.log(new Date().toString())"`.
+
+### Acentos en el timbre (TED)
+
+El lector de PDF417 del SII pierde los bytes ≥ 128: `Cajón` llega como `Cajnn` y el timbre no
+valida. Por eso `DTE` normaliza a ASCII `RznSocRecep` y `NmbItem` **solo dentro del TED**,
+antes de firmarlo.
+
+El cuerpo del DTE conserva las tildes: el documento impreso y el XML que recibe el receptor
+se ven correctos. Si generas el PDF417 por tu cuenta, respeta esa misma regla.
+
 ---
 
 ## Licencia

package/SiiCertificacion.js

@@ -17,6 +17,7 @@
 
 const SiiSession = require('./SiiSession.js');
 const { STEPS, emitProgress } = require('./utils/progress');
+const { resolveArtifactDir } = require('./utils/paths');
 
 /** Decodifica entidades HTML latinas (el portal SII las usa en vez de UTF-8 crudo) y limpia
  * tags/whitespace, para poder aplicar regex de texto sobre las respuestas de forma confiable. */
@@ -83,11 +84,18 @@ class SiiCertificacion {
 
     this.rutEmpresa = options.rutEmpresa.replace(/\./g, '');
     this.dvEmpresa = options.dvEmpresa.toUpperCase();
-    
+
+    // Un solo lugar donde se decide dónde escribir. Antes había 7 call sites que
+    // recalculaban la ruta a mano, y no coincidían entre sí: cuatro usaban
+    // `../../debug/cert-v2` y tres `../../debug`, así que archivos de la misma
+    // operación quedaban repartidos en dos carpetas distintas.
+    this.debugDir = resolveArtifactDir(options.debugDir, options.debugDir ? '' : 'cert-v2');
+
     this.session = new SiiSession({
       pfxPath: options.pfxPath,
       pfxPassword: options.pfxPassword,
       ambiente: 'certificacion',
+      debugDir: this.debugDir,
     });
 
     // Reutilización de sesión: cargar desde archivo y guardar automáticamente tras cada login
@@ -632,7 +640,7 @@ class SiiCertificacion {
       {
         const fs = require('fs');
         const path = require('path');
-        const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug/cert-v2');
+        const debugDir = this.debugDir;
         if (!fs.existsSync(debugDir)) {
           fs.mkdirSync(debugDir, { recursive: true });
         }
@@ -789,7 +797,7 @@ class SiiCertificacion {
         // Guardar respuesta de pe_avance3 para debug
         const fs = require('fs');
         const path = require('path');
-        const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug');
+        const debugDir = this.debugDir;
         if (!fs.existsSync(debugDir)) {
           fs.mkdirSync(debugDir, { recursive: true });
         }
@@ -822,6 +830,38 @@ class SiiCertificacion {
         errorMsg = 'Respuesta inválida al declarar avance';
       }
 
+      // ── Datos inconsistentes: error DEFINITIVO, no "todavía no" ────────────
+      //
+      // El SII contesta 200 con una página normal que dice, entre los antecedentes del
+      // set, "FECHA NO CORRESPONDE AL ENVIO". No es un error de sesión ni de contenido,
+      // así que caía en el camino de éxito: la verificación posterior encontraba los
+      // campos vacíos, el bucle reintentaba 10 veces y después el polling seguía hasta
+      // agotar el timeout de la etapa. Minutos quemados esperando algo imposible, y sin
+      // que el mensaje real del SII llegara nunca al usuario.
+      //
+      // Esta ruta la comparten declarar avance, libros y simulación, así que detectarlo
+      // acá los cubre a los tres.
+      //
+      // La causa habitual es la zona horaria: los runners arman las fechas con
+      // `new Date().getDate()`, que usa la TZ del proceso. Corriendo en UTC, entre las
+      // 20:00 y las 00:00 de Chile ya es el día siguiente y se declara con la fecha de
+      // mañana. Por eso `TZ=America/Santiago` es obligatorio (ver CLAUDE.md).
+      const _inconsistencia = body.replace(/<[^>]*>/g, ' ')
+        .match(/((?:FECHA|RUT|FOLIO|NUMERO|N[UÚ]MERO)[^.<]{0,40}?NO\s+(?:CORRESPONDE|COINCIDE)[^.<]{0,40})/i);
+      if (_inconsistencia) {
+        const _detalle = _inconsistencia[1].replace(/\s+/g, ' ').trim();
+        return {
+          success: false,
+          datoInconsistente: true,
+          error: `El SII rechazó la declaración: ${_detalle}. Los datos declarados no coinciden con lo que el SII tiene registrado del envío; corrígelos y vuelve a declarar (esperar no lo resuelve).`,
+          status: declareResponse.status,
+          rawHtml: body,
+          formHtml,
+          setsDeclarados: Object.keys(sets),
+          formDataSent: formData,
+        };
+      }
+
       // Éxito si el form se envió sin errores de sesión/contenido.
       // El estado del envío (ERRORES O REPAROS / EN REVISION / REVISADO CONFORME)
       // NO determina el éxito de la declaración — eso se resuelve vía polling.
@@ -843,7 +883,7 @@ class SiiCertificacion {
       {
         const fs = require('fs');
         const path = require('path');
-        const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug/cert-v2');
+        const debugDir = this.debugDir;
         if (!fs.existsSync(debugDir)) fs.mkdirSync(debugDir, { recursive: true });
         fs.writeFileSync(path.join(debugDir, 'pe_avance3_response.html'), body, 'utf8');
 
@@ -868,7 +908,7 @@ class SiiCertificacion {
         {
           const fs = require('fs');
           const path = require('path');
-          const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug/cert-v2');
+          const debugDir = this.debugDir;
           if (!fs.existsSync(debugDir)) fs.mkdirSync(debugDir, { recursive: true });
           fs.writeFileSync(path.join(debugDir, 'pe_avance2_verify.html'), verifyHtml, 'utf8');
 
@@ -1027,7 +1067,7 @@ class SiiCertificacion {
       if (process.env.DEBUG_SII) {
         const fs = require('fs');
         const path = require('path');
-        const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug');
+        const debugDir = this.debugDir;
         if (!fs.existsSync(debugDir)) {
           fs.mkdirSync(debugDir, { recursive: true });
         }
@@ -1053,7 +1093,7 @@ class SiiCertificacion {
       if (process.env.DEBUG_SII) {
         const fs = require('fs');
         const path = require('path');
-        const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug');
+        const debugDir = this.debugDir;
         if (!fs.existsSync(debugDir)) {
           fs.mkdirSync(debugDir, { recursive: true });
         }
@@ -1201,7 +1241,7 @@ class SiiCertificacion {
     try {
       const fs = require('fs');
       const path = require('path');
-      const debugDir = process.env.SII_DEBUG_DIR || path.join(__dirname, '../../debug/cert-v2');
+      const debugDir = this.debugDir;
       if (!fs.existsSync(debugDir)) fs.mkdirSync(debugDir, { recursive: true });
       fs.writeFileSync(path.join(debugDir, filename), body || '', 'utf8');
     } catch (_e) { /* debug best-effort, no bloquear el flujo real */ }
@@ -1475,6 +1515,13 @@ class SiiCertificacion {
           esReparos:   upper.includes('REPAROS'),
           porRealizar: upper.includes('POR REALIZAR'),
           esAnulado:   upper.includes('ANULADO'),
+          // Estados que NO se resuelven esperando: el dato declarado no cuadra con lo
+          // que el SII tiene registrado, así que hay que corregirlo y volver a declarar.
+          // Sin esta categoría caían en el limbo (ni conforme, ni en revisión, ni
+          // rechazado) y el polling seguía hasta agotar el timeout de la etapa.
+          // Caso real: "FECHA NO CORRESPONDE AL ENVIO" cuando el proceso corre en UTC
+          // y declara con la fecha del día siguiente (ver TZ en docker-compose.yml).
+          datoInconsistente: /NO CORRESPONDE|NO COINCIDE|FECHA INVALIDA/i.test(upper),
         };
       }
     }
@@ -1540,7 +1587,9 @@ class SiiCertificacion {
         : result.estados;
 
       const todosConformes = Object.values(estadosRelevantes).every(e => e.esConforme);
-      const algunoRechazado = Object.values(estadosRelevantes).some(e => e.esRechazado);
+      // `datoInconsistente` cuenta como rechazo: seguir esperando no lo arregla.
+      const algunoRechazado = Object.values(estadosRelevantes)
+        .some(e => e.esRechazado || e.datoInconsistente);
 
       if (onProgress) {
         onProgress({ intento, maxIntentos, estado: 'resultado', estados: estadosRelevantes });
@@ -1559,7 +1608,7 @@ class SiiCertificacion {
         // sin decir cuál set ni con qué estado. Se nombran solo los rechazados
         // para no ahogar el dato entre los que sí pasaron.
         const detalle = Object.values(estadosRelevantes)
-          .filter(e => e.esRechazado)
+          .filter(e => e.esRechazado || e.datoInconsistente)
           .map(e => `${e.nombre}: ${e.estado}`)
           .join('; ');
         return {