> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tupana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pedir una lectura al SII

## ¿Para qué se usa?

Para leer del SII el estado real de tus folios cuando necesitas el dato fresco: antes de decidir un timbraje grande, después de una jornada de emisión fuerte, o cuando el `as_of` de [`GET /folios`](/api-reference/folios/availability) ya quedó viejo.

## Qué hace

* Es un **recurso asíncrono**: crea la consulta, responde **201** con `status: "pending"` y va al SII en segundo plano. La llamada nunca bloquea.
* Lee la disponibilidad y el histórico de timbrajes del tipo de documento que pidas.
* Sigue el resultado con [`GET /folio-queries/{id}`](/api-reference/folios/query-get). Cuando termina, la foto de `GET /folios` también queda actualizada.

## En qué ambiente lees

`sii_environment` decide qué stock lees: `production` (palena, tus folios reales) o `certification` (maullin). Si lo omites, producción. Va en el **cuerpo** de la llamada:

```json theme={null}
{
  "master_entity_id": "eid_...",
  "dte_type": 33,
  "sii_environment": "certification"
}
```

Cada ambiente guarda su propia foto, así que una lectura de certificación no pisa lo que sabemos de tus folios reales.

<Note>
  **Consultar no consume folios.** La consulta abre el trámite en el portal del SII y lee lo que publica, sin llegar al paso que reserva un rango. Por eso tampoco lleva `Idempotency-Key`: repetirla no cuesta nada irreversible, a diferencia de un timbraje.
</Note>

## Límite

Cada empresa puede pedir **10 lecturas por hora**. No hay límite mensual: una consulta no consume nada irreversible.

El límite existe porque consultar no quema folios, pero sí habla con el SII —un login más dos lecturas—, y el SII penaliza por RUT. Cuando eso pasa deja de responder **todo** lo de esa empresa, no solo los folios. Se cuenta por empresa, no por API key, y aparte de la cuota de timbraje: son recursos distintos.

## Errores que vas a ver

* **400** — el tipo de documento no es válido.
* **403** — la entidad no es tuya.
* **429** — se agotó el límite horario. El cuerpo trae `limit`, `window` y `resets_at` para que sepas cuándo reintentar.

```json theme={null}
{
  "error": "Cuota de consultas de folios agotada: 10 de 10 por hora.",
  "limit": 10,
  "window": "hora",
  "used": 10,
  "resets_at": "2026-08-28T15:05:00Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.