> ## 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 una decisión en línea > Decide para un cliente ahora (menos de 100 ms). Con `Idempotency-Key`, repetir la petición devuelve **la misma decisión** durante 24 horas (ADR-21). Un cliente con una ventana de recompensa abierta recibe «nada» con la decisión abierta (ADR-09). Con el ámbito `explicar:leer`, la respuesta incluye μ por acción en `detalle`. ## OpenAPI ````yaml /openapi/v1.json post /v1/decisiones 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/decisiones: post: tags: - decisiones summary: Pedir una decisión en línea description: >- Decide para un cliente ahora (menos de 100 ms). Con `Idempotency-Key`, repetir la petición devuelve **la misma decisión** durante 24 horas (ADR-21). Un cliente con una ventana de recompensa abierta recibe «nada» con la decisión abierta (ADR-09). Con el ámbito `explicar:leer`, la respuesta incluye μ por acción en `detalle`. operationId: decidir_v1_decisiones_post parameters: - in: header name: Idempotency-Key required: false schema: anyOf: - maxLength: 128 type: string - type: 'null' title: Idempotency-Key requestBody: content: application/json: schema: $ref: '#/components/schemas/PeticionDecisionV1' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RespuestaDecisionV1' 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: PeticionDecisionV1: additionalProperties: false description: >- Cuerpo de `POST /v1/decisiones`. Lleva la cabecera `Idempotency-Key` (ADR-21). properties: cliente_ref: 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}$ title: Cliente Ref type: string contexto: $ref: '#/components/schemas/ContextoDecisionV1' required: - cliente_ref - contexto title: PeticionDecisionV1 type: object RespuestaDecisionV1: additionalProperties: false properties: accion: description: 0 = nada; el resto, ids del catálogo title: Accion accion_nombre: title: Accion Nombre caduca_en: description: Después de esta fecha no se admite la confirmación de ejecución title: Caduca En decision_id: title: Decision Id detalle: {} en_control: title: En Control en_respaldo: description: True si el motor no decidió y respondió «usa tu regla» title: En Respaldo en_sombra: description: >- True en modo sombra: el motor solo sugiere. Aplica tu regla como siempre, etiqueta el cupón que mandes con este decision_id y confirma con accion_real title: En Sombra explorado: title: Explorado motivo: description: >- Explicación breve, p. ej. «margen esperado +8.40 MXN frente a no mandar» title: Motivo politica_version: title: Politica Version propension: description: Probabilidad de esta acción bajo la política que decidió title: Propension required: - decision_id - accion - accion_nombre - propension - politica_version - explorado - en_control - en_respaldo - caduca_en - motivo title: RespuestaDecisionV1 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 ContextoDecisionV1: additionalProperties: false properties: acciones_permitidas: anyOf: - items: type: integer type: array - type: 'null' description: >- Subconjunto de ids del catálogo que el sistema puede ejecutar ahora; «nada» (0) siempre está title: Acciones Permitidas campana_id: anyOf: - maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9][A-Za-z0-9_.:\-]{0,127}$ type: string - type: 'null' title: Campana Id canal: description: >- Canal por el que se ejecutará la acción: sms, email, push, app, caja… maxLength: 256 minLength: 1 title: Canal type: string required: - canal title: ContextoDecisionV1 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 ````