Folios y CAF: solicitar, subir y anular
Cada documento que emite un emisor DTE usa un folio, y los folios los autoriza el SII en archivos CAF: un rango de folios por tipo de documento. Esta guía recorre lo que haces con ellos por API.
El agente que integra con IA tiene la versión resumida en la ficha Folios y CAF. Desde la terminal, cada operación tiene su subcomando de redcumbre folios, por ejemplo redcumbre folios anular <cafId> --rut <rut-del-emisor> --clave <clave>; la lista completa está en CLI de REDCUMBRE.
Qué necesitas
Sección titulada «Qué necesitas»- El
emisorDteIdde tu emisor DTE (GET /{tenantSlug}/emisores). - Una llave
FULL-APIde producción, o de prueba para ensayar. Cómo crearla y cuándo usar cada una: Modo de prueba.
Ver cuántos folios tienes
Sección titulada «Ver cuántos folios tienes»| Qué quieres ver | Ruta |
|---|---|
| Folios totales, usados y disponibles por tipo | GET /{tenantSlug}/boletas/cafs/stats |
| Los CAF del emisor, con rango, estado y folios usados | GET /{tenantSlug}/boletas/cafs |
| Los tipos de documento autorizados del emisor | GET /{tenantSlug}/boletas/cafs/documentos-autorizados |
| La disponibilidad de folios de un tipo | GET /{tenantSlug}/boletas/cafs/consulta-folios |
| Los tipos para los que puedes pedir folios | GET /{tenantSlug}/boletas/cafs/tipos-disponibles |
Todas piden emisorDteId como parámetro de consulta. Ninguna devuelve el XML del CAF ni su clave privada.
Solicitar folios
Sección titulada «Solicitar folios»curl -X POST "https://api.redcumbre.cl/{tenantSlug}/boletas/cafs/solicitar" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "emisorDteId": "cm1abc123def456", "tipoDte": 33, "cantidad": 10, "idempotencyKey": "folios-factura-2026-11", "confirmacionRut": "76123456-0" }'Respuesta esperada: el CAF guardado, con su tipo, su rango y su estado. cantidad va de 1 a 10.000.
Subir un CAF que ya tienes
Sección titulada «Subir un CAF que ya tienes»POST /{tenantSlug}/boletas/cafs/upload recibe el XML como formulario (multipart/form-data): el archivo en el campo archivo y el emisorDteId. Se valida igual que siempre; un XML inválido responde 400 y un rango
que se traslapa con un CAF existente responde 409. Subir un CAF no pide clave de repetición ni confirmación del RUT.
Anular folios
Sección titulada «Anular folios»| Qué anulas | Ruta |
|---|---|
| Todos los folios sin usar de un CAF | POST /{tenantSlug}/boletas/cafs/{cafId}/anular |
| Un rango de folios | POST /{tenantSlug}/boletas/cafs/{cafId}/anular-folios |
El rango lleva folioDesde, folioHasta (puede ser igual al primero) y un motivo: NO_UTILIZADO, EXPIRADO, ERROR_IRRECUPERABLE o DECOMMISSION_CAF. Una anulación no se deshace.
curl -X POST "https://api.redcumbre.cl/{tenantSlug}/boletas/cafs/{cafId}/anular-folios" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "folioDesde": 100, "folioHasta": 200, "motivo": "NO_UTILIZADO", "idempotencyKey": "anular-100-200-2026-11", "confirmacionRut": "76123456-0" }'Cada anulación se reporta al SII. Ves el historial con GET /{tenantSlug}/boletas/cafs/anulaciones y el detalle de una con GET /{tenantSlug}/boletas/cafs/anulaciones/{anulacionId}, que con una llave de API indica qué llave la hizo.
Si el reporte de una anulación quedó en error, POST /{tenantSlug}/boletas/cafs/anulaciones/{anulacionId}/retry lo reintenta.
La clave de repetición y la confirmación del RUT
Sección titulada «La clave de repetición y la confirmación del RUT»Pedir folios, anular un CAF, anular un rango y reintentar un reporte exigen, con una llave de API, dos campos en el cuerpo:
| Campo | Para qué |
|---|---|
idempotencyKey | 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. Usa un identificador estable de tu sistema |
confirmacionRut | El RUT del emisor, escrito de nuevo. Si no es el del emisor, el acto no se ejecuta. El panel no lo pide |
Sin la clave, la operación responde 400 y no se ejecuta. Con el CLI, la clave va con --clave y el RUT con --rut.
Solicitud automática de folios
Sección titulada «Solicitud automática de folios»GET y PUT /{tenantSlug}/boletas/cafs/auto-folio-config leen y cambian la configuración por emisor y tipo: si está habilitado, el umbral bajo el cual se pide y la cantidad a pedir. Guardar la
configuración no pide folios ni lleva clave de repetición: los pide la plataforma cuando bajas del umbral.
Qué pasa con una llave de prueba
Sección titulada «Qué pasa con una llave de prueba»Con una llave de prueba, los folios trabajan sobre una copia de prueba del emisor con un CAF simulado; no tocan tus CAF reales ni llaman al SII:
- Subir un CAF valida el XML y su traslape contra los CAF de prueba, y responde
409si choca, incluido el CAF simulado, que cubre los folios del 1 al 1.000.000. - Solicitar folios entrega el CAF simulado y no usa
cantidad. - Anular crea anulaciones con estado
NO_APLICA, sin reportar al SII. - Las lecturas muestran sólo los CAF de prueba.
Nada se cobra. Cuando todo funcione, repite con la llave de producción: ahí sí se piden y se anulan folios reales.