@devlas/dte-sii 2.16.0 → 2.18.0

package/FolioService.js

@@ -142,6 +142,24 @@ class FolioService {
    * @returns {string|null} - Ruta al CAF o null
    */
   findLatestCaf(tipoDte) {
+    return this.listarCafs(tipoDte)[0] ?? null;
+  }
+
+  /**
+   * Todos los CAF de un tipo que hay en disco para este RUT y ambiente, del más
+   * reciente al más viejo.
+   *
+   * `findLatestCaf` devuelve solo el primero, que alcanza mientras un CAF cubra
+   * la cantidad completa. Cuando el SII raciona el timbraje eso deja de valer: un
+   * pedido de 4 folios puede haber quedado repartido en un CAF de 3 y otro de 1, y
+   * mirando solo el último se concluye "no alcanza" y se vuelven a pedir folios
+   * nuevos, dejando los anteriores timbrados y sin usar (que es justo lo que el SII
+   * cuenta en contra del cupo).
+   *
+   * @param {number} tipoDte
+   * @returns {string[]} rutas ordenadas por mtime descendente
+   */
+  listarCafs(tipoDte) {
     const matches = [];
     
     // Helper para buscar recursivamente
@@ -195,9 +213,8 @@ class FolioService {
     const canonicalDir = path.join(this.debugDir, 'caf', this.ambiente, this.rutEmisor, String(tipoDte));
     searchRecursive(canonicalDir);
 
-    if (!matches.length) return null;
     matches.sort((a, b) => b.mtime - a.mtime);
-    return matches[0].filePath;
+    return matches.map(m => m.filePath);
   }
 
   /**
@@ -345,7 +362,7 @@ class FolioService {
    *
    * @returns {Promise<{ ok: boolean, cafPath?: string, motivo?: string, disponibles?: number }>}
    */
-  async reobtenerCaf({ tipoDte, cantidad }) {
+  async reobtenerCaf({ tipoDte, cantidad, yaEmitido = null }) {
     if (!this.cafSolicitor) {
       return { ok: false, motivo: 'CafSolicitor no inicializado' };
     }
@@ -358,11 +375,30 @@ class FolioService {
       return { ok: false, motivo: err.message };
     }
 
-    const usables = rangos.filter(r => !r.anulado);
-    const anulados = rangos.length - usables.length;
+    // ⚠️ El listado del portal NO dice si un folio ya se emitió.
+    //
+    // `anulado` es lo único que marca, y eso deja pasar los folios que ya viajaron al SII
+    // dentro de un envío. Emitir de nuevo con ellos hace que el SII rechace cada documento
+    // con `(DTE-3-101) Folio para este Tipo de documento ya fue recibido en el SII`.
+    //
+    // Pasó de verdad (24/08/2026): la corrida descartó los CAF en disco por tener folios
+    // ya emitidos y, tres líneas después, la reobtención trajo esos mismos folios del
+    // portal y los usó. Los 7 documentos del tipo 61 fueron rechazados.
+    //
+    // Por eso el llamador puede pasar `yaEmitido`: es el mismo registro con el que descarta
+    // los CAF de disco (`CertRunner._rangoYaConsumido`), aplicado también acá. Sin ese dato
+    // la reobtención no puede saberlo, porque el SII no lo publica.
+    const emitidos = yaEmitido
+      ? rangos.filter(r => yaEmitido({ folioDesde: r.folioDesde, folioHasta: r.folioHasta }))
+      : [];
+    const emitidosSet = new Set(emitidos);
+    const usables = rangos.filter(r => !r.anulado && !emitidosSet.has(r));
+    const anulados = rangos.filter(r => r.anulado).length;
     console.log(
       `[FolioService] Tipo ${tipoDte}: ${rangos.length} rango(s) reobtenible(s), ` +
-      `${usables.length} usable(s)${anulados ? `, ${anulados} anulado(s) descartado(s)` : ''}`
+      `${usables.length} usable(s)` +
+      `${anulados ? `, ${anulados} anulado(s) descartado(s)` : ''}` +
+      `${emitidos.length ? `, ${emitidos.length} ya emitido(s) descartado(s)` : ''}`
     );
 
     const total = usables.reduce((n, r) => n + r.cantidad, 0);
@@ -456,7 +492,16 @@ class FolioService {
       result.errorCode === 'MAX_AUTOR_INSUFICIENTE' ||
       result.errorCode === 'TIMBRAJE_BLOQUEADO';
 
-    if (!result.success && recuperable && permitirAnular) {
+    // ⚠️ `!== 0` estricto. FOLIOS_DISP es el total de folios timbrados y sin utilizar,
+    // que es exactamente el conjunto anulable (el SII solo anula folios "que no han sido
+    // recepcionados"). Con 0 la anulación no puede prosperar y solo gasta requests: el
+    // 19/08/2026 una corrida intentó anular 4 folios ya emitidos, uno por uno, para
+    // terminar en `SIN_FOLIOS_ANULABLES` y un mensaje que culpaba a folios inexistentes.
+    // Con el timbraje BLOQUEADO el SII no publica el campo y queda `null`, y ese caso sí
+    // necesita intentarlo.
+    const hayQueAnular = result.foliosDisp !== 0;
+
+    if (!result.success && recuperable && permitirAnular && hayQueAnular) {
       console.warn(
         `[FolioService] Tipo ${tipoDte}: ${result.errorCode} — anulando folios sin utilizar y reintentando...`
       );
@@ -541,6 +586,96 @@ class FolioService {
     return { ok: true, cafPath: result.cafPath, otorgados, ...base };
   }
 
+  /**
+   * Cubre `cantidad` folios en varios timbrajes cuando el SII no autoriza tantos de
+   * una vez.
+   *
+   * `solicitarCafExacto` exige que UN CAF cubra todo y aborta si `MAX_AUTOR` no da.
+   * Eso es correcto para no agravar el racionamiento cuando hay folios sin usar
+   * (anular/reobtener sí destraba ese caso), pero deja sin salida el caso contrario:
+   * `FOLIOS_DISP=0` y `MAX_AUTOR` chico porque el SII raciona por historial. Ahí no
+   * hay nada que anular ni que reobtener, y la única vía es pedir de a tandas.
+   *
+   * Medido el 19/08/2026 (RUT 76543210-K, maullin): el set de simulación necesita 4
+   * folios de tipo 33, el SII autorizaba 3 con FOLIOS_DISP=0, y el tope siguió en 3
+   * durante 24 h. Esperar no lo mueve.
+   *
+   * Los sets aceptan varios CAF por tipo (`SetBase._tomarFolio` recorre la lista y
+   * salta al siguiente cuando se agota un rango), así que juntar tandas es
+   * transparente para quien genera los documentos.
+   *
+   * ⚠️ Cada tanda sube `FOLIOS_DISP` y puede bajar el `MAX_AUTOR` de la siguiente. Por
+   * eso se corta apenas una tanda no aporta folios nuevos, en vez de insistir: cada
+   * pedido inútil deja folios timbrados que después juegan en contra.
+   *
+   * @param {Object} params
+   * @param {number} params.tipoDte
+   * @param {number} params.cantidad - folios a cubrir en total
+   * @param {number} [params.maxTandas=4] - tope duro de viajes al portal
+   * @param {Object} [params.topeInicial] - resultado de `consultarTope` ya en mano, para
+   *   no repetir el sondeo de la primera tanda (cuesta ~3 requests al portal).
+   * @returns {Promise<{ ok: boolean, cafPaths: string[], otorgados: number,
+   *   maxAutor: number|null, foliosDisp: number|null, errorCode?: string, error?: string }>}
+   */
+  async solicitarCafPorTandas({ tipoDte, cantidad, maxTandas = 4, topeInicial = null }) {
+    if (!this.cafSolicitor) {
+      throw new Error('FolioService: CafSolicitor no inicializado (se requiere pfxPath y pfxPassword)');
+    }
+
+    const objetivo = Number(cantidad);
+    const cafPaths = [];
+    let cubiertos = 0;
+    let tope = null;
+
+    for (let tanda = 1; tanda <= maxTandas && cubiertos < objetivo; tanda++) {
+      tope = (tanda === 1 && topeInicial) ? topeInicial : await this.consultarTope({ tipoDte });
+      const faltan = objetivo - cubiertos;
+
+      // `sinTope` = el SII no publica MAX_AUTOR, o sea no está racionando este tipo:
+      // se pide todo lo que falta de una.
+      const pedir = tope.sinTope ? faltan : Math.min(tope.maxAutor ?? 0, faltan);
+      if (pedir <= 0) {
+        console.warn(
+          `[FolioService] Tipo ${tipoDte}: tanda ${tanda} sin cupo ` +
+          `(MAX_AUTOR=${tope.maxAutor}, FOLIOS_DISP=${tope.foliosDisp}) — se corta con ${cubiertos}/${objetivo}`
+        );
+        break;
+      }
+
+      console.log(
+        `[FolioService] Tipo ${tipoDte}: tanda ${tanda} pide ${pedir} folio(s) ` +
+        `(faltan ${faltan}; MAX_AUTOR=${tope.maxAutor ?? 'sin tope'}, FOLIOS_DISP=${tope.foliosDisp ?? 'sin dato'})`
+      );
+
+      const res = await this.cafSolicitor.solicitar({ tipoDte, cantidad: pedir, minCantidad: 1 });
+      const otorgados = res.success ? this._contarFoliosCaf(res.cafPath) : 0;
+      if (!otorgados) {
+        console.warn(
+          `[FolioService] Tipo ${tipoDte}: tanda ${tanda} no entregó folios ` +
+          `(${res.errorCode || 'sin código'}: ${res.error || 'sin detalle'}) — se corta`
+        );
+        break;
+      }
+
+      cafPaths.push(res.cafPath);
+      cubiertos += otorgados;
+      console.log(`[FolioService] Tipo ${tipoDte}: tanda ${tanda} entregó ${otorgados} folio(s) — ${cubiertos}/${objetivo}`);
+    }
+
+    const base = { maxAutor: tope?.maxAutor ?? null, foliosDisp: tope?.foliosDisp ?? null };
+    if (cubiertos < objetivo) {
+      return {
+        ok: false, cafPaths, otorgados: cubiertos, ...base,
+        errorCode: 'TOPE_SII_INSUFICIENTE',
+        error:
+          `El SII autorizó ${cubiertos} folio(s) de los ${objetivo} que necesita el tipo ${tipoDte}, ` +
+          `repartidos en ${cafPaths.length} timbraje(s). No hay folios sin utilizar que anular ni recuperar ` +
+          `(FOLIOS_DISP=${base.foliosDisp}): el tope lo fija el SII según el historial de timbraje y emisión.`,
+      };
+    }
+    return { ok: true, cafPaths, otorgados: cubiertos, ...base };
+  }
+
   /**
    * Consulta el estado de folios en el SII
    * @param {Object} params - Parámetros

package/cert/CertRunner.js

@@ -492,51 +492,116 @@ class CertRunner {
 
   _cafReusable(tipoDte, cantidad) {
     try {
-      const cafPath = this.folioService.findLatestCaf(tipoDte);
-      if (!cafPath || !fs.existsSync(cafPath)) return null;
-      // Ya se emitió con él: reusarlo repetiría folios y el SII rechaza el envío entero.
-      if (fs.existsSync(`${cafPath}.usado`)) {
-        console.log(` Tipo ${tipoDte}: el CAF previo ya se usó para emitir — se pedirá uno nuevo`);
-        return null;
-      }
-      const rango = this._rangoDelCaf(cafPath);
-      if (rango && this._rangoYaConsumido(tipoDte, rango.desde, rango.hasta)) {
-        console.log(` Tipo ${tipoDte}: los folios ${rango.desde}-${rango.hasta} ya se emitieron `
-          + '(otra copia del mismo CAF) — se pedirá uno nuevo');
-        return null;
-      }
+      // ⚠️ Se recorren TODOS los CAF del tipo, no solo el último.
+      //
+      // Cuando el SII raciona el timbraje, un pedido de 4 folios puede haber quedado
+      // repartido en un CAF de 3 y otro de 1 (ver FolioService.solicitarCafPorTandas).
+      // Mirando solo el último se concluía "no alcanza" y se pedían folios nuevos,
+      // dejando los anteriores timbrados y sin usar — que es exactamente lo que el SII
+      // cuenta en contra del cupo, o sea que el reintento empeoraba el problema que
+      // intentaba resolver.
+      // `listarCafs` es de 2.17.0. El fallback cubre a un `folioService` inyectado con la
+      // forma vieja: sin él, la excepción caería en el catch de abajo y el resultado sería
+      // "no hay CAF reusable", que dispara un timbraje nuevo teniendo folios en mano.
+      const rutas = typeof this.folioService.listarCafs === 'function'
+        ? this.folioService.listarCafs(tipoDte)
+        : [this.folioService.findLatestCaf(tipoDte)].filter(Boolean);
+      if (!rutas.length) return null;
 
       // Require local, igual que en _construirCafObjects (línea ~2110): `../index` cierra
       // el ciclo con este archivo, así que importarlo arriba deja CAF sin definir.
       const { CAF } = require('../index');
-      const caf = new CAF(fs.readFileSync(cafPath, 'utf8'));
-
-      // Doble chequeo del RUT, aunque findLatestCaf ya filtre. Firmar un timbre con el CAF
-      // de otro contribuyente hace que el SII rechace el envío ENTERO con `RFR - Rechazado
-      // por Error en Firma`, y el síntoma aparece etapas más adelante (la declaración de
-      // simulación se traba porque el envío tiene rechazos). Un fallo así de caro no puede
-      // depender de que una función de otro archivo siga filtrando bien.
-      const rutCaf = String(caf.da?.RE ?? '').replace(/\./g, '').trim().toUpperCase();
       const rutMio = String(this.config.emisor.rut).replace(/\./g, '').trim().toUpperCase();
-      if (rutCaf !== rutMio) {
-        console.warn(
-          `[CertRunner] CAF previo del tipo ${tipoDte} DESCARTADO: es del RUT ${rutCaf}, ` +
-          `no del emisor ${rutMio} (${cafPath})`
+
+      const candidatos = [];
+      const rangosVistos = new Set();
+      const descartes = [];
+
+      for (const cafPath of rutas) {
+        if (!fs.existsSync(cafPath)) continue;
+        // Ya se emitió con él: reusarlo repetiría folios y el SII rechaza el envío entero.
+        if (fs.existsSync(`${cafPath}.usado`)) {
+          descartes.push('ya se usó para emitir');
+          continue;
+        }
+
+        const rango = this._rangoDelCaf(cafPath);
+        if (rango && this._rangoYaConsumido(tipoDte, rango.desde, rango.hasta)) {
+          descartes.push(`folios ${rango.desde}-${rango.hasta} ya emitidos (otra copia del mismo CAF)`);
+          continue;
+        }
+
+        const caf = new CAF(fs.readFileSync(cafPath, 'utf8'));
+
+        // Doble chequeo del RUT, aunque listarCafs ya filtre. Firmar un timbre con el CAF
+        // de otro contribuyente hace que el SII rechace el envío ENTERO con `RFR - Rechazado
+        // por Error en Firma`, y el síntoma aparece etapas más adelante (la declaración de
+        // simulación se traba porque el envío tiene rechazos). Un fallo así de caro no puede
+        // depender de que una función de otro archivo siga filtrando bien.
+        const rutCaf = String(caf.da?.RE ?? '').replace(/\./g, '').trim().toUpperCase();
+        if (rutCaf !== rutMio) {
+          console.warn(
+            `[CertRunner] CAF previo del tipo ${tipoDte} DESCARTADO: es del RUT ${rutCaf}, ` +
+            `no del emisor ${rutMio} (${cafPath})`
+          );
+          continue;
+        }
+
+        const desde = caf.getFolioDesde();
+        const hasta = caf.getFolioHasta();
+        if (!Number.isFinite(desde) || !Number.isFinite(hasta)) continue;
+
+        // El MISMO CAF vive en dos árboles con el mismo contenido (ver _foliosUsadosPath),
+        // así que sin deduplicar por rango se contarían dos veces los mismos folios y el
+        // set se quedaría sin numeración a mitad de camino.
+        const clave = `${desde}-${hasta}`;
+        if (rangosVistos.has(clave)) continue;
+        rangosVistos.add(clave);
+
+        candidatos.push({ path: cafPath, desde, hasta });
+      }
+
+      if (!candidatos.length) {
+        const motivos = [...new Set(descartes)].join('; ');
+        console.log(
+          ` Tipo ${tipoDte}: sin CAF previo reusable${motivos ? ` (${motivos})` : ''} — se pedirá uno nuevo`
         );
         return null;
       }
 
-      const desde = caf.getFolioDesde();
-      const hasta = caf.getFolioHasta();
-      if (!Number.isFinite(desde) || !Number.isFinite(hasta)) return null;
-
-      // Cuántos folios de ese rango quedan libres según el contador de ESTA corrida.
-      // Si el helper ya consumió parte del rango, lo que queda es lo que sirve.
+      // Descuento del contador de ESTA corrida: si el helper ya reservó folios de este
+      // tipo, no vuelven a estar disponibles. Va sobre el total y no por CAF porque el
+      // contador es por tipo, no por rango.
       const yaUsados = this.folioHelper.usedFolios.get(tipoDte)?.size ?? 0;
-      const disponibles = (hasta - desde + 1) - yaUsados;
-      if (disponibles < cantidad) return null;
+      const disponibles = candidatos.reduce((n, c) => n + (c.hasta - c.desde + 1), 0) - yaUsados;
+      if (disponibles <= 0) return null;
+
+      // Se juntan desde el folio más bajo, y solo los que hagan falta.
+      //
+      // Los dos criterios importan. Del folio más bajo porque los documentos quedan
+      // numerados como si vinieran de un rango contiguo, y porque gastar primero lo más
+      // viejo es lo que baja FOLIOS_DISP más rápido. Y solo los necesarios porque
+      // `_marcarCafsConsumidos` marca como usados TODOS los CAF que reciba: incluir uno
+      // que el plan no llega a tocar quema esos folios sin haber emitido nada con ellos.
+      candidatos.sort((a, b) => a.desde - b.desde);
+      const elegidos = [];
+      let acumulado = 0;
+      for (const c of candidatos) {
+        if (acumulado >= cantidad) break;
+        elegidos.push(c);
+        acumulado += (c.hasta - c.desde + 1);
+      }
 
-      return { path: cafPath, desde, hasta };
+      return {
+        path: elegidos[0].path,
+        paths: elegidos.map(e => e.path),
+        desde: elegidos[0].desde,
+        hasta: elegidos[elegidos.length - 1].hasta,
+        /** Folios libres que aportan los CAF elegidos. */
+        total: Math.min(acumulado, disponibles),
+        /** false = hay folios en disco, pero no alcanzan para el plan. */
+        alcanza: disponibles >= cantidad,
+      };
     } catch (err) {
       // Un CAF ilegible no puede tumbar la corrida: se pide uno nuevo y listo.
       console.warn(`[CertRunner] No se pudo evaluar el CAF previo del tipo ${tipoDte}: ${err.message}`);
@@ -621,6 +686,36 @@ class CertRunner {
           );
           continue;
         }
+
+        // ── Cupo corto pero nada que limpiar ────────────────────────────────────
+        //
+        // FOLIOS_DISP es, textual en el formulario del SII, "considerando el timbraje
+        // histórico de documentos y de los documentos emitidos y/o anulados, la empresa
+        // posee folios disponibles o sin utilizar, por un total de N". O sea:
+        // timbrados - emitidos - anulados. Y anulable es exactamente ese conjunto: la
+        // página de anulación aclara que solo acepta "folios que no han sido
+        // recepcionados por el SII".
+        //
+        // Con N=0 la limpieza no puede anular nada, pero igual se intentaba, porque los
+        // candidatos NO salen de ahí: `consultarFolios` los saca del listado de
+        // TIMBRAJES (af_anular2), que lista los rangos autorizados sin decir si se usaron.
+        // Medido el 19/08/2026 (RUT 76543210-K): MAX_AUTOR=3 para 4 folios con
+        // FOLIOS_DISP=0, y la corrida gastó 43 de sus 70 requests intentando anular
+        // folios ya emitidos, uno por uno, para terminar con "0 anulados" y un error que
+        // además decía lo contrario de lo que pasaba ("el SII tiene bloqueado el
+        // timbraje", cuando el SII estaba autorizando 3).
+        //
+        // ⚠️ `=== 0` estricto, nunca `!foliosDisp`: con el timbraje BLOQUEADO el SII no
+        // publica el campo y queda `null` (ver FolioService.consultarTope), y ese caso
+        // sí necesita la limpieza, que es lo único que puede destrabarlo.
+        if (tope.foliosDisp === 0) {
+          console.log(
+            ` Tipo ${tipoDte}: sin limpieza previa — MAX_AUTOR=${tope.maxAutor} para ` +
+            `${necesarios} folio(s), pero FOLIOS_DISP=0: no hay folios sin utilizar que ` +
+            'anular ni recuperar. El tope lo fija el SII por historial, se pedirá en tandas.'
+          );
+          continue;
+        }
         // Un solo mensaje según el motivo: con el timbraje bloqueado el SII no publica
         // MAX_AUTOR ni FOLIOS_DISP, así que el texto de racionamiento saldría con `null`
         // en los dos números y confundiría a quien lea el log.
@@ -691,10 +786,13 @@ class CertRunner {
       // Reusarlos es seguro: los sets se envían recién cuando TODOS los CAF están en mano,
       // así que si el intento anterior falló, esos folios nunca se emitieron.
       const previo = this._cafReusable(Number(tipoDte), Number(cantidad));
-      if (previo) {
-        cafs[tipoDte] = previo.path;
+      if (previo?.alcanza) {
+        cafs[tipoDte] = previo.paths.length > 1 ? previo.paths : previo.path;
         emitProgress(STEPS.CAF_OK, { tipo: Number(tipoDte) });
-        console.log(` ✓ CAF tipo ${tipoDte} reusado del intento anterior (folios ${previo.desde}-${previo.hasta})`);
+        console.log(
+          ` ✓ CAF tipo ${tipoDte} reusado del intento anterior (folios ${previo.desde}-${previo.hasta}` +
+          `${previo.paths.length > 1 ? `, ${previo.paths.length} CAF` : ''})`
+        );
         continue;
       }
 
@@ -711,12 +809,34 @@ class CertRunner {
       // devuelve sin gastar cupo. Por eso va acá: después de reusar lo que hay en disco y
       // antes de `solicitarCafExacto`, que pide folios nuevos y, si falla, anula.
       //
-      // Solo se intenta con el timbraje bloqueado. Con cupo disponible pedir es más simple
-      // y no cuesta nada; la reobtención implica un request por rango para descartar los
-      // anulados, que el listado del SII no distingue.
-      if (this._topeConsultado?.[tipoDte]?.bloqueado) {
+      // ── Cuándo reobtener: solo si NO se pueden pedir folios nuevos ──────────
+      //
+      // La reobtención es el último recurso antes de anular, no un atajo para ahorrar
+      // cupo, porque tiene un riesgo que pedir folios nuevos no tiene: el listado del
+      // portal **no marca los folios ya emitidos**, y emitir de nuevo con uno hace que el
+      // SII rechace el documento con `(DTE-3-101) Folio ... ya fue recibido en el SII`.
+      //
+      // El filtro `yaEmitido` de abajo tapa lo que sabemos, pero no alcanza solo: el
+      // registro local puede estar incompleto (corridas viejas, disco efímero). Medido el
+      // 24/08/2026: de los folios reobtenidos del tipo 61, los rangos 1-3 y 10 sí estaban
+      // registrados, pero el 4-6 no, y el SII también lo tenía. Los 7 documentos del envío
+      // fueron rechazados.
+      //
+      // Por eso vuelve a exigirse que el cupo NO alcance: con timbraje bloqueado (el SII no
+      // publica MAX_AUTOR y queda `null`) o con un tope racionado por debajo de lo que hace
+      // falta. Con cupo holgado —el caso de esa corrida, MAX_AUTOR=19 para 7 folios— se
+      // piden folios nuevos, que es la vía sin riesgo.
+      const topeTipo = this._topeConsultado?.[tipoDte];
+      const cupoAlcanza = topeTipo?.sinTope === true
+        || (topeTipo?.maxAutor != null && topeTipo.maxAutor >= Number(cantidad));
+      if (topeTipo?.bloqueado || (!cupoAlcanza && (topeTipo?.foliosDisp ?? 0) > 0)) {
         const reob = await this.folioService.reobtenerCaf({
           tipoDte: Number(tipoDte), cantidad: Number(cantidad),
+          // El portal lista folios ya emitidos sin marcarlos: el único que lo sabe es este
+          // registro, el mismo con el que se descartan los CAF de disco unas líneas arriba.
+          // Sin pasarlo, la reobtención devuelve folios ya recibidos por el SII y todo el
+          // envío se rechaza documento por documento.
+          yaEmitido: (r) => this._rangoYaConsumido(Number(tipoDte), r.folioDesde, r.folioHasta),
         });
         if (reob.ok) {
           // Puede ser más de uno: el SII entrega los folios reobtenidos de a uno y cada
@@ -733,32 +853,82 @@ class CertRunner {
         console.warn(`[CertRunner] Tipo ${tipoDte}: reobtención no sirvió — ${reob.motivo}`);
       }
 
-      // solicitarCafExacto (no ConFallback): la simulación genera un plan fijo de
-      // documentos y muere si falta un folio, así que un CAF corto no sirve. El
-      // método aborta antes de emitir si el SII no autoriza lo suficiente, anula
-      // folios sin utilizar para destrabar el tope, y reintenta.
-      const res = await this.folioService.solicitarCafExacto({
-        tipoDte: Number(tipoDte),
-        cantidad: Number(cantidad),
-      });
+      // ── Cómo pedir: de una o en tandas ──────────────────────────────────────
+      //
+      // `solicitarCafExacto` exige que UN CAF cubra la cantidad y, si no, anula folios
+      // sin utilizar y reintenta. Eso es lo correcto cuando el cupo está corto POR esos
+      // folios (FOLIOS_DISP > 0) y cuando el timbraje está bloqueado.
+      //
+      // Con FOLIOS_DISP=0 no aplica: no hay nada que anular ni que reobtener, el tope lo
+      // fija el SII por historial y no se mueve esperando (medido: 24 h con el mismo
+      // MAX_AUTOR=3 para 4 folios, RUT 76543210-K). Ahí la única vía es juntar el rango
+      // en varios timbrajes, que los sets soportan de fábrica porque `_tomarFolio` acepta
+      // una lista de CAF y salta al siguiente cuando se agota un rango.
+      const racionadoPorHistorial =
+        topeTipo?.foliosDisp === 0 &&
+        topeTipo?.maxAutor != null &&
+        topeTipo.maxAutor < Number(cantidad);
+
+      // Folios que ya están en disco pero no alcanzaban solos. En el camino normal se
+      // ignoran (se pide un rango que cubra todo y estos quedan para después), pero acá
+      // son la mitad del asunto: si el intento anterior alcanzó a timbrar 3 de 4, pedir
+      // los 4 de nuevo desperdicia esos 3 y encima sube FOLIOS_DISP, que es lo que aprieta
+      // el tope. Se cuentan como cubiertos y al SII se le pide solo la diferencia.
+      const parciales = racionadoPorHistorial && previo && !previo.alcanza ? previo : null;
+      const faltante = Number(cantidad) - (parciales?.total ?? 0);
+      if (parciales) {
+        console.log(
+          ` Tipo ${tipoDte}: ${parciales.total} folio(s) ya timbrados en disco ` +
+          `(${parciales.desde}-${parciales.hasta}) — se pedirán ${faltante} al SII`
+        );
+      }
+
+      const res = racionadoPorHistorial
+        ? await this.folioService.solicitarCafPorTandas({
+            tipoDte: Number(tipoDte),
+            cantidad: faltante,
+            topeInicial: topeTipo,
+          })
+        : await this.folioService.solicitarCafExacto({
+            tipoDte: Number(tipoDte),
+            cantidad: Number(cantidad),
+          });
 
       if (!res.ok) {
         const detalle = [
           res.maxAutor != null ? `MAX_AUTOR=${res.maxAutor}` : null,
           res.foliosDisp != null ? `FOLIOS_DISP=${res.foliosDisp}` : null,
         ].filter(Boolean).join(', ');
+        // Dos causas con remedios opuestos. Antes las dos salían con el mismo texto, y en
+        // el caso de abajo el mensaje mandaba a anular folios que no existen: el 19/08/2026
+        // un comercio recibió "el SII tiene bloqueado el timbraje" mientras el SII le
+        // estaba autorizando 3 folios y no tenía ni uno sin utilizar.
+        const remedio = res.foliosDisp === 0
+          ? 'No hay folios sin utilizar que anular ni recuperar: el tope lo fija el SII ' +
+            'según el historial de timbraje y emisión de este tipo de documento.'
+          : 'El SII limita el timbraje cuando hay folios ya autorizados sin utilizar; ' +
+            'emite o anula documentos electrónicos de este tipo y reintenta.';
+        const cubiertos = res.otorgados + (parciales?.total ?? 0);
         throw new Error(
-          `Folios insuficientes para tipo ${tipoDte}: se requieren ${cantidad} y el SII ` +
-          `otorgó ${res.otorgados}${detalle ? ` (${detalle})` : ''}. ` +
-          `El SII limita el timbraje cuando hay folios ya autorizados sin utilizar; ` +
-          `emite o anula documentos electrónicos de este tipo y reintenta. ` +
+          `Folios insuficientes para tipo ${tipoDte}: se requieren ${cantidad} y hay ` +
+          `${cubiertos}${detalle ? ` (${detalle})` : ''}. ${remedio} ` +
           `[${res.errorCode}] ${res.error || ''}`.trim()
         );
       }
 
-      cafs[tipoDte] = res.cafPath;
+      // `solicitarCafPorTandas` devuelve varios; `solicitarCafExacto`, uno solo. Los
+      // parciales van primero: el set numera de menor a mayor y son los folios más viejos,
+      // así que gastarlos antes es también lo que baja FOLIOS_DISP más rápido.
+      const rutas = [
+        ...(parciales?.paths ?? []),
+        ...(res.cafPaths ?? (res.cafPath ? [res.cafPath] : [])),
+      ];
+      cafs[tipoDte] = rutas.length > 1 ? rutas : rutas[0];
       emitProgress(STEPS.CAF_OK, { tipo: Number(tipoDte) });
-      console.log(` ✓ CAF tipo ${tipoDte} (${res.otorgados} folios)`);
+      console.log(
+        ` ✓ CAF tipo ${tipoDte} (${res.otorgados + (parciales?.total ?? 0)} folios` +
+        `${rutas.length > 1 ? ` en ${rutas.length} CAF` : ''})`
+      );
     }
     
     return cafs;
@@ -961,6 +1131,7 @@ class CertRunner {
           await sleep(intervalo);
         } else {
           console.log(` [ERR] Contenido rechazado por SII (ENVIO CON ERRORES O REPAROS): ${(result.nombresConError || []).join(', ')}`);
+          await this._diagnosticarEnviosConError(sets, result.nombresConError, debugPrefix);
           break;
         }
       } else if (result.allRejected) {
@@ -986,6 +1157,144 @@ class CertRunner {
     return lastResult;
   }
 
+  /**
+   * Cuando el portal dice "ENVIO CON ERRORES O REPAROS", pregunta POR QUÉ.
+   *
+   * El portal de certificación solo da el titular: nombra el set y dice que tiene errores
+   * o reparos, sin un solo dato del documento culpable. El detalle vive en la consulta de
+   * estado del envío, que se hace con el TrackId — y ese TrackId lo tenemos en la mano
+   * desde que se subió el set.
+   *
+   * Hasta acá nadie preguntaba. Caso real (24/08/2026): una corrida quedó trabada con
+   * "SET BASICO, SET GUIA DE DESPACHO" con errores, y en las 105 respuestas HTTP de la
+   * etapa los TrackIds de esos sets aparecían solo en el `DTEUpload` que los creó y en el
+   * formulario que los declaró. Ni el comercio ni nosotros teníamos forma de saber qué
+   * corregir; la corrida siguió a libros, avance y simulación arrastrando el problema.
+   *
+   * ⚠️ Se consulta por SOAP (`QueryEstUp.jws`), NO por el REST de `consultarEstado()`: ese
+   * apunta a `apicert.sii.cl/recursos/v1/boleta.electronica.envio/`, que es el servicio de
+   * BOLETAS. Pasarle el TrackId de un set de facturas devuelve un resultado que no
+   * corresponde, y el diagnóstico saldría equivocado justo cuando más se necesita.
+   *
+   * La respuesta cruda queda en el debug dir y también en la captura HTTP de la librería.
+   *
+   * Nunca es fatal: es diagnóstico. Si la consulta falla, se deja constancia y se sigue.
+   *
+   * @private
+   * @param {Object} sets - El mismo mapa que se declaró: { setBasico: { trackId }, ... }
+   * @param {string[]} nombresConError - Nombres tal como los escribe el portal
+   * @param {string} debugPrefix - Prefijo de los archivos de debug de esta declaración
+   */
+  async _diagnosticarEnviosConError(sets, nombresConError, debugPrefix) {
+    // Espejo de la tabla `patterns` de SiiCertificacion.declararAvance: ahí se traduce de
+    // fila del portal a clave, acá de vuelta a la clave para encontrar el TrackId.
+    const NOMBRE_A_CLAVE = {
+      'SET BASICO': 'setBasico',
+      'SET GUIA DE DESPACHO': 'setGuiaDespacho',
+      'SET FACTURA EXENTA': 'setFacturaExenta',
+      'SET CASO GENERAL FACTURA COMPRA': 'setFacturaCompra',
+      'SET DE SIMULACION': 'setSimulacion',
+      'LIBRO DE VENTAS': 'libroVentas',
+      'LIBRO DE COMPRAS': 'libroCompras',
+      'LIBRO DE COMPRAS PARA EXENTOS': 'libroComprasExentos',
+      'LIBRO DE GUIAS': 'libroGuias',
+    };
+
+    const nombres = nombresConError || [];
+    if (!nombres.length) return;
+
+    console.log('\n──────────────────────────────────────────────────────────');
+    console.log(' DIAGNÓSTICO: consultando al SII por qué rechazó');
+    console.log('──────────────────────────────────────────────────────────');
+
+    let enviador = null;
+    try {
+      enviador = new EnviadorSII(this.certificado, this.ambiente);
+    } catch (err) {
+      console.warn(` [!] No se pudo crear el consultor de estado: ${err.message}`);
+      return;
+    }
+
+    const rut = this.config.emisor.rut;
+
+    // Se consultan TODOS los envíos declarados, no solo los marcados. El contraste es la
+    // mitad del diagnóstico: si el que falló dice RPR y los demás EPR, el problema es de
+    // ese documento; si todos vuelven RCT o RFR, es de la carátula o de la firma y el
+    // portal solo alcanzó a marcar los que ya procesó.
+    const conError = new Set(nombres.map(n => NOMBRE_A_CLAVE[n]).filter(Boolean));
+    const claves = [...new Set([...conError, ...Object.keys(sets || {})])];
+
+    for (const clave of claves) {
+      const nombre = Object.keys(NOMBRE_A_CLAVE).find(n => NOMBRE_A_CLAVE[n] === clave) || clave;
+      const marca = conError.has(clave) ? '[CON ERRORES]' : '[sin marca en el portal]';
+      const trackId = sets?.[clave]?.trackId;
+
+      if (!trackId) {
+        console.log(` [?] ${nombre} ${marca}: sin TrackId a mano — no se puede consultar el detalle`);
+        continue;
+      }
+
+      console.log(`\n ${nombre} ${marca} — TrackId ${trackId}`);
+
+      try {
+        const res = await enviador.consultarEstadoSoap(trackId, rut);
+
+        // Cruda y completa: el resumen de abajo es para leer en el momento, el archivo es
+        // para poder revisar después qué dijo exactamente el SII.
+        try {
+          fs.writeFileSync(
+            path.join(this.debugDir, `${debugPrefix}-estado-${clave}-${trackId}.xml`),
+            res?.xmlRaw || res?.respuesta || JSON.stringify(res, null, 2),
+            'utf8'
+          );
+        } catch { /* el debug no puede tumbar el diagnóstico */ }
+
+        if (!res || res.ok === false) {
+          console.log(`   sin estado: ${res?.error || 'sin detalle'}`);
+          continue;
+        }
+
+        console.log(`   estado=${res.estado ?? '?'}  ${res.mensaje || ''}`.trimEnd());
+        if (res.glosa) console.log(`   glosa: ${res.glosa}`);
+        this._imprimirDetalleEstado(res.xmlRaw);
+      } catch (err) {
+        console.log(`   falló la consulta de estado: ${err.message}`);
+      }
+    }
+    console.log('──────────────────────────────────────────────────────────\n');
+  }
+
+  /**
+   * Saca a la luz el detalle por documento que trae el XML de estado.
+   *
+   * `consultarEstadoSoap` parsea solo ESTADO, GLOSA y NUM_ATENCION, que es lo que necesita
+   * para decidir si seguir esperando. El detalle de los reparos viene en el mismo XML y se
+   * perdía: son las líneas que nombran el documento culpable.
+   *
+   * No se asume una estructura fija — el SII varía los nombres según el tipo de envío — así
+   * que se imprimen los campos que aparezcan y el XML completo queda en el archivo.
+   * @private
+   */
+  _imprimirDetalleEstado(xml) {
+    if (!xml) return;
+
+    // Cualquier bloque que hable de reparos, rechazos o detalle por documento.
+    const bloques = xml.match(/<(DETALLE_REP|REPARO|RECHAZO|DETALLE)[\s\S]{0,600}?<\/\1>/gi) || [];
+    for (const b of bloques.slice(0, 20)) {
+      const campos = [...b.matchAll(/<([A-Z_]+)>([^<]+)<\/\1>/gi)]
+        .map(m => `${m[1]}=${m[2].trim()}`)
+        .filter(t => !/^DETALLE(_REP)?=/.test(t));
+      if (campos.length) console.log(`     · ${campos.join(' | ')}`);
+    }
+    if (bloques.length > 20) console.log(`     · (+${bloques.length - 20} más — ver el XML en el debug)`);
+
+    // Contadores del envío: cuántos documentos aceptó, cuántos objetó. Aunque no haya
+    // bloques de detalle, esto ya dice si el problema es de uno o de todos.
+    const contadores = [...xml.matchAll(/<(NUM_DOC[A-Z_]*|ACEPTADOS|RECHAZADOS|REPAROS)>([^<]+)<\/\1>/gi)]
+      .map(m => `${m[1]}=${m[2].trim()}`);
+    if (contadores.length) console.log(`     · ${contadores.join(' | ')}`);
+  }
+
   /**
    * Declara avance de los sets ejecutados con reintentos automáticos
    * @param {Object} [resultadosExt] - Resultados externos (usa this.resultados si no se pasa)
@@ -2395,12 +2704,17 @@ class CertRunner {
     // Solicitar CAFs frescos
     const cafs = await this.solicitarCafs(cafRequired);
     
-    // Cargar objetos CAF
+    // Cargar objetos CAF. Un tipo puede traer VARIOS CAF cuando el SII racionó el
+    // timbraje y el rango se juntó en tandas: `Simulacion._tomarFolio` recorre la lista.
     const cafObjects = {};
     const { CAF } = require('../index');
-    for (const [tipo, cafPath] of Object.entries(cafs)) {
-      const cafXml = fs.readFileSync(cafPath, 'utf8');
-      cafObjects[tipo] = new CAF(cafXml);
+    for (const [tipo, ref] of Object.entries(cafs)) {
+      const rutas = Array.isArray(ref) ? ref : [ref];
+      const objetos = rutas.map(p => new CAF(fs.readFileSync(p, 'utf8')))
+        // De menor a mayor folio: los documentos del plan quedan numerados como si
+        // vinieran de un rango contiguo.
+        .sort((a, b) => a.getFolioDesde() - b.getFolioDesde());
+      cafObjects[tipo] = objetos.length > 1 ? objetos : objetos[0];
     }
 
     // Crear simulación

package/cert/Simulacion.js

@@ -38,10 +38,49 @@ class Simulacion {
     };
   }
 
+  /**
+   * Reserva el siguiente folio de un tipo, aceptando UNO o VARIOS CAF.
+   *
+   * El SII raciona el timbraje: cuando el cupo por solicitud es menor a lo que pide el
+   * plan, los folios llegan repartidos en varios CAF (ver
+   * `FolioService.solicitarCafPorTandas`). Cada CAF firma con su propia llave, así que
+   * hay que devolver también CUÁL se usó, para timbrar el documento con ese y no con el
+   * primero de la lista.
+   *
+   * Los sets ya funcionaban así (`SetBase._tomarFolio`); la simulación no, porque recibía
+   * un objeto CAF por tipo. Ese era el único punto que impedía repartir un rango.
+   *
+   * @private
+   * @returns {{ caf: Object, folio: number }}
+   */
+  _tomarFolio(cafRef, tipoDte, folioHelper) {
+    const lista = (Array.isArray(cafRef) ? cafRef : [cafRef]).filter(Boolean);
+    if (!lista.length) {
+      throw new Error(`No hay CAF para tipo ${tipoDte}`);
+    }
+
+    let ultimoError = null;
+    for (const caf of lista) {
+      try {
+        const folio = folioHelper.reserveNextFolio({
+          tipoDte,
+          folioDesde: caf.getFolioDesde(),
+          folioHasta: caf.getFolioHasta(),
+        });
+        return { caf, folio };
+      } catch (err) {
+        // Rango agotado: se pasa al CAF siguiente. Cualquier otro error sí es fatal.
+        if (!/No hay más folios disponibles/.test(err.message)) throw err;
+        ultimoError = err;
+      }
+    }
+    throw ultimoError;
+  }
+
   /**
    * Genera el EnvioDTE de simulación a partir de las estructuras
    * @param {Object} estructuras - Estructuras del set de pruebas
-   * @param {Object} cafs - { tipoDte: CAF } pre-cargados
+   * @param {Object} cafs - { tipoDte: CAF | CAF[] } pre-cargados
    * @param {Object} folioHelper - Helper para gestionar folios
    * @param {Object} [options] - Opciones
    * @param {string} [options.fechaEmision] - Fecha de emisión (default: hoy)
@@ -61,17 +100,7 @@ class Simulacion {
 
     for (const doc of plan) {
       const tipoDte = Number(doc.tipoDte || 33);
-      const caf = cafs[tipoDte];
-      if (!caf) {
-        throw new Error(`No hay CAF para tipo ${tipoDte}`);
-      }
-
-      // Obtener folio desde el CAF
-      const folio = folioHelper.reserveNextFolio({
-        tipoDte,
-        folioDesde: caf.getFolioDesde(),
-        folioHasta: caf.getFolioHasta(),
-      });
+      const { caf, folio } = this._tomarFolio(cafs[tipoDte], tipoDte, folioHelper);
       const base = doc.referenciaCaso ? docRefs[doc.referenciaCaso] : null;
 
       // Resolver items

package/dte-sii.d.ts

@@ -652,7 +652,54 @@ export class FolioService {
    * el portal reporta como anulados (los documentos emitidos con esos folios se
    * rechazan).
    */
-  reobtenerCaf(options: { tipoDte: number; cantidad: number }): Promise<ReobtenerCafResult | null>;
+  reobtenerCaf(options: {
+    tipoDte: number;
+    cantidad: number;
+    /**
+     * Descarta los rangos que ya se emitieron. El listado del portal solo marca los
+     * ANULADOS, así que sin esto la reobtención devuelve folios que el SII ya recibió y
+     * cada documento vuelve rechazado con `DTE-3-101`.
+     */
+    yaEmitido?: (rango: { folioDesde: number; folioHasta: number }) => boolean;
+  }): Promise<ReobtenerCafResult | null>;
+  /** El CAF más reciente de un tipo para este RUT y ambiente, o null. */
+  findLatestCaf(tipoDte: number): string | null;
+  /**
+   * Todos los CAF de un tipo en disco, del más reciente al más viejo.
+   *
+   * Hace falta cuando el SII raciona el timbraje y un rango queda repartido en
+   * varios CAF: mirando solo el último se concluye "no alcanza" y se piden folios
+   * nuevos, dejando los anteriores timbrados y sin usar.
+   */
+  listarCafs(tipoDte: number): string[];
+  /**
+   * Cubre `cantidad` folios en varios timbrajes cuando el SII no autoriza tantos de
+   * una vez.
+   *
+   * Es para el caso `FOLIOS_DISP = 0` con `MAX_AUTOR` corto: no hay folios sin usar
+   * que anular ni recuperar, el tope lo fija el SII por historial y no se mueve
+   * esperando. Se corta apenas una tanda no aporta folios nuevos, porque cada
+   * timbraje parcial sube `FOLIOS_DISP` y puede bajar el tope siguiente.
+   */
+  solicitarCafPorTandas(options: {
+    tipoDte: number;
+    cantidad: number;
+    maxTandas?: number;
+    topeInicial?: FolioTope | null;
+  }): Promise<SolicitarCafTandasResult>;
+}
+
+export interface SolicitarCafTandasResult {
+  ok: boolean;
+  /** CAF obtenidos, uno por tanda. Los sets y la simulación aceptan la lista completa. */
+  cafPaths: string[];
+  /** Folios cubiertos entre todas las tandas. */
+  otorgados: number;
+  maxAutor: number | null;
+  foliosDisp: number | null;
+  /** `TOPE_SII_INSUFICIENTE` cuando el SII no llegó a cubrir la cantidad pedida. */
+  errorCode?: string;
+  error?: string;
 }
 
 export interface FolioRegistryOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devlas/dte-sii",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "description": "Facturación y boletas electrónicas para el SII de Chile. Genera, timbra, firma y envía DTEs, libros electrónicos y automatiza la certificación.",
   "main": "index.js",
   "types": "dte-sii.d.ts",