# Listar los rangos de folios autorizados (CAF)
> Lista los rangos de folios que el SII autorizó (los CAF) y que esta empresa tiene cargados en Notta, por tipo de documento y ambiente: desde qué folio hasta cuál, cuál es el próximo por usar, cuántos quedan, si están por agotarse y hasta cuándo son válidos.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ----------------------------------------------------------------- |
| **Tool ID** | `notta.folios.listar` |
| **Nombre MCP** | `notta__folios__listar` |
| **Conector** | `notta` |
| **Plano** | `action` |
| **Scope (permiso)** | `notta:read` |
| **Auth** | `connection_credentials` |
| **Versión** | `1` |
| **Sensible** | sí |
| **Deprecado** | no |
| **Comportamiento** | readOnly=true, destructive=false, idempotent=true, openWorld=true |
> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST, campo `connectionId` en el `execute` de MCP y en las opciones del SDK. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](../conexiones/estado-consultar).
## Qué hace [#qué-hace]
Un mismo tipo de documento aparece en VARIAS filas cuando tiene varios rangos cargados, así que cuántos folios le quedan a un tipo es la suma del remaining de sus filas y jamás una sola de ellas. Es la respuesta a por qué una emisión falla por falta de folios.
## Entrada [#entrada]
Sin parámetros: envía `{}`.
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}
```
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | | |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | ----------------------------------------------------------- |
| `data` | lista de objeto | sí | Los rangos de folios autorizados (CAF) cargados en Notta, uno por rango. Un mismo tipo de documento aparece en VARIAS filas cuando tiene varios rangos cargados, asi que cuantos folios le quedan a un tipo es la suma del remaining de sus filas y nunca una sola de ellas. | | |
| `data[].id` | string \`^(\[0-9a-fA-F]{8}-\[0-9a-fA-F]{4}-\[1-8]\[0-9a-fA-F]{3}-\[89abAB]\[0-9a-fA-F]{3}-\[0-9a-fA-F]{12} | 00000000-0000-0000-0000-000000000000 | ffffffff-ffff-ffff-ffff-ffffffffffff)$\` | sí | Identificador del rango de folios dentro de Notta, un UUID. |
| `data[].rut_emisor` | string | sí | RUT de la empresa a la que el SII autorizo este rango, sin puntos y con guion antes del digito verificador. | | |
| `data[].tipo_dte` | entero | sí | Codigo del tipo de documento que este rango puede emitir, con el catalogo del SII. | | |
| `data[].sii_env` | `"cert"` · `"prod"` | sí | Ambiente al que pertenece este CAF, y al que está RECORTADA toda la lista. Certificación y producción son secuencias de folios independientes, así que una organización puede tener un CAF del mismo tipo en cada una y esta respuesta sólo trae los de uno. Lo decide la CREDENCIAL con la que llamas: una API key de certificación ve los folios de certificación aunque la empresa ya esté autorizada en producción. En el navegador lo decide el ambiente activo de la sesión. Para ver los del otro ambiente, usa una API key de ese ambiente. | | |
| `data[].folio_desde` | string | sí | Primer folio del rango autorizado. Viaja en TEXTO aunque Notta lo mande como numero, porque es un identificador y no una cantidad: un rango no empieza en 1, empieza donde el SII lo autorizo. | | |
| `data[].folio_hasta` | string | sí | Ultimo folio del rango autorizado. Viaja en TEXTO por la misma razon que folio\_desde. | | |
| `data[].next_folio` | string | sí | Proximo folio que se va a usar de este rango. Viaja en TEXTO por la misma razon que folio\_desde. | | |
| `data[].remaining` | entero | sí | Cuantos folios quedan sin usar EN ESTE RANGO, no en el tipo de documento: si el tipo tiene varios rangos, lo que le queda al tipo es la suma. Esto SI es una cantidad, por eso va en numero. | | |
| `data[].low_folios` | booleano | sí | true cuando quedan pocos folios y conviene pedirle un rango nuevo al SII antes de que se agote. | | |
| `data[].not_after` | string | sí | Fecha hasta la que el SII permite usar este rango. Pasada esa fecha los folios que queden ya no sirven. | | |
| `data[].exhausted` | booleano | sí | true cuando el rango ya no tiene folios disponibles. | | |
| `data[].created_at` | string | sí | Momento en que el rango se cargo en Notta, en formato ISO 8601. | | |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Identificador del rango de folios dentro de Notta, un UUID."
},
"rut_emisor": {
"type": "string",
"description": "RUT de la empresa a la que el SII autorizo este rango, sin puntos y con guion antes del digito verificador."
},
"tipo_dte": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Codigo del tipo de documento que este rango puede emitir, con el catalogo del SII."
},
"sii_env": {
"type": "string",
"enum": [
"cert",
"prod"
],
"description": "Ambiente al que pertenece este CAF, y al que está RECORTADA toda la lista. Certificación y producción son secuencias de folios independientes, así que una organización puede tener un CAF del mismo tipo en cada una y esta respuesta sólo trae los de uno. Lo decide la CREDENCIAL con la que llamas: una API key de certificación ve los folios de certificación aunque la empresa ya esté autorizada en producción. En el navegador lo decide el ambiente activo de la sesión. Para ver los del otro ambiente, usa una API key de ese ambiente."
},
"folio_desde": {
"type": "string",
"description": "Primer folio del rango autorizado. Viaja en TEXTO aunque Notta lo mande como numero, porque es un identificador y no una cantidad: un rango no empieza en 1, empieza donde el SII lo autorizo."
},
"folio_hasta": {
"type": "string",
"description": "Ultimo folio del rango autorizado. Viaja en TEXTO por la misma razon que folio_desde."
},
"next_folio": {
"type": "string",
"description": "Proximo folio que se va a usar de este rango. Viaja en TEXTO por la misma razon que folio_desde."
},
"remaining": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Cuantos folios quedan sin usar EN ESTE RANGO, no en el tipo de documento: si el tipo tiene varios rangos, lo que le queda al tipo es la suma. Esto SI es una cantidad, por eso va en numero."
},
"low_folios": {
"type": "boolean",
"description": "true cuando quedan pocos folios y conviene pedirle un rango nuevo al SII antes de que se agote."
},
"not_after": {
"type": "string",
"description": "Fecha hasta la que el SII permite usar este rango. Pasada esa fecha los folios que queden ya no sirven."
},
"exhausted": {
"type": "boolean",
"description": "true cuando el rango ya no tiene folios disponibles."
},
"created_at": {
"type": "string",
"description": "Momento en que el rango se cargo en Notta, en formato ISO 8601."
}
},
"required": [
"id",
"rut_emisor",
"tipo_dte",
"sii_env",
"folio_desde",
"folio_hasta",
"next_folio",
"remaining",
"low_folios",
"not_after",
"exhausted",
"created_at"
],
"additionalProperties": false,
"description": "UN rango de folios autorizado por el SII (un CAF) para un tipo de documento, no todos los de ese tipo: el mismo tipo puede tener varios rangos, cada uno en su propia fila."
},
"description": "Los rangos de folios autorizados (CAF) cargados en Notta, uno por rango. Un mismo tipo de documento aparece en VARIAS filas cuando tiene varios rangos cargados, asi que cuantos folios le quedan a un tipo es la suma del remaining de sus filas y nunca una sola de ellas."
}
},
"required": [
"data"
],
"additionalProperties": false
}
```
## Errores de esta tool [#errores-de-esta-tool]
| Código | HTTP | Reintentable | Qué hacer |
| -------------------------------- | ---- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled` | 403 | no | Reactívala en /connections o usa otra conexión del mismo sistema. |
| `connection_credential_required` | 428 | no | Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior. |
| `connection_busy` | 409 | sí | Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez. |
| `upstream_error` | 502 | sí | Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración. |
| `timeout` | 504 | sí | Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo. |
Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](../errores).