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

# Pedir un lote de decisiones

> Una campaña entera. Un trabajo en curso por inquilino. Al terminar, el resultado
(JSONL, una decisión por línea) se sirve en `/v1/lotes-decision/{job_id}/resultado`
y se avisa por webhook `lote.completado` firmado.



## OpenAPI

````yaml /openapi/v1.json post /v1/lotes-decision
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/lotes-decision:
    post:
      tags:
        - decisiones
      summary: Pedir un lote de decisiones
      description: >-
        Una campaña entera. Un trabajo en curso por inquilino. Al terminar, el
        resultado

        (JSONL, una decisión por línea) se sirve en
        `/v1/lotes-decision/{job_id}/resultado`

        y se avisa por webhook `lote.completado` firmado.
      operationId: crear_lote_v1_lotes_decision_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeticionLoteDecisionV1'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespuestaLoteDecisionV1'
          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:
    PeticionLoteDecisionV1:
      additionalProperties: false
      description: |-
        Cuerpo de `POST /v1/lotes-decision`.

        Se pasa la lista de clientes o un segmento, no los dos.
      properties:
        campana_id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:\-]{0,127}$
          title: Campana Id
          type: string
        clientes:
          anyOf:
            - items:
                description: >-
                  Identificador seudonimizado del cliente (hash con sal del
                  inquilino)
                maxLength: 128
                minLength: 8
                pattern: ^[A-Za-z0-9][A-Za-z0-9_.:\-]{0,127}$
                type: string
              maxItems: 500000
              minItems: 1
              type: array
            - type: 'null'
          title: Clientes
        segmento:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Filtro sobre las características a mano, p. ej.
            {"dias_desde_ultima_compra": {"<=": 90}}
          title: Segmento
      required:
        - campana_id
      title: PeticionLoteDecisionV1
      type: object
    RespuestaLoteDecisionV1:
      additionalProperties: false
      properties:
        creado_en:
          description: >-
            ISO-8601 con zona horaria; el motor la guarda y la devuelve en UTC
            (Z)
          title: Creado En
        estado: {}
        job_id:
          title: Job Id
        resultado_url:
          description: URL firmada del fichero de decisiones cuando está completado
          title: Resultado Url
      required:
        - job_id
        - estado
        - creado_en
      title: RespuestaLoteDecisionV1
      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

````