Skip to main content

​
¿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 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}. 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:
Cada ambiente guarda su propia foto, así que una lectura de certificación no pisa lo que sabemos de tus folios reales.
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.

​
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.