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

# Actualizar documento programado

> Actualiza parcialmente un documento programado existente.

## Qué hace

* Actualiza parcialmente un documento programado existente
* Permite modificar solo los campos que se desean cambiar (PATCH)
* Actualiza la configuración de frecuencia, estado, montos o detalles
* Recalcula automáticamente la próxima ejecución si se cambia la frecuencia
* Mantiene la integridad del documento programado

## Ejemplos de uso

* Cambiar la frecuencia de ejecución de un documento programado
* Pausar o reactivar un documento programado (cambiar estado)
* Actualizar montos o productos/servicios del documento
* Modificar el día de ejecución (día del mes o día de la semana)
* Cambiar el número máximo de ejecuciones permitidas

## 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 del documento antes de actualizar
* [Crear Documento Programado](/api-reference/scheduled-documents/create) - Crear un nuevo documento programado
* [Preview de Documento Programado](/api-reference/scheduled-documents/preview) - Ver preview del documento actualizado
* [Listar Documentos](/api-reference/documents/list) - Consultar documentos ya emitidos


## OpenAPI

````yaml PATCH /scheduled-documents/{id}
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/{id}:
    patch:
      tags:
        - Documentos Programados
      summary: Actualizar documento programado
      description: Actualiza parcialmente un documento programado existente.
      operationId: updateScheduledDocument
      parameters:
        - name: id
          in: path
          description: ID del documento programado
          required: true
          schema:
            type: integer
            example: 789
        - name: master_entity_id
          in: query
          description: ID de la entidad maestra
          required: true
          schema:
            type: integer
            example: 123
      requestBody:
        description: Campos a actualizar del documento programado
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledDocumentUpdate'
            example:
              status: inactive
              amount: 120000
              currency_day: 15
              references:
                - dte_type_code: '33'
                  reference_folio: '100'
                  reference_date: '2024-01-15'
                  reference_reason: ANULA DOCUMENTO DE LA REFERENCIA
              details:
                - item_name: Servicio actualizado
                  item_description: Descripción del servicio
                  quantity: 1
                  unit_price: 120000
        required: true
      responses:
        '200':
          description: Documento programado actualizado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledDocument'
        '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'
        '404':
          description: Documento programado no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    ScheduledDocumentUpdate:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - inactive
          description: Estado del documento programado
          example: inactive
        amount:
          type: number
          description: Monto total del documento
          minimum: 0
          example: 120000
        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: weekly
        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: 20
        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: 2
        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. 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).
          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).
          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'
        max_occurrences:
          type: integer
          nullable: true
          description: >-
            Número máximo de ejecuciones. Solo aplica y es requerido si end_type
            es 'after_occurrences'. El documento programado dejará de ejecutarse
            después de alcanzar este número de ejecuciones.
          minimum: 1
          example: 24
        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. Si se envía, reemplaza todas las referencias
            existentes.
          items:
            $ref: '#/components/schemas/ScheduledDocumentReferenceItem'
        details:
          type: array
          description: >-
            Detalles/productos del documento. Si se envía, reemplaza todos los
            detalles existentes. Misma estructura que en creación.
          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)

````