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

# Listar pedidos de timbraje

> Pedidos de timbraje de la entidad, del más reciente al más antiguo.



## OpenAPI

````yaml api-reference/openapi-v2.json GET /folio-requests/
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-requests/:
    get:
      tags:
        - Folios
      summary: Listar pedidos de timbraje
      description: Pedidos de timbraje de la entidad, del más reciente al más antiguo.
      operationId: listFolioRequests_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
          description: >-
            Filtra por ambiente. Si se omite, se listan los de los DOS
            ambientes: es lo que necesita un cliente que está migrando de uno a
            otro.
      responses:
        '200':
          description: Listado de pedidos
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FolioRequest'
                  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
      security:
        - apiKeyAuth: []
components:
  schemas:
    FolioRequest:
      type: object
      description: Pedido de timbraje de folios ante el SII.
      properties:
        id:
          type: string
          example: fir_8d4a2f7c1e9b5
        dte_type:
          type: integer
          description: Tipo de documento timbrado.
          example: 33
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - authorized_without_caf
          description: >-
            `authorized_without_caf` significa que el SII autorizó el rango y no
            entregó el archivo: esos folios ya salieron de tu stock.
          example: completed
        requested_quantity:
          type: integer
          description: Folios que pediste.
          example: 50
        granted_quantity:
          type: integer
          nullable: true
          description: >-
            Folios que el SII autorizó. Puede ser menor al pedido: el tope por
            solicitud lo pone el SII y sube con el uso.
          example: 50
        partially_granted:
          type: boolean
          description: >-
            `true` cuando el SII entregó menos folios de los que pediste. Es un
            desenlace normal: el tope por solicitud lo fija el SII y sube con el
            uso de la empresa.
          example: true
        sii_max_per_request:
          type: integer
          nullable: true
          description: >-
            Tope por solicitud que el SII publicó al hacer este trámite: el
            motivo por el que se entregó menos de lo pedido.
          example: 9
        folio_start:
          type: integer
          nullable: true
          example: 539
        folio_end:
          type: integer
          nullable: true
          example: 588
        caf_xml:
          type: string
          nullable: true
          description: >-
            CAF entregado por el SII. Contiene la llave privada con la que se
            firman tus DTE: trátalo como secreto. Es `null` hasta que el pedido
            queda `completed`.
          example: <AUTORIZACION><CAF version="1.0">…</CAF></AUTORIZACION>
        idempotency_key:
          type: string
          description: La clave que enviaste al crear el pedido.
          example: pedido-facturas-2026-08-27-01
        error:
          type: string
          description: Motivo del SII cuando el pedido no terminó bien.
          example: ''
        created_at:
          type: string
          format: date-time
          example: '2026-08-27T14:30:00Z'
        completed_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-08-27T14:32:11Z'
        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
  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.