Ir al contenido

Folios y CAF por API

Cada documento tributario que emite un emisor DTE consume un folio, y los folios los autoriza el SII en archivos llamados CAF (un rango de folios por tipo de documento). Esta ficha deja que un agente haga por API lo que la persona hace en el panel, en DTE → Folios: subir un CAF, pedir folios nuevos al SII, ver cuántos quedan, anular los que no se van a usar, seguir el reporte de esas anulaciones al SII y dejar que la plataforma pida folios sola cuando se acaban.

Son catorce operaciones, con las mismas reglas y los mismos mensajes de rechazo que el panel. La respuesta nunca trae el XML del CAF ni su clave privada, tampoco la que sube tu integración: el archivo se valida y se guarda del lado de REDCUMBRE.

Qué hace cada una:

ParaOperación
Subir el CAF que entregó el SIIsubirCaf
Ver los CAF del emisor, con su rango, su estado y los folios usadoslistarCafs
Ver folios totales, usados y disponibles por tipoobtenerEstadisticasDeCafs
Ver qué tipos de documento tiene autorizados el emisorconsultarDocumentosAutorizados
Ver la disponibilidad de folios de un tipoconsultarFoliosEnSii
Ver para qué tipos se pueden pedir folioslistarTiposDeFoliosDisponibles
Pedir folios nuevos al SIIsolicitarFolios
Anular todos los folios sin usar de un CAFanularCaf
Anular un rango de foliosanularFoliosDeCaf
Ver el historial de anulaciones y el detalle de unalistarAnulacionesDeFolios, obtenerAnulacionDeFolios
Reintentar el reporte de una anulación que fallóreintentarReporteDeAnulacion
Leer y cambiar la solicitud automática de foliosobtenerSolicitudAutomaticaDeFolios, actualizarSolicitudAutomaticaDeFolios

Lo que esta ficha no hace: no inscribe el emisor (eso es la tokenización, en Emisores y tokenización) ni emite documentos (eso es Documentos tributarios). Los folios sólo se piden y se anulan para un emisor que ya existe.

  • Un emisor DTE y su emisorDteId. Sale de redcumbre api listarEmisoresDte, y el RUT del emisor lo necesitas para confirmar los actos.
  • Una llave con acceso a folios. La llave del proyecto que instala redcumbre init es FULL-API y alcanza. Para una llave más angosta, redcumbre api describir solicitarFolios muestra el rol que declara la operación.
  • El archivo de la llave en el proyecto, como en Modo de prueba y producción. No lo leas, no lo imprimas ni le pidas a la persona que pegue el secreto en el chat.
  • Paginación, errores y límites: Reglas comunes.

Cuatro operaciones hacen algo ante el SII o consumen folios para siempre: solicitarFolios, anularCaf, anularFoliosDeCaf y reintentarReporteDeAnulacion. Con una llave de API las cuatro exigen, en el cuerpo:

  • idempotencyKey, la clave de repetición. Si el pedido se corta y lo repites con la misma clave y el mismo cuerpo, recibes la misma respuesta sin que el acto se repita: no se piden folios dos veces ni se anula dos veces. Sin clave, responde 400 y no se ejecuta. Usa una clave estable de tu sistema, no una nueva por intento: una clave nueva es un acto nuevo. Con el CLI puedes pasarla con --clave; si no la pasas, el CLI genera una y la imprime: guárdala para reintentar.
  • confirmacionRut, el RUT del emisor escrito de nuevo. Es la confirmación de que el agente sabe sobre qué emisor actúa; si no coincide con el del emisor, el acto no se ejecuta. Con los comandos de redcumbre folios es la bandera --rut. El panel no lo pide, porque ahí una persona ve el emisor en pantalla.

Con una llave de prueba, los folios trabajan sobre una copia de prueba del emisor, con un CAF simulado, y nunca tocan los CAF reales ni llaman al SII. Un emisor de producción responde, para una llave de prueba, como inexistente.

  • subirCaf: el XML se valida como en producción, pero lo que se guarda es un CAF simulado con el mismo tipo, rango y fecha. Valida el traslape contra los CAF de prueba y responde 409 si choca, incluido el CAF simulado de prueba, que cubre los folios del 1 al 1.000.000. Para ensayar la subida, usa un CAF cuyo rango no esté dentro de ese.
  • solicitarFolios: entrega el CAF simulado en vez de pedirlo al SII, con la misma forma de respuesta que en producción. No usa cantidad: la mandas igual, porque el cuerpo se valida como siempre, pero no cambia el resultado.
  • anularCaf y anularFoliosDeCaf: crean las anulaciones con estado NO_APLICA y no reportan nada al SII.
  • reintentarReporteDeAnulacion: una anulación NO_APLICA se devuelve tal cual.
  • Las lecturas (listarCafs, estadísticas, documentos autorizados, consulta de folios, tipos disponibles, anulaciones) se calculan sólo sobre los CAF de prueba; una anulación de un CAF de producción responde como inexistente.
  • actualizarSolicitudAutomaticaDeFolios guarda la configuración en el emisor de prueba y no pide folios.

Eso confirma que la llave, el rol y el cuerpo son correctos; no confirma que haya folios reales. Ninguna de las catorce operaciones se cobra.

Cada paso usa el subcomando de redcumbre folios: las banderas arman el pedido, y los bloques JSON de abajo muestran el cuerpo que viaja. Todos trabajan con la llave de prueba; para producción agrega --produccion --confirmar <slug-de-la-empresa>, y con --ensayo ves la petición sin hacerla. La alternativa genérica es redcumbre api <operationId>.

Ventana de terminal
redcumbre buscar "folios CAF"
redcumbre api describir solicitarFolios

Resultado esperado: las operaciones de esta ficha, con su método, su ruta y los campos del cuerpo.

Ventana de terminal
redcumbre folios estadisticas --emisor <id-del-emisor>
redcumbre folios listar --emisor <id-del-emisor>

Resultado esperado: los folios totales, usados y disponibles por tipo de documento y ambiente, y la lista paginada de los CAF con su rango, su estado y los folios usados. folios listar admite --tipo-dte (39 o 41), --estado, --limite y --desde (con --todas recorre todas las páginas). Si la lista viene vacía en prueba, el emisor de prueba aún no tiene CAF.

Ventana de terminal
redcumbre folios tipos-disponibles --emisor <id-del-emisor>
redcumbre folios consultar --emisor <id-del-emisor> --tipo-dte 33
redcumbre folios documentos-autorizados --emisor <id-del-emisor>

Resultado esperado: la lista (posiblemente vacía) de los tipos para los que el emisor puede pedir folios, y la disponibilidad de folios de un tipo, con la forma de factura o de boleta según el tipo. consultarDocumentosAutorizados entrega los tipos que el emisor tiene autorizados, filtrados por los servicios DTE de la empresa. Una lista vacía de tipos disponibles es una respuesta válida, no un error.

{
"emisorDteId": "cm1abc123def456",
"tipoDte": 33,
"cantidad": 10,
"idempotencyKey": "folios-factura-2026-11",
"confirmacionRut": "76123456-0"
}
Ventana de terminal
redcumbre folios solicitar --emisor <id-del-emisor> --tipo-dte 33 --cantidad 10 --rut 76123456-0 --clave folios-factura-2026-11

Resultado esperado: el CAF guardado, con su tipo, su rango y su estado, sin el XML ni la clave privada. cantidad va de 1 a 10.000. Con una llave de prueba la respuesta trae el CAF simulado. Si repites el comando con la misma clave y el mismo cuerpo, recibes la misma respuesta sin pedir folios de nuevo.

Ventana de terminal
redcumbre folios subir --emisor <id-del-emisor> --archivo caf.xml

Resultado esperado: el CAF registrado, sin el XML ni la clave privada. El XML viaja como formulario (campo archivo) junto con emisorDteId. Un XML inválido o inconsistente responde 400, y un rango que se traslapa con un CAF existente responde 409 (en prueba, contra los CAF de prueba, el simulado incluido).

Todos los folios sin usar de un CAF:

{
"idempotencyKey": "anular-caf-33-2026-11",
"confirmacionRut": "76123456-0"
}

Un rango de folios no consumidos:

{
"folioDesde": 100,
"folioHasta": 200,
"motivo": "NO_UTILIZADO",
"idempotencyKey": "anular-100-200-2026-11",
"confirmacionRut": "76123456-0"
}
Ventana de terminal
redcumbre folios anular <id-del-caf> --rut 76123456-0 --clave anular-caf-33-2026-11
redcumbre folios anular-folios <id-del-caf> --folio-desde 100 --folio-hasta 200 --motivo NO_UTILIZADO --rut 76123456-0 --clave anular-100-200-2026-11

Resultado esperado: la anulación creada, con el estado de su reporte al SII. folioHasta puede ser igual a folioDesde para anular un solo folio. Una anulación no se deshace: antes de mandarla confirma el rango con listarCafs. Los motivos son NO_UTILIZADO, EXPIRADO, ERROR_IRRECUPERABLE y DECOMMISSION_CAF.

7. Sigue las anulaciones y reintenta el reporte

Sección titulada «7. Sigue las anulaciones y reintenta el reporte»
Ventana de terminal
redcumbre folios anulaciones listar --emisor <id-del-emisor>
redcumbre folios anulaciones ver <id-de-la-anulacion>

Resultado esperado: el historial paginado, con el estado del reporte de cada anulación al SII, y el detalle completo de una; con una llave de API, el detalle dice qué llave la hizo. Si una anulación quedó en error, reintenta el reporte:

{
"idempotencyKey": "reintento-anulacion-2026-11",
"confirmacionRut": "76123456-0"
}
Ventana de terminal
redcumbre folios anulaciones reintentar <id-de-la-anulacion> --rut 76123456-0 --clave reintento-anulacion-2026-11

Resultado esperado: la anulación con su estado de reporte actualizado. Reintenta sólo una anulación cuyo reporte quedó en error.

Ventana de terminal
redcumbre folios automatica ver --emisor <id-del-emisor>
{
"emisorDteId": "cm1abc123def456",
"tipoDte": 33,
"habilitado": true,
"umbral": 20,
"cantidad": 100
}
Ventana de terminal
redcumbre folios automatica cambiar --emisor <id-del-emisor> --tipo-dte 33 --habilitado true --umbral 20 --cantidad 100

Resultado esperado: la configuración del emisor por tipo. Con habilitado: true, cuando los folios disponibles bajan del umbral, la plataforma pide cantidad folios sola. Esta operación no lleva clave de repetición ni confirmación de RUT, porque guardar la configuración no consume folios; los folios los pide después la plataforma.

RespuestaQué significaQué haces
400 con CLAVE_DE_REPETICION_REQUERIDAFalta idempotencyKey en uno de los cuatro actosAgrégala (o usa --clave) y repite
400 por la confirmaciónFalta confirmacionRut o no es el RUT del emisorEscribe el RUT del emisor, el mismo que ves en listarEmisoresDte
409 al subir un CAFEl rango se traslapa con un CAF existenteRevisa los rangos con listarCafs; no subas el mismo CAF dos veces
404 de un emisor, CAF o anulaciónNo existe, es de otra empresa o es de producción y tu llave es de pruebaVerifica el identificador y el modo de la llave

Para el resultado incierto de un acto cortado a medias, reenvía exactamente el mismo cuerpo con la misma clave; no cambies la clave, porque eso es un acto nuevo.