> ## 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 documentos programados

> Obtiene una lista paginada de documentos programados de una entidad específica. Los documentos programados son plantillas que se ejecutan automáticamente según una frecuencia definida.

## Qué hace

* Obtiene una lista paginada de documentos programados de una entidad específica
* Filtra documentos por estado (active, inactive, completed)
* Filtra por frecuencia de ejecución (daily, weekly, monthly, quarterly)
* Filtra por tipo de DTE
* Proporciona información completa de cada documento programado incluyendo próxima ejecución

## Ejemplos de uso

* Listar todos los documentos programados activos de una entidad
* Consultar documentos programados por frecuencia (mensual, semanal, etc.)
* Verificar cuándo se ejecutará cada documento programado
* Revisar el estado de los documentos programados (activos, pausados, completados)
* Filtrar documentos programados por tipo de DTE

## Endpoints relacionados

* [Crear Documento Programado](/api-reference/scheduled-documents/create) - Crear un nuevo documento programado
* [Obtener Documento Programado](/api-reference/scheduled-documents/get) - Ver detalles de un documento específico
* [Actualizar Documento Programado](/api-reference/scheduled-documents/update) - Modificar un documento programado existente
* [Preview de Documento Programado](/api-reference/scheduled-documents/preview) - Ver preview del próximo documento a emitir
* [Eliminar Documento Programado](/api-reference/scheduled-documents/delete) - Eliminar un documento programado
* [Listar Documentos](/api-reference/documents/list) - Consultar documentos ya emitidos


## OpenAPI

````yaml GET /scheduled-documents
openapi: 3.0.0
info:
  title: Tupana API
  description: API para integración con el sistema Tupana - Facturación Electrónica
  version: 1.0.0
servers:
  - url: https://api.tupana.ai/v1
    description: Servidor de producción
security:
  - apiKeyAuth: []
paths:
  /scheduled-documents:
    get:
      tags:
        - Documentos Programados
      summary: Listar documentos programados
      description: >-
        Obtiene una lista paginada de documentos programados de una entidad
        específica. Los documentos programados son plantillas que se ejecutan
        automáticamente según una frecuencia definida.
      parameters:
        - name: master_entity_id
          in: query
          description: ID de la entidad maestra
          required: true
          schema:
            type: integer
            example: 123
        - name: status
          in: query
          description: Filtrar por estado del documento programado
          required: false
          schema:
            type: string
            enum:
              - active
              - inactive
              - completed
            example: active
        - name: frequency
          in: query
          description: Filtrar por frecuencia de ejecución
          required: false
          schema:
            type: string
            enum:
              - daily
              - weekly
              - monthly
              - quarterly
            example: monthly
        - name: dte_type
          in: query
          description: Filtrar por tipo de DTE
          required: false
          schema:
            type: string
            example: '33'
        - name: page
          in: query
          description: Número de página para paginación
          required: false
          schema:
            type: integer
            default: 1
            example: 1
        - name: page_size
          in: query
          description: Número de elementos por página
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
            example: 20
      responses:
        '200':
          description: Lista de documentos programados obtenida exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledDocumentListResponse'
        '400':
          description: Parámetros inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No autorizado - API Key inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Prohibido - Sin acceso a la entidad
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    ScheduledDocumentListResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total de documentos programados
          example: 25
        next:
          type: string
          nullable: true
          description: URL de la siguiente página
          example: >-
            https://api.tupana.ai/v1/scheduled-documents?master_entity_id=123&page=2
        previous:
          type: string
          nullable: true
          description: URL de la página anterior
          example: null
        results:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledDocument'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
          description: Código de error
          example: VALIDATION_ERROR
          enum:
            - VALIDATION_ERROR
            - AUTHENTICATION_ERROR
            - AUTHORIZATION_ERROR
            - NOT_FOUND
            - SII_ERROR
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error
    ScheduledDocument:
      type: object
      properties:
        id:
          type: integer
          description: ID único del documento programado
          example: 789
        sender:
          type: object
          description: Información de la entidad emisora
          properties:
            id:
              type: integer
              example: 123
            name:
              type: string
              example: Empresa Ejemplo SpA
            rut:
              type: string
              example: 76543210-1
        receiver:
          type: object
          nullable: true
          description: Información de la entidad receptora
          properties:
            id:
              type: integer
              example: 456
            name:
              type: string
              example: Cliente ABC Ltda
            rut:
              type: string
              example: 12345678-9
        dte_type:
          type: object
          description: Tipo de documento tributario
          properties:
            id:
              type: integer
              example: 1
            code:
              type: string
              example: '33'
            description:
              type: string
              example: Factura Electrónica
        frequency:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
            - semiannual
            - yearly
          description: Frecuencia de ejecución
          example: monthly
        frequency_display:
          type: string
          description: Frecuencia en formato legible
          example: Mensual
        day_of_month:
          type: integer
          nullable: true
          description: >-
            Día del mes en que se ejecutará el documento (1-31). Requerido para
            frecuencias: monthly, quarterly, semiannual, yearly. Si el día no
            existe en un mes (ej: 31 en febrero), se usará el último día del
            mes.
          example: 15
        day_of_week:
          type: integer
          nullable: true
          description: Día de la semana para ejecución (1=Lunes, 7=Domingo)
          example: null
        next_execution:
          type: string
          format: date-time
          description: Fecha y hora de la próxima ejecución
          example: '2024-02-15T10:00:00Z'
        status:
          type: string
          enum:
            - active
            - inactive
            - completed
          description: Estado del documento programado
          example: active
        status_display:
          type: string
          description: Estado en formato legible
          example: Activo
        amount:
          type: number
          description: Monto del documento
          example: 100000
        currency:
          type: string
          description: Moneda del documento
          enum:
            - CLP
            - UF
            - USD
            - EUR
          example: CLP
        currency_day:
          type: integer
          nullable: true
          minimum: 1
          maximum: 31
          description: >-
            Día del mes (1-31) para tomar el valor del tipo de cambio. Aplica
            cuando la moneda es UF o USD; si no se indica, se usa el día de
            emisión.
          example: 10
        completed_occurrences:
          type: integer
          description: Número de veces que se ha ejecutado
          example: 5
        max_occurrences:
          type: integer
          nullable: true
          description: Número máximo de ejecuciones
          example: null
        start_date:
          type: string
          format: date
          nullable: true
          description: >-
            Fecha de inicio de la programación (YYYY-MM-DD). Define desde cuándo
            comenzará a ejecutarse el documento programado. Si no se
            proporciona, se usa la fecha actual. La primera ejecución será
            calculada a partir de esta fecha según la frecuencia configurada.
          example: '2024-02-01'
        emission_day_adjustment:
          type: string
          enum:
            - none
            - next
            - previous
          description: >-
            Ajuste de fecha de emisión a días hábiles: 'none' (sin ajuste),
            'next' (próximo día hábil), 'previous' (anterior día hábil)
          default: none
          example: none
        end_type:
          type: string
          enum:
            - never
            - on_date
            - after_occurrences
          description: >-
            Tipo de finalización de la programación: 'never' (nunca finaliza, se
            ejecuta indefinidamente), 'on_date' (finaliza en una fecha
            específica, requiere end_date), 'after_occurrences' (finaliza
            después de un número máximo de ejecuciones, requiere
            max_occurrences). Por defecto: 'never'.
          default: never
          example: never
        end_date:
          type: string
          format: date
          nullable: true
          description: >-
            Fecha de finalización de la programación (YYYY-MM-DD). Solo aplica y
            es requerido si end_type es 'on_date'. El documento programado
            dejará de ejecutarse después de esta fecha.
          example: '2024-12-31'
        details:
          type: array
          description: Detalles/productos del documento
          items:
            $ref: '#/components/schemas/ScheduledDocumentDetail'
        references:
          type: array
          maxItems: 3
          description: >-
            Referencias a documentos (ej. factura anulada por nota de crédito).
            Máximo 3 referencias.
          items:
            $ref: '#/components/schemas/ScheduledDocumentReferenceItem'
        created_at:
          type: string
          format: date-time
          description: Fecha de creación
          example: '2024-01-15T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Fecha de última actualización
          example: '2024-01-20T15:30:00Z'
    ScheduledDocumentDetail:
      type: object
      properties:
        id:
          type: integer
          description: ID único del detalle
          example: 1
        item_name:
          type: string
          description: Nombre del producto o servicio
          example: Servicio mensual de consultoría
        item_description:
          type: string
          description: Descripción del producto o servicio
          example: Consultoría especializada en tecnología
        quantity:
          type: number
          description: Cantidad
          example: 1
        unit_price:
          type: number
          minimum: 0
          description: Precio unitario sin IVA (no puede ser negativo)
          example: 100000
        unit_of_measurement:
          type: string
          description: Unidad de medida
          example: UN
        item_code:
          type: string
          description: >-
            Código del producto o servicio según el sistema del emisor. Este
            código aparece en el documento emitido y puede ser usado para
            identificación interna del producto.
          nullable: true
          example: PROD-001
        item_type_code:
          type: string
          description: >-
            Código de tipo de ítem según clasificación SII. Identifica la
            categoría del producto o servicio (ej: '1' para productos, '2' para
            servicios).
          nullable: true
          example: '1'
    ScheduledDocumentReferenceItem:
      type: object
      description: >-
        Referencia a un documento (ej. para notas de crédito). Máximo 3
        referencias por documento programado.
      properties:
        id:
          type: integer
          description: ID de la referencia (solo en respuesta)
          example: 1
        dte_type_code:
          type: string
          description: 'Código del tipo de DTE del documento referenciado (ej: 33, 61)'
          example: '33'
        reference_folio:
          type: string
          description: Folio del documento referenciado
          example: '123'
        reference_date:
          type: string
          format: date
          description: Fecha del documento referenciado (YYYY-MM-DD)
          example: '2024-01-15'
        reference_reason:
          type: string
          description: >-
            Razón de la referencia. Para notas de crédito totales: 'ANULA
            DOCUMENTO DE LA REFERENCIA'.
          nullable: true
          example: ANULA DOCUMENTO DE LA REFERENCIA
  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)

````