Folios y CAF por API
Qué resuelve
Sección titulada «Qué resuelve»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:
| Para | Operación |
|---|---|
| Subir el CAF que entregó el SII | subirCaf |
| Ver los CAF del emisor, con su rango, su estado y los folios usados | listarCafs |
| Ver folios totales, usados y disponibles por tipo | obtenerEstadisticasDeCafs |
| Ver qué tipos de documento tiene autorizados el emisor | consultarDocumentosAutorizados |
| Ver la disponibilidad de folios de un tipo | consultarFoliosEnSii |
| Ver para qué tipos se pueden pedir folios | listarTiposDeFoliosDisponibles |
| Pedir folios nuevos al SII | solicitarFolios |
| Anular todos los folios sin usar de un CAF | anularCaf |
| Anular un rango de folios | anularFoliosDeCaf |
| Ver el historial de anulaciones y el detalle de una | listarAnulacionesDeFolios, obtenerAnulacionDeFolios |
| Reintentar el reporte de una anulación que falló | reintentarReporteDeAnulacion |
| Leer y cambiar la solicitud automática de folios | obtenerSolicitudAutomaticaDeFolios, 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.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- Un emisor DTE y su
emisorDteId. Sale deredcumbre 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 initesFULL-APIy alcanza. Para una llave más angosta,redcumbre api describir solicitarFoliosmuestra 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.
Lo que exigen los cuatro actos
Sección titulada «Lo que exigen los cuatro actos»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, responde400y 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 deredcumbre folioses la bandera--rut. El panel no lo pide, porque ahí una persona ve el emisor en pantalla.
Cómo se comporta el modo de prueba
Sección titulada «Cómo se comporta el modo de prueba»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 responde409si 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 usacantidad: la mandas igual, porque el cuerpo se valida como siempre, pero no cambia el resultado.anularCafyanularFoliosDeCaf: crean las anulaciones con estadoNO_APLICAy no reportan nada al SII.reintentarReporteDeAnulacion: una anulaciónNO_APLICAse 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. actualizarSolicitudAutomaticaDeFoliosguarda 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>.
1. Ubica las operaciones
Sección titulada «1. Ubica las operaciones»redcumbre buscar "folios CAF"redcumbre api describir solicitarFoliosResultado esperado: las operaciones de esta ficha, con su método, su ruta y los campos del cuerpo.
2. Mira cuántos folios tiene el emisor
Sección titulada «2. Mira cuántos folios tiene el emisor»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.
3. Ve qué se puede pedir
Sección titulada «3. Ve qué se puede pedir»redcumbre folios tipos-disponibles --emisor <id-del-emisor>redcumbre folios consultar --emisor <id-del-emisor> --tipo-dte 33redcumbre 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.
4. Solicita folios
Sección titulada «4. Solicita folios»{ "emisorDteId": "cm1abc123def456", "tipoDte": 33, "cantidad": 10, "idempotencyKey": "folios-factura-2026-11", "confirmacionRut": "76123456-0"}redcumbre folios solicitar --emisor <id-del-emisor> --tipo-dte 33 --cantidad 10 --rut 76123456-0 --clave folios-factura-2026-11Resultado 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.
5. Sube un CAF que ya tienes
Sección titulada «5. Sube un CAF que ya tienes»redcumbre folios subir --emisor <id-del-emisor> --archivo caf.xmlResultado 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).
6. Anula folios
Sección titulada «6. Anula folios»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"}redcumbre folios anular <id-del-caf> --rut 76123456-0 --clave anular-caf-33-2026-11redcumbre folios anular-folios <id-del-caf> --folio-desde 100 --folio-hasta 200 --motivo NO_UTILIZADO --rut 76123456-0 --clave anular-100-200-2026-11Resultado 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»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"}redcumbre folios anulaciones reintentar <id-de-la-anulacion> --rut 76123456-0 --clave reintento-anulacion-2026-11Resultado esperado: la anulación con su estado de reporte actualizado. Reintenta sólo una anulación cuyo reporte quedó en error.
8. Configura la solicitud automática
Sección titulada «8. Configura la solicitud automática»redcumbre folios automatica ver --emisor <id-del-emisor>{ "emisorDteId": "cm1abc123def456", "tipoDte": 33, "habilitado": true, "umbral": 20, "cantidad": 100}redcumbre folios automatica cambiar --emisor <id-del-emisor> --tipo-dte 33 --habilitado true --umbral 20 --cantidad 100Resultado 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.
Errores que vas a ver
Sección titulada «Errores que vas a ver»| Respuesta | Qué significa | Qué haces |
|---|---|---|
400 con CLAVE_DE_REPETICION_REQUERIDA | Falta idempotencyKey en uno de los cuatro actos | Agrégala (o usa --clave) y repite |
400 por la confirmación | Falta confirmacionRut o no es el RUT del emisor | Escribe el RUT del emisor, el mismo que ves en listarEmisoresDte |
409 al subir un CAF | El rango se traslapa con un CAF existente | Revisa los rangos con listarCafs; no subas el mismo CAF dos veces |
404 de un emisor, CAF o anulación | No existe, es de otra empresa o es de producción y tu llave es de prueba | Verifica 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.