Ir al contenido

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.

  • El emisorDteId de tu emisor DTE (GET /{tenantSlug}/emisores).
  • Una llave FULL-API de producción, o de prueba para ensayar. Cómo crearla y cuándo usar cada una: Modo de prueba.
Qué quieres verRuta
Folios totales, usados y disponibles por tipoGET /{tenantSlug}/boletas/cafs/stats
Los CAF del emisor, con rango, estado y folios usadosGET /{tenantSlug}/boletas/cafs
Los tipos de documento autorizados del emisorGET /{tenantSlug}/boletas/cafs/documentos-autorizados
La disponibilidad de folios de un tipoGET /{tenantSlug}/boletas/cafs/consulta-folios
Los tipos para los que puedes pedir foliosGET /{tenantSlug}/boletas/cafs/tipos-disponibles

Todas piden emisorDteId como parámetro de consulta. Ninguna devuelve el XML del CAF ni su clave privada.

Ventana de terminal
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.

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.

Qué anulasRuta
Todos los folios sin usar de un CAFPOST /{tenantSlug}/boletas/cafs/{cafId}/anular
Un rango de foliosPOST /{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.

Ventana de terminal
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:

CampoPara qué
idempotencyKeySi 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
confirmacionRutEl 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.

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.

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 409 si 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.