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

# Folios disponibles y timbrajes históricos

> Última lectura conocida del estado de tus folios en el SII: cuántos tienes timbrados y sin emitir (`available`), cuántos te autoriza el SII por solicitud (`max_per_request`) y los rangos que te timbraron antes (`timbrajes`).

El dato vive en el SII y solo se conoce consultándolo, así que este endpoint responde con la **última foto guardada** y su fecha (`as_of`) — no bloquea. Para forzar una relectura usa `POST /folios/refresh`.

Si la entidad nunca fue consultada, `results` viene vacío. Vacío significa *no sabemos*, no *cero folios*.



## OpenAPI

````yaml api-reference/openapi-v2.json GET /folios/
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:
  /folios/:
    get:
      tags:
        - Folios
      summary: Folios disponibles y timbrajes históricos
      description: >-
        Última lectura conocida del estado de tus folios en el SII: cuántos
        tienes timbrados y sin emitir (`available`), cuántos te autoriza el SII
        por solicitud (`max_per_request`) y los rangos que te timbraron antes
        (`timbrajes`).


        El dato vive en el SII y solo se conoce consultándolo, así que este
        endpoint responde con la **última foto guardada** y su fecha (`as_of`) —
        no bloquea. Para forzar una relectura usa `POST /folios/refresh`.


        Si la entidad nunca fue consultada, `results` viene vacío. Vacío
        significa *no sabemos*, no *cero folios*.
      operationId: listFolioAvailability_v2
      parameters:
        - name: master_entity_id
          in: query
          required: true
          schema:
            type: string
          description: ID de la entidad maestra (public ID `ment_...`).
          example: ment_4829301923847
        - name: dte_type
          in: query
          required: false
          schema:
            type: integer
          description: Filtra por tipo de documento.
          example: 33
        - name: sii_environment
          in: query
          required: false
          schema:
            type: string
            enum:
              - production
              - certification
            default: production
          description: >-
            Ambiente del SII. Si se omite, producción: los folios de
            certificación son un stock distinto y mostrarlos como propios sería
            peor que no mostrar nada.
      responses:
        '200':
          description: Última foto conocida por tipo de documento
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FolioAvailability'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                        nullable: true
                      page_size:
                        type: integer
                        nullable: true
                      total:
                        type: integer
                      total_pages:
                        type: integer
                        nullable: true
                  links:
                    type: object
                    properties:
                      next:
                        type: string
                        nullable: true
                      prev:
                        type: string
                        nullable: true
              example:
                data:
                  - dte_type: 33
                    available: 120
                    max_per_request: 50
                    last_timbraje: '2026-08-19'
                    timbrajes:
                      - authorization_date: '2026-08-19'
                        quantity: 50
                        folio_start: 539
                        folio_end: 588
                        consistent: true
                    as_of: '2026-08-27T14:05:00Z'
                meta:
                  page: null
                  page_size: null
                  total: 1
                  total_pages: null
                links:
                  next: null
                  prev: null
        '403':
          description: Sin acceso a la entidad indicada
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: No tienes acceso a esta entidad.
      security:
        - apiKeyAuth: []
components:
  schemas:
    FolioAvailability:
      type: object
      description: >-
        Foto del estado de los folios de una empresa en el SII para un tipo de
        documento.
      properties:
        dte_type:
          type: integer
          example: 33
        available:
          type: integer
          nullable: true
          description: >-
            Folios timbrados y sin emitir según el SII. `null` significa que el
            SII no publicó el dato, no que sean cero.
          example: 120
        max_per_request:
          type: integer
          nullable: true
          description: >-
            Máximo de folios que el SII autoriza por solicitud en este momento.
            Sube con el uso.
          example: 50
        last_timbraje:
          type: string
          description: Fecha del último timbraje según el SII.
          example: '2026-08-19'
        timbrajes:
          type: array
          description: Rangos timbrados históricamente a nombre de la empresa.
          items:
            type: object
            properties:
              authorization_date:
                type: string
                format: date
                example: '2026-08-19'
              quantity:
                type: integer
                example: 50
              folio_start:
                type: integer
                example: 539
              folio_end:
                type: integer
                example: 588
              consistent:
                type: boolean
                description: >-
                  `false` cuando la fila del SII no cuadra con su propio rango y
                  la leímos en el orden documentado.
                example: true
        as_of:
          type: string
          format: date-time
          description: Cuándo se leyó del SII. Un número sin esta fecha no dice nada.
          example: '2026-08-27T14:05:00Z'
        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.
  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.