@devlas/dte-sii 2.12.26 → 2.13.1

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
@@ -235,7 +238,7 @@ class CafSolicitor {
   }
 
   static esBloqueoTimbraje(html) {
-    return /NO\s+(SE\s+)?AUTORIZA\s+TIMBRAJE/i.test(String(html || ''));
+    return /NO\s+(SE\s+)?AUTORIZA\s+TIMBRAJE/i.test(CafSolicitor.textoVisible(html, 4000));
   }
 
   /**
@@ -251,7 +254,8 @@ class CafSolicitor {
    * no confirmado por el mensaje) de un fallo real desconocido.
    */
   static esNoAutorizadoIngresarOpcion(html) {
-    return /no\s+est.\s+autorizado\s+para\s+ingresar\s+a\s+esta\s+opci.n/i.test(String(html || ''));
+    return /no\s+est.{0,8}\s*autorizado\s+para\s+ingresar\s+a\s+esta\s+opci.{0,8}n/i
+      .test(CafSolicitor.textoVisible(html, 4000));
   }
 
   /**
@@ -264,9 +268,91 @@ class CafSolicitor {
    * es reenviar los permisos del usuario (Paso 5 de la inscripción) EN EL MISMO
    * AMBIENTE donde se está pidiendo el folio.
    */
+  /**
+   * El SII exige hacer el trámite PRESENCIALMENTE en la oficina.
+   *
+   * Sale al intentar inscribir a la empresa como facturador electrónico, incluso en el
+   * sistema gratuito: "deberá presentarse en la oficina del SII correspondiente a su
+   * domicilio y solicitar la asistencia de un funcionario". Suele deberse a observaciones
+   * en el RUT, domicilio sin verificar o anotaciones del contribuyente.
+   *
+   * Se detecta porque es un callejón sin salida para el software: mientras esté, la
+   * empresa no puede inscribirse, no queda autorizada en palena, no puede enrolar
+   * usuarios ni timbrar. Sin este mensaje el usuario ve un error genérico y vuelve a
+   * intentar sin saber que lo único que corresponde es ir al SII.
+   *
+   * Caso real (12/08/2026, RUT 78441936-3): Verificación de Actividades aprobada,
+   * usuario enrolado en maullin y certificación de boleta enviada — y aun así palena
+   * rechazaba todo, porque la inscripción por internet estaba bloqueada de origen.
+   */
+  static esRequiereTramitePresencial(html) {
+    const t = CafSolicitor.textoVisible(html, 4000);
+    return /deber.{0,8}\s*presentarse\s+en\s+la\s+oficina\s+del\s+SII/i.test(t)
+      || (/no\s+cumple\s+con\s+los\s+requisitos/i.test(t)
+          && /asistencia\s+de\s+un\s+funcionario/i.test(t));
+  }
+
+  /**
+   * "la empresa no está autorizada para operar en esta modalidad"
+   *
+   * Distinto de `esUsuarioSinPermiso`: ahí el sujeto es el USUARIO del certificado, acá
+   * es la EMPRESA. El SII lo devuelve en palena cuando el contribuyente todavía no fue
+   * autorizado como emisor electrónico en producción — no hay nada que arreglar del lado
+   * del enrolamiento, porque el portal ni siquiera deja abrir la mantención de usuarios.
+   *
+   * Caso real (12/08/2026, RUT 78441936-3): el flujo de enrolamiento siguió de largo con
+   * páginas vacías —sin formulario ni hidden `key`— hasta reventar con un 500 en
+   * `eu_graba_usuario`. El 500 era el síntoma; esta frase, en el PRIMER paso, la causa.
+   */
+  static esEmpresaNoAutorizada(html) {
+    return /(la\s+)?empresa\s+no\s+est.{0,8}\s*autorizada\s+para\s+operar/i
+      .test(CafSolicitor.textoVisible(html, 4000));
+  }
+
+  /**
+   * ¿Este HTML es un rechazo que hace inútil seguir el flujo?
+   *
+   * ⚠️ Los rechazos del SII NO llegan siempre en la última respuesta. Este caso real
+   * (12/08/2026, RUT 78441936-3, tipo 39 en palena) llegó en el PASO 2
+   * (`of_solicita_folios_dcto`), donde solo se miraba `esBloqueoTimbraje`. El flujo
+   * siguió de largo y terminó devolviendo el genérico `UNKNOWN: No se obtuvo CAF`,
+   * escondiendo un mensaje que la librería ya sabía interpretar desde julio.
+   *
+   * Por eso el chequeo es UNO SOLO y se aplica en TODOS los pasos: agregar un patrón
+   * nuevo no debe obligar a acordarse de replicarlo en cada punto del flujo.
+   */
+  static esRechazoDuro(html) {
+    const h = String(html || '');
+    return CafSolicitor.esBloqueoTimbraje(h)
+      || CafSolicitor.esRequiereTramitePresencial(h)
+      || CafSolicitor.esEmpresaNoAutorizada(h)
+      || CafSolicitor.esNoAutorizadoIngresarOpcion(h)
+      || CafSolicitor.esUsuarioSinPermiso(h)
+      || /no\s+registra\s+Verificaci.{0,8}n\s+de\s+Actividades/i.test(CafSolicitor.textoVisible(h, 4000));
+  }
+
+  /**
+   * Texto legible de una página del SII, sin markup.
+   *
+   * Para que un rechazo desconocido no se pierda: sin esto, el motivo real queda solo
+   * en el HTML —que en producción no se guarda— y el operador ve `UNKNOWN` sin más.
+   */
+  static textoVisible(html, max = 400) {
+    return String(html || '')
+      .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+      .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+      .replace(/<[^>]+>/g, ' ')
+      .replace(/&nbsp;/gi, ' ').replace(/&aacute;/gi, 'a').replace(/&eacute;/gi, 'e')
+      .replace(/&iacute;/gi, 'i').replace(/&oacute;/gi, 'o').replace(/&uacute;/gi, 'u')
+      .replace(/&ntilde;/gi, 'n').replace(/&[a-z]+;/gi, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, max);
+  }
+
   static esUsuarioSinPermiso(html) {
-    return /no\s+tiene\s+permiso\s+en\s+(la\s+)?empresa|usuario\s+no\s+autorizado\s+para\s+(la\s+)?empresa|no\s+est.\s+autorizado\s+para\s+operar\s+en\s+la\s+empresa/i
-      .test(String(html || ''));
+    return /no\s+tiene\s+permiso\s+en\s+(la\s+)?empresa|usuario\s+no\s+autorizado\s+para\s+(la\s+)?empresa|no\s+est.{0,8}\s*autorizado\s+para\s+operar\s+en\s+la\s+empresa/i
+      .test(CafSolicitor.textoVisible(html, 4000));
   }
 
   /**
@@ -280,7 +366,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 +375,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();
@@ -395,6 +485,22 @@ class CafSolicitor {
         return { success: false, errorCode: 'TIMBRAJE_BLOQUEADO', error: 'SII: No se autoriza timbraje. Folios acumulados excesivos o situaciones tributarias pendientes. Revisa el portal SII → Factura Electrónica → Solicitud de Timbraje.' };
       }
 
+      if (response.body && CafSolicitor.esRequiereTramitePresencial(response.body)) {
+        return {
+          success: false,
+          errorCode: 'REQUIERE_TRAMITE_PRESENCIAL',
+          error: 'El SII exige completar la inscripción en Factura Electrónica de forma presencial: el representante legal debe ir con su cédula a la oficina del SII del domicilio de la empresa. Hasta entonces no se pueden obtener folios. Suele deberse a observaciones en el RUT o al domicilio sin verificar.',
+        };
+      }
+
+      if (response.body && CafSolicitor.esEmpresaNoAutorizada(response.body)) {
+        return {
+          success: false,
+          errorCode: 'EMPRESA_NO_AUTORIZADA',
+          error: `SII (${this.ambiente}): la EMPRESA no está autorizada para operar como emisor electrónico en este ambiente. No es un problema del usuario ni de sus permisos: hasta que el SII autorice al contribuyente, el portal no permite ni enrolar usuarios ni solicitar folios.`,
+        };
+      }
+
       if (response.body && CafSolicitor.esNoAutorizadoIngresarOpcion(response.body)) {
         return {
           success: false,
@@ -517,7 +623,14 @@ class CafSolicitor {
         return { success: false, errorCode: 'SESSION_EXPIRED', error: 'Sesión SII inválida — registro limpiado, el próximo intento reautenticará.' };
       }
 
-      return { success: false, errorCode: 'UNKNOWN', error: 'No se obtuvo CAF en la respuesta' };
+      // Se adjunta lo que dijo el SII: un `UNKNOWN` sin el motivo obliga a reproducir
+      // el fallo con el debug encendido, que es justo lo que no se puede hacer en
+      // producción cuando el problema es de un cliente concreto.
+      return {
+        success: false,
+        errorCode: 'UNKNOWN',
+        error: `No se obtuvo CAF en la respuesta. El SII respondió: "${CafSolicitor.textoVisible(response.body)}"`,
+      };
 
     } catch (err) {
       const msg = err.message || '';
@@ -550,8 +663,8 @@ class CafSolicitor {
 
     // Defensivo: mismo rechazo por Verificación de Actividades puede aparecer si el SII
     // lo entrega recién en un paso posterior en vez del response inicial de solicitar().
-    if (currentHtml.includes('no registra Verificacion de Actividades')) {
-      return response; // solicitar() detectará el rechazo en response.body
+    if (CafSolicitor.esRechazoDuro(currentHtml)) {
+      return response; // solicitar() traduce el motivo desde response.body
     }
 
     const realFormAction = SiiSession.extractFormAction(currentHtml);
@@ -585,8 +698,8 @@ class CafSolicitor {
 
       // Rechazo duro antes del check de COD_DOCTO: la página de rechazo también contiene
       // "COD_DOCTO" en su JavaScript, lo que causaría un POST innecesario con datos vacíos.
-      if (CafSolicitor.esBloqueoTimbraje(currentHtml)) {
-        return response; // solicitar() detectará el bloqueo en response.body
+      if (CafSolicitor.esRechazoDuro(currentHtml)) {
+        return response; // solicitar() traduce el motivo desde response.body
       }
 
       // Selección de tipo de documento
@@ -608,8 +721,8 @@ class CafSolicitor {
         currentHtml = response.body || '';
         this._saveDebug(debugDir, 'select.html', currentHtml);
 
-        if (CafSolicitor.esBloqueoTimbraje(currentHtml)) {
-          return response; // solicitar() detectará el bloqueo en response.body
+        if (CafSolicitor.esRechazoDuro(currentHtml)) {
+          return response; // solicitar() traduce el motivo desde response.body
         }
       }
 
@@ -627,8 +740,8 @@ class CafSolicitor {
   async _processStep3(response, rut, dv, tipoDte, cantidad, debugDir) {
     let currentHtml = response.body || '';
 
-    if (currentHtml.includes('no registra Verificacion de Actividades')) {
-      return response; // solicitar() detectará el rechazo en response.body
+    if (CafSolicitor.esRechazoDuro(currentHtml)) {
+      return response; // solicitar() traduce el motivo desde response.body
     }
 
     const formAction3 = SiiSession.extractFormAction(currentHtml) || '/cvc_cgi/dte/of_confirma_folio';
@@ -654,6 +767,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