Folios y CAF

Cada documento tiene un folio (su número). No puedes usar cualquier número: el SII te autoriza rangos de folios por tipo de documento, y esa autorización llega en un archivo llamado CAF (Código de Autorización de Folios).

Por ejemplo, un CAF puede decir: “la empresa 88888888-8 puede emitir facturas (33) con los folios del 1 al 100”.

Qué contiene un CAF

Es un XML firmado por el SII:

<AUTORIZACION>
  <CAF version="1.0">
    <DA>
      <RE>88888888-8</RE>          <!-- RUT del emisor -->
      <RS>Mi Empresa SpA</RS>      <!-- Razón social -->
      <TD>33</TD>                  <!-- Tipo de documento -->
      <RNG><D>1</D><H>100</H></RNG><!-- Rango: desde el 1 hasta el 100 -->
      <FA>2026-10-29</FA>          <!-- Fecha de autorización -->
      <RSAPK>...</RSAPK>           <!-- Llave pública -->
      <IDK>100</IDK>
    </DA>
    <FRMA algoritmo="SHA1withRSA">...</FRMA>   <!-- Firma del SII -->
  </CAF>
  <RSASK>...</RSASK>               <!-- Llave privada para timbrar -->
  <RSAPUBK>...</RSAPUBK>
</AUTORIZACION>

La llave privada del CAF (RSASK) es la que se usa para timbrar cada documento. Por eso el CAF también es un dato sensible: guárdalo con el mismo cuidado que el certificado.

Obtener el CAF

Los CAF se solicitan al SII con el certificado digital de una persona autorizada por la empresa. Puedes hacerlo de dos formas, y ambas sirven para cualquier CAF, incluido el primero de cada tipo de documento:

Solicitar un CAF con la API

curl -X POST "https://app.apigateway.cl/api/v2/sii/dte/caf/solicitar/88888888-8/33/100?certificacion=1" \
  -H "Authorization: Token $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
        "cert": {
            "cert-data": "-----BEGIN CERTIFICATE-----\nMIIG...\n-----END CERTIFICATE-----",
            "pkey-data": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----"
        }
    }
}'

La respuesta no es JSON: es directamente el XML del CAF, en codificación ISO-8859-1. Guárdalo tal cual como archivo.

Otros recursos de folios

Todos son POST, usan el bloque auth.cert y el parámetro certificacion igual que la solicitud, y sus URL parten en /api/v2/sii/dte/caf/:

El detalle de cada uno está en la documentación de la API, en API DTE - Código de Asignación de Folios (CAF).

Revisar un CAF

Antes de guardar un CAF en tu sistema, cárgalo con la API para leer sus datos. El XML va en base64:

curl -X POST https://app.apigateway.cl/api/v2/libredte/billing/identifier/caf_loader/load \
  -H "Authorization: Token $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iSVNPLTg4NTktMSI/Pgo8QVVU..."}}'

Respuesta (resumida):

{
    "data": {
        "id": "CAF33D1H100",
        "emisor": {
            "rut": "88888888-8",
            "razon_social": "Mi Empresa SpA"
        },
        "tipoDocumento": 33,
        "folioDesde": 1,
        "folioHasta": 100,
        "cantidadFolios": 100,
        "fechaAutorizacion": "2026-10-29",
        "fechaVencimiento": "2027-04-27",
        "vigente": true,
        "vence": true
    }
}

Guarda en tu base de datos al menos: el emisor, el tipo de documento, folioDesde, folioHasta, fechaVencimiento, el ambiente y el XML del CAF.

Controlar los folios en tu sistema

La API no lleva la cuenta de qué folios usaste: eso es responsabilidad de tu sistema. Una forma simple de hacerlo:

Tabla de CAF: un registro por cada CAF recibido.

Tabla de folios usados: un registro por cada folio que asignas.

Para emitir:

1. Busca un CAF vigente del emisor, tipo de documento y ambiente.
2. Toma el siguiente folio libre de ese CAF y resérvalo en tu base de datos dentro de una transacción, para que dos emisiones simultáneas nunca usen el mismo folio.
3. Construye el documento con ese folio y ese CAF.
4. Cuando queden pocos folios (por ejemplo, el 20%), solicita un nuevo CAF.

Practicar con un CAF de prueba

Mientras aprendes, no necesitas un CAF real. La API puede generar un CAF ficticio para cualquier emisor:

curl -X POST https://app.apigateway.cl/api/v2/libredte/billing/identifier/caf_faker/create \
  -H "Authorization: Token $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
        "emisor": {"rut": "88888888-8", "razon_social": "Mi Empresa SpA"},
        "codigoDocumento": 33,
        "folioDesde": 1,
        "folioHasta": 100
    }
}'

La respuesta tiene el mismo formato que caf_loader/load y además el XML del CAF en base64 en el campo xml. Ese valor es el que usarás como caf al construir documentos.