# Listar CAF (/docs/referencia/caf/listar)

`POST /v1/caf/{rut}/listar/{tipoDocumento}`

Lista los CAF que el SII autorizó para la empresa y el tipo de documento, en el ambiente que
indique `ambiente`: todos los que el SII lista, también los ya usados o anulados enteros. Para
saber cuántos folios quedan en uno de ellos, consulte caf_v1_estado_folios con su rango. Es una
lectura: no timbra ni anula nada, y repetirla no cambia nada en el SII.

**Cuál usar.** Reemplaza a caf_v1_anulacion_masiva_listar para listar CAF: el mismo modelo de
respuesta, pero en el ambiente pedido y verificando el permiso del certificado. Para bajar uno de
estos CAF, use caf_v1_reobtener con `folioInicial`, si está en la primera página del listado de
reobtención del SII (ver `folioInicial` en caf_v1_reobtener).

**Permisos.** Además de validar el certificado en el ambiente pedido, verifica en el SII del mismo
ambiente que su titular esté autorizado por la empresa para operar con folios (CAF); no hace falta
que administre usuarios. caf_v1_reobtener, en cambio, valida el certificado siempre en producción.
Consulta la opción de anulación masiva del SII: una empresa que no está habilitada ahí recibe
`CONTRIBUYENTE_SIN_PERMISO`.

**Tiempos.** Hace varias llamadas al SII en serie y puede tardar decenas de segundos: configure un timeout de cliente de al menos 70 segundos. Si tarda más de 60
segundos, la capa de entrada de la API responde 504 con una página HTML, sin código: es una
lectura, repítala. `SII_ERROR_CXN` es frecuente e intermitente en el SII de producción: reintente
respetando `Retry-After` (30 segundos), con espera exponencial (30, 60 y 120 segundos) y un tope
de 3 intentos; cada intento puede tardar decenas de segundos.

**Sesión del SII entre ambientes (sin verificar).** La sesión del SII se reusa 15 minutos por
certificado, en los dos ambientes. Si alterna `ambiente=0` y `ambiente=1` con el mismo certificado
en menos de 15 minutos, el SII podría rechazar la sesión. Desde la versión 1.5.3 la respuesta es
`SII_ERROR_CXN`, reintentable (antes, `SII_RESPUESTA_INESPERADA`): si persiste después de los
reintentos, espere 15 minutos y repita antes de contactar a soporte.

**Para probar.** Con el RUT 1-9 o un RUT de prueba del cliente no se consulta al SII ni se valida
el certificado: la respuesta es siempre un único CAF de ejemplo, del folio 1 al 10 (el ejemplo de
respuesta de esta página es otro: una empresa con dos CAF). El RUT de prueba no simula los errores
del SII: `CONTRIBUYENTE_SIN_PERMISO`, `SII_ERROR_CXN` y los rechazos solo se ven contra el SII.

## Parámetros

| Nombre | En | Tipo | Requerido | Descripción |
|---|---|---|---|---|
| `rut` | path | string | sí | RUT de la empresa. |
| `tipoDocumento` | path | integer | sí | Tipo del documento DTE, con el código del SII: 33 factura, 34 factura exenta, 39 y 41 boletas, 56 nota de débito, 61 nota de crédito, entre otros. |
| `ambiente` | query | integer | no | Ambiente del SII: 0 = Homologación (certificación), 1 = Producción. Si se omite, opera en **producción**: páselo siempre explícito. Un valor que no se reconoce no da error: la operación corre en producción. Un número distinto de 0 y 1 no da error y corre en homologación. En caf_v1_reobtener, ese mismo número corre en producción: use 0 o 1 en las dos. |

## Cuerpo

```json
{
  "Contrasenna": "********",
  "Data": "MIIC"
}
```

## Respuestas

### 200

Los CAF del SII para la empresa y el tipo de documento: `Cafs`, un elemento por CAF, ordenados por `FolioInicial` de mayor a menor. Cada CAF trae `FolioInicial`, `FolioFinal`, `Cantidad`, `Fecha`, `Dueno` y `RUTDueno`. `Cafs` vacía significa que el SII no lista CAF de ese tipo para la empresa; nunca es nula. Con el RUT 1-9 o un RUT de prueba del cliente, un único CAF de ejemplo, del folio 1 al 10.

| Campo | Tipo | Descripción |
|---|---|---|
| `Cafs` | array o null | Un elemento por CAF. En caf_v1_listar nunca es nula: es una lista vacía si el SII no lista CAF de ese tipo para la empresa. |
| `Cafs[].Cantidad` | integer | Cantidad de folios en el CAF. |
| `Cafs[].Dueno` | string o null | Nombre de la persona que generó el CAF en el SII. |
| `Cafs[].Fecha` | string o null | Fecha del CAF, como la informa el SII, en formato dd-mm-aaaa. |
| `Cafs[].FolioFinal` | integer | Folio final del CAF. |
| `Cafs[].FolioInicial` | integer | Folio inicial del CAF. |
| `Cafs[].RUTDueno` | string o null | RUT de la persona que generó el CAF en el SII. |

Ejemplo:

```json
{
  "Cafs": [
    {
      "Cantidad": 100,
      "Dueno": "Usuario Ejemplo",
      "Fecha": "12-03-2026",
      "FolioFinal": 1200,
      "FolioInicial": 1101,
      "RUTDueno": "12345678-5"
    },
    {
      "Cantidad": 100,
      "Dueno": "Usuario Ejemplo",
      "Fecha": "05-01-2026",
      "FolioFinal": 1100,
      "FolioInicial": 1001,
      "RUTDueno": "12345678-5"
    }
  ]
}
```

### 400

Un parámetro numérico de la ruta (o de la query) sin valor por omisión no se pudo convertir: no es un número, o no cabe en el tipo. Lo responde el framework, después de autenticar y antes de ejecutar la operación. `MessageDetail` depende de la configuración del servidor (no verificado): no dependa de él.

### 401

No autenticado.

### 404

Esta operación no tiene un 404 de negocio. Un 404 es una URL que no corresponde a ninguna operación (una ruta mal escrita, un segmento de más o de menos): en general lo responde el servidor web con una página HTML, sin los headers de la API; si la URL llega a la API, es un JSON del framework con `Message`. Inferido del código, no verificado contra el servidor desplegado. Revise la URL: repetir el mismo request da el mismo 404. El texto plano sigue declarado para no romper el contrato publicado, pero esta operación nunca responde un 404 en texto plano.

### 409

Se superó el rate limit: **409 Conflict**, no 429. El request no se ejecutó.

### 500

Error de negocio en texto plano, `CODIGO:mensaje`, con los headers `X-Codigo-Error`,
`X-Reintentable` y, si vale reintentar, `Retry-After`; ante una falla interna, un error del
framework en JSON. Esta operación no responde desde la memoria de rechazos: nunca trae
`X-Respuesta-De-Memoria`.

- Sin el cuerpo del POST, o sin `Data` o sin `Contrasenna`: `CERT_REQUERIDO:Los datos del
  certificado son requeridos.`.
- Un RUT que no es válido: `ERROR_GENERAL:El rut … no es valido.`: corríjalo, no lo reintente.
- El certificado no se pudo validar: el error de la validación con su propio código
  (`CERT_EXPIRADO`, `CERT_REVOCADO`, `CERT_NO_VALIDO`, `CERT_NO_CONFIGURADO_AUTH`,
  `CERT_AUTH_NOT_CONFIGURED`, `CERT_ERROR`…).
- El SII dice que el titular del certificado no está autorizado por la empresa para operar con
  folios: `CERT_SIN_PERMISO`.
- La empresa no puede operar en esa modalidad (MiPyme): `SEC_EMP_NOT_AUTHORIZED`.
- La empresa no está habilitada en la opción de anulación masiva del SII:
  `CONTRIBUYENTE_SIN_PERMISO`.
- El SII pide intentarlo más tarde, falló la comunicación con el SII o, desde la versión 1.5.3,
  el listado de CAF del SII pide volver a iniciar sesión: `SII_ERROR_CXN`, reintentable.
- La página del listado de CAF del SII no dice si el certificado tiene permiso, o el SII
  contestó algo que no se pudo interpretar: `SII_RESPUESTA_INESPERADA`, no reintentable.
- Además pueden llegar otros rechazos del SII: `SEC_USER_BOLSII`, `SEC_USER_NOT_AUTHENTICATED`
  y, al autenticar el certificado, `CERT_REVOCADO` o `CERT_EXPIRADO`.

Ejemplos en `text/plain`:

**El titular del certificado no está autorizado por la empresa para CAF** (`CERT_SIN_PERMISO`)

```text
CERT_SIN_PERMISO:El certificado no está autorizado por la empresa 11111111-1 para operar con folios (CAF) en el SII.
```

**El SII pidió intentarlo más tarde (reintentable)** (`SII_ERROR_CXN`)

```text
SII_ERROR_CXN:Error de comunicacion con el SII, intente nuevamente.
```

## Códigos de error

| Status | Código | Mensaje |
|---|---|---|
| 500 | `CERT_SIN_PERMISO` | «El certificado no está autorizado por la empresa {rut} para operar con folios (CAF) en el SII.»; o «El certificado no tiene permisos para la empresa {rut}.»; o «El certificado no tiene permisos para la empresa.» |

## Reintentos e idempotencia

**Idempotente: sí.** Repetirla con los mismos datos no duplica nada.

| Qué hacer | Códigos y status |
|---|---|
| Reintentar solo, con espera (`automatico`) | `409`, [`SII_ERROR_CXN`](/docs/errores-y-reintentos/#error-SII_ERROR_CXN) |
| Consultar el estado antes de repetir (`manual`) | [`CERT_ERROR`](/docs/errores-y-reintentos/#error-CERT_ERROR), [`ERROR_GENERAL`](/docs/errores-y-reintentos/#error-ERROR_GENERAL), [`SEC_USER_NOT_AUTHENTICATED`](/docs/errores-y-reintentos/#error-SEC_USER_NOT_AUTHENTICATED) |
| No repetir: corregir la causa (`nunca`) | [`CERT_AUTH_NOT_CONFIGURED`](/docs/errores-y-reintentos/#error-CERT_AUTH_NOT_CONFIGURED), [`CERT_EXPIRADO`](/docs/errores-y-reintentos/#error-CERT_EXPIRADO), [`CERT_NO_CONFIGURADO_AUTH`](/docs/errores-y-reintentos/#error-CERT_NO_CONFIGURADO_AUTH), [`CERT_NO_VALIDO`](/docs/errores-y-reintentos/#error-CERT_NO_VALIDO), [`CERT_REQUERIDO`](/docs/errores-y-reintentos/#error-CERT_REQUERIDO), [`CERT_REVOCADO`](/docs/errores-y-reintentos/#error-CERT_REVOCADO), [`CERT_SIN_PERMISO`](/docs/errores-y-reintentos/#error-CERT_SIN_PERMISO), [`CONTRIBUYENTE_SIN_PERMISO`](/docs/errores-y-reintentos/#error-CONTRIBUYENTE_SIN_PERMISO), [`SEC_EMP_NOT_AUTHORIZED`](/docs/errores-y-reintentos/#error-SEC_EMP_NOT_AUTHORIZED), [`SEC_USER_BOLSII`](/docs/errores-y-reintentos/#error-SEC_USER_BOLSII), [`SII_RESPUESTA_INESPERADA`](/docs/errores-y-reintentos/#error-SII_RESPUESTA_INESPERADA) |

Un código que no figura en esta tabla se resuelve con la [regla de respaldo](/docs/errores-y-reintentos/#la-regla-de-respaldo).

## Ejemplo

```bash
curl --request POST \
  --url 'https://api.enrolamiento.cl/v1/caf/1-9/listar/33?ambiente=0' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <base64 de usuario:apikey>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "Contrasenna": "********",
  "Data": "MIIC"
}
'
```