> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coupons.piixan.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Definir una campaña

> Canal y presupuesto (envíos o descuento esperado) que el decisor aplica antes de
aleatorizar (ADR-03).



## OpenAPI

````yaml /openapi/v1.json put /v1/campanas/{campana_id}
openapi: 3.1.0
info:
  contact:
    email: soporte@ejemplo.mx
    name: Soporte del motor de decisión
  description: >-
    Eventos, decisiones, ejecución y lotes. Dinero en MXN sin IVA; fechas en
    UTC.
  title: Piixan Coupons · API de datos
  version: 1.0.0
servers:
  - description: producción
    url: https://api.coupons.piixan.ai
security: []
tags:
  - description: Tokens de corta vida a partir de las credenciales del sistema.
    name: autenticación
  - description: 'Derechos ARCO sobre un cliente seudonimizado: exportar y borrar.'
    name: clientes
  - description: Operaciones de configuración.
    name: configuración
  - description: Decisiones en línea y por lotes, confirmación de ejecución y respaldo.
    name: decisiones
  - description: Publicación de eventos v1 (compras, cupones, altas y bajas).
    name: eventos
paths:
  /v1/campanas/{campana_id}:
    put:
      tags:
        - decisiones
        - configuración
      summary: Definir una campaña
      description: >-
        Canal y presupuesto (envíos o descuento esperado) que el decisor aplica
        antes de

        aleatorizar (ADR-03).
      operationId: campana_v1_campanas__campana_id__put
      parameters:
        - in: path
          name: campana_id
          required: true
          schema:
            title: Campana Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampanaV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: true
                title: Response Campana V1 Campanas  Campana Id  Put
                type: object
          description: Successful Response
        '401':
          content:
            application/json:
              example:
                codigo: no_autenticado
                mensaje: token inválido o caducado
              schema:
                $ref: '#/components/schemas/ErrorV1'
          description: Token ausente, inválido o caducado.
        '403':
          content:
            application/json:
              example:
                codigo: sin_permiso
                mensaje: la credencial no tiene el ámbito decisiones:pedir
              schema:
                $ref: '#/components/schemas/ErrorV1'
          description: La credencial no tiene el ámbito necesario.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '429':
          content:
            application/json:
              example:
                codigo: limite_excedido
                mensaje: límite de ritmo superado
              schema:
                $ref: '#/components/schemas/ErrorV1'
          description: Límite de ritmo o cuota superados; espera `Retry-After`.
          headers:
            Retry-After:
              description: Segundos que hay que esperar antes de reintentar.
              schema:
                minimum: 1
                type: integer
components:
  schemas:
    CampanaV1:
      additionalProperties: false
      description: Cuerpo de `PUT /v1/campanas/{campana_id}`.
      properties:
        canal:
          default: push
          maxLength: 256
          minLength: 1
          title: Canal
          type: string
        descripcion:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Descripcion
        max_descuento_mxn:
          anyOf:
            - description: Importe en MXN sin IVA, con dos decimales, ≥ 0
              maximum: 1000000000
              minimum: 0
              type: number
            - type: 'null'
          description: Presupuesto de descuento esperado
          title: Max Descuento Mxn
        max_envios:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: Presupuesto de envíos del lote
          title: Max Envios
      title: CampanaV1
      type: object
    ErrorV1:
      additionalProperties: false
      description: >-
        Cuerpo uniforme de todas las respuestas 4xx y 5xx. Nunca revela detalles
        internos.
      properties:
        campo:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Ruta del campo que falla, si aplica
          title: Campo
        codigo:
          $ref: '#/components/schemas/CodigoErrorV1'
        detalle:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          title: Detalle
        mensaje:
          maxLength: 512
          title: Mensaje
          type: string
        trace_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Para citar en soporte
          title: Trace Id
      required:
        - codigo
        - mensaje
      title: ErrorV1
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    CodigoErrorV1:
      description: >-
        Catálogo cerrado de errores. La documentación pública lo lista con causa
        y corrección.
      enum:
        - esquema_invalido
        - campo_desconocido
        - ts_fuera_de_rango
        - duplicado
        - no_autenticado
        - sin_permiso
        - no_encontrado
        - limite_excedido
        - idempotencia_conflicto
        - decision_caducada
        - ejecucion_ya_confirmada
        - inquilino_pausado
        - error_interno
      title: CodigoErrorV1
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object

````