> ## 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 de folios al SII > Crea una consulta de folios contra el SII. Es un **recurso asíncrono**: responde 201 con `status: "pending"` y lee en segundo plano. **Consultar no consume folios**: el trámite se queda en el paso 1 del portal, que no reserva ningún rango. Por eso no lleva `Idempotency-Key` — repetirla no cuesta nada irreversible. ## OpenAPI ````yaml api-reference/openapi-v2.json POST /folio-queries/ openapi: 3.0.0 info: title: Tupana API — v2 description: >- API v2 de Tupana: facturación electrónica, cesiones, recaudación, consultas, boleta de honorarios y nómina. Los identificadores de recursos son public IDs opacos con prefijo (docu_, ment_, cred_, doce_, empl_…). version: 2.0.0 servers: - url: https://api.tupana.ai/v2 description: Producción (v2) security: - apiKeyAuth: [] paths: /folio-queries/: post: tags: - Folios summary: Pedir una lectura de folios al SII description: >- Crea una consulta de folios contra el SII. Es un **recurso asíncrono**: responde 201 con `status: "pending"` y lee en segundo plano. **Consultar no consume folios**: el trámite se queda en el paso 1 del portal, que no reserva ningún rango. Por eso no lleva `Idempotency-Key` — repetirla no cuesta nada irreversible. operationId: createFolioQuery_v2 requestBody: required: true content: application/json: schema: type: object required: - master_entity_id - dte_type properties: master_entity_id: type: string description: ID de la entidad. El public ID de la entidad (`ment_...`). example: ment_4829301923847 dte_type: type: integer description: Tipo de DTE a consultar. example: 33 sii_environment: type: string enum: - production - certification default: production description: >- Ambiente del SII contra el que se hace la operación. `production` (palena) entrega folios REALES, que no se devuelven; `certification` (maullin) entrega folios de prueba, que NO sirven para emitir. Si se omite, producción. Un valor distinto de los dos se rechaza con 422 en vez de asumir un default. example: certification responses: '201': description: Consulta creada. content: application/json: schema: $ref: '#/components/schemas/FolioQuery' '400': description: Tipo de documento inválido. '403': description: La entidad no pertenece al cliente. '422': description: El ambiente pedido no existe o no está habilitado content: application/json: schema: type: object properties: error: type: string error_code: type: string enum: - invalid_environment - environment_not_allowed - certification_not_enabled '429': description: >- Límite horario de consultas agotado (10 por hora, por empresa). Se cuenta aparte de la cuota de timbraje. content: application/json: schema: $ref: '#/components/schemas/FolioQuotaExceeded' security: - apiKeyAuth: [] components: schemas: FolioQuery: type: object description: >- Consulta de folios al SII. Es un recurso para que puedas seguirla: antes esto era una acción que respondía 202 sin nada que consultar. properties: id: type: string example: foqu_3b7f1e9d5c2a8 dte_type: type: integer example: 33 status: type: string enum: - pending - processing - completed - failed result: type: object description: Lo que dijo el SII cuando la consulta terminó. properties: available: type: integer nullable: true description: >- Folios timbrados y sin emitir. `null` significa que no lo sabemos, no cero. example: 3 max_per_request: type: integer nullable: true description: Máximo por solicitud vigente. example: 8 last_timbraje: type: string nullable: true timbrajes: type: array description: Rangos timbrados históricamente. items: type: object error: type: string description: Motivo cuando la consulta no terminó bien. created_at: type: string format: date-time completed_at: type: string format: date-time nullable: true sii_environment: type: string enum: - production - certification description: >- Ambiente del SII en el que se hizo la operación. Un CAF de `certification` NO sirve para emitir. error_code: type: string description: >- Vocabulario cerrado del desenlace fallido; vacío si no hubo error. Ver la página de códigos de error. enum: - '' - certification_not_enabled - missing_certificate - no_folios_authorized - sii_unavailable - sii_unrecognized_page FolioQuotaExceeded: type: object description: >- Cuota agotada para la empresa. Timbraje y consulta tienen cuotas separadas; las dos se cuentan por empresa, no por API key. properties: error: type: string example: 'Cuota de timbrajes agotada: 3 de 3 por hora.' limit: type: integer description: Tope de la ventana que se agotó. example: 3 window: type: string enum: - hora - mes example: hora used: type: integer description: Timbrajes ya consumidos en esa ventana. example: 3 resets_at: type: string format: date-time description: Cuándo vuelve a haber cupo. securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: >- API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.