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

# Crear documento programado

> Crea un nuevo documento programado que se ejecutará automáticamente según la frecuencia especificada.

## Qué hace

* Crea un nuevo documento programado que se ejecutará automáticamente según la frecuencia especificada
* Permite definir la frecuencia de ejecución (diaria, semanal, mensual, trimestral)
* Configura automáticamente la próxima ejecución según la frecuencia
* Busca o crea automáticamente el receptor si no existe
* Establece el estado inicial del documento programado (activo o inactivo)

## Ejemplos de uso

* Crear facturas recurrentes mensuales a clientes específicos
* Programar servicios de suscripción que se facturen automáticamente
* Automatizar facturación de servicios periódicos (consulta, mantenimiento, etc.)
* Configurar facturas trimestrales para reportes o servicios continuos
* Establecer documentos programados que se ejecuten diariamente

## Endpoints relacionados

* [Listar Documentos Programados](/api-reference/scheduled-documents/list) - Ver todos los documentos programados
* [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
* [Listar Documentos](/api-reference/documents/list) - Consultar documentos ya emitidos


## OpenAPI

````yaml POST /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:
    post:
      tags:
        - Documentos Programados
      summary: Crear documento programado
      description: >-
        Crea un nuevo documento programado que se ejecutará automáticamente
        según la frecuencia especificada.
      operationId: createScheduledDocument
      requestBody:
        description: Datos del documento programado a crear
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledDocumentCreate'
            example:
              sender: 123
              dte_type: '33'
              receiver_tax_id: 76111111-1
              frequency: monthly
              day_of_month: 10
              currency: CLP
              currency_day: 10
              status: active
              references:
                - dte_type_code: '33'
                  reference_folio: '100'
                  reference_date: '2024-01-15'
                  reference_reason: ANULA DOCUMENTO DE LA REFERENCIA
              details:
                - item_name: Servicio mensual de consultoría
                  item_description: Asistencia contable mensual
                  quantity: 1
                  unit_price: 150000
        required: true
      responses:
        '201':
          description: Documento programado creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledDocument'
              example:
                id: 987
                sender:
                  id: 123
                  name: Empresa Ejemplo SpA
                  rut: 76543210-1
                receiver:
                  id: 456
                  name: Cliente ABC Ltda
                  rut: 12345678-9
                dte_type:
                  id: 1
                  code: '33'
                  description: Factura Electrónica
                frequency: monthly
                frequency_display: Mensual
                day_of_month: 10
                day_of_week: null
                next_execution: '2024-03-10T10:00:00Z'
                status: active
                status_display: Activo
                amount: 150000
                currency: CLP
                currency_day: 10
                completed_occurrences: 0
                max_occurrences: null
                references:
                  - id: 1
                    dte_type_code: '33'
                    reference_folio: '100'
                    reference_date: '2024-01-15'
                    reference_reason: ANULA DOCUMENTO DE LA REFERENCIA
                details:
                  - id: 1
                    item_name: Servicio mensual de consultoría
                    item_description: Asistencia contable mensual
                    quantity: 1
                    unit_price: 150000
                created_at: '2024-02-05T12:15:00Z'
                updated_at: '2024-02-05T12:15:00Z'
        '400':
          description: Datos 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'
        '422':
          description: Error de validación en el SII
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    ScheduledDocumentCreate:
      type: object
      required:
        - sender
        - dte_type
        - frequency
        - details
        - receiver_tax_id
      properties:
        sender:
          type: integer
          description: ID de la entidad maestra emisora (obligatorio)
          example: 123
        dte_type:
          type: string
          description: 'Código del tipo de DTE (ej: ''33'' para Factura Electrónica)'
          example: '33'
        receiver_tax_id:
          type: string
          description: >-
            RUT del receptor (formato: 12345678-9). El sistema buscará un
            cliente existente con este RUT. Si no existe, creará uno nuevo
            automáticamente. Campo requerido.
          example: 12345678-9
        frequency:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - quarterly
            - semiannual
            - yearly
          description: >-
            Frecuencia de ejecución del documento programado. Valores: 'daily'
            (diario), 'weekly' (semanal), 'monthly' (mensual), 'quarterly'
            (trimestral), 'semiannual' (semestral), 'yearly' (anual).
          example: monthly
        day_of_month:
          type: integer
          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.
          minimum: 1
          maximum: 31
          example: 15
        day_of_week:
          type: integer
          description: >-
            Día de la semana en que se ejecutará el documento (1=Lunes,
            2=Martes, 3=Miércoles, 4=Jueves, 5=Viernes, 6=Sábado, 7=Domingo).
            Requerido para frecuencia semanal (weekly).
          minimum: 1
          maximum: 7
          example: 1
        start_date:
          type: string
          format: date
          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. Si la fecha calculada cae
            en fin de semana o feriado, se ajusta según esta opción: 'none' (sin
            ajuste, emite en la fecha calculada aunque sea fin de semana),
            'next' (ajusta al próximo día hábil), 'previous' (ajusta al anterior
            día hábil). Por defecto: 'none'.
          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
          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'
        currency:
          type: string
          description: Moneda del documento
          enum:
            - CLP
            - UF
            - USD
            - EUR
          default: CLP
          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 (UF o
            USD). Si no se indica, se usa el día de emisión.
          example: 10
        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'
        status:
          type: string
          enum:
            - active
            - inactive
          description: Estado inicial del documento programado
          default: active
          example: active
        max_occurrences:
          type: integer
          description: >-
            Número máximo de ejecuciones (opcional, null = infinito). Solo
            aplica si end_type es 'after_occurrences'.
          minimum: 1
          example: 12
        details:
          type: array
          description: Detalles/productos del documento
          minItems: 1
          items:
            $ref: '#/components/schemas/ScheduledDocumentDetailCreate'
    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'
    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
    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
    ScheduledDocumentDetailCreate:
      type: object
      required:
        - item_name
        - quantity
        - unit_price
      properties:
        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 (opcional)
          example: Consultoría especializada en tecnología
        quantity:
          type: number
          description: Cantidad
          minimum: 0.01
          example: 1
        unit_price:
          type: number
          minimum: 0
          description: Precio unitario sin IVA (no puede ser negativo)
          example: 100000
        unit:
          type: string
          description: Unidad de medida (opcional). Para UF/USD se asigna automáticamente.
          example: UN
        item_code:
          type: string
          description: Código del ítem
          nullable: true
          example: PROD-001
        item_type_code:
          type: string
          description: Código de tipo de ítem
          nullable: true
          example: '1'
    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'
  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)

````