Saltar al contenido principal
POST
Obtener una recomendación de enrutamiento
Este endpoint recomienda a cuál de tus propias cuentas de proveedor enrutar un pago, según el historial de resultados que envías a Yuno mediante la API de reporte de transacciones. Envías el contexto del pago y los candidatos que realmente puedes usar; Yuno devuelve el candidato recomendado, una clasificación completa con métricas por candidato y un recommendation_id. La transacción en sí nunca pasa por Yuno. Yuno recomienda; tú decides y procesas.
Se habilita por organización: esta API requiere activación para tu organización. Contacta a tu Key Account Manager (KAM) para habilitarla. Hasta entonces, cada llamada devuelve 403 PRODUCT_NOT_ENABLED.

Cómo funciona

  1. Reportas los resultados de tus transacciones fuera de Yuno mediante la API de reporte de transacciones. Solo los pagos con origin: REPORTED alimentan las estadísticas: el tráfico procesado por Yuno es una población distinta y se mantiene fuera de forma deliberada.
  2. Antes de enrutar un pago, llamas a este endpoint con el contexto del pago y tus proveedores candidatos.
  3. Yuno calcula estadísticas por candidato (tasa de aprobación, latencia promedio del proveedor, tamaño de muestra) sobre una ventana móvil de 30 días de tus pagos reportados, segmentadas por proveedor, país y método de pago, por BIN de la tarjeta cuando envías uno (consulta Estadísticas por BIN) y por iniciación CIT/MIT cuando envías una (consulta Estadísticas por iniciación), y devuelve la clasificación ordenada según tu objetivo.
  4. Enrutas el pago tú mismo y reportas su resultado con el recommendation_id devuelto aquí, y Yuno atribuye el resultado a esta recomendación exacta. Si el evento reportado no incluye un recommendation_id, Yuno recurre al mismo merchant_order_id que enviaste aquí.
Solo los pagos reportados en un estado terminal alimentan la tasa de aprobación: SUCCEEDED cuenta como aprobado y SUCCEEDED + DECLINED como decidido. Los pagos en cualquier otro estado (por ejemplo, ERROR, pendiente) se ignoran para la tasa y la latencia, aunque igualmente cuentan para sample_size.

Cuerpo de la solicitud

string (UUID)
requerido
La cuenta del comercio para la que se emite la recomendación. Viaja en el cuerpo; Yuno la convierte internamente en el encabezado de cuenta. Debe pertenecer a la organización de las credenciales de la API.
string
Referencia de orden opcional proporcionada por el comercio (máx. 255). Se almacena con la recomendación emitida como clave de correlación para la atribución de ciclo cerrado.
object
requerido
El contexto del pago con el que se evalúa la recomendación.
object[]
requerido
Los proveedores a clasificar. Entre 2 y 20 elementos: una recomendación sobre un solo candidato no tiene sentido.
enum
predeterminado:"APPROVAL_RATE"
El objetivo que optimiza la clasificación. APPROVAL_RATE (predeterminado), LATENCY o BALANCED.

Respuesta

string
Identificador único de la recomendación emitida, un UUID v4 en minúsculas. Se genera un id nuevo en cada llamada. Envíalo de vuelta como recommendation_id en el evento reportado para atribuir el resultado a esta recomendación.
string
Eco del campo de la solicitud, cuando se proporcionó; null en caso contrario.
enum
El objetivo aplicado a la clasificación.
enum
Cómo se decidió la clasificación: MERCHANT_HISTORY o INSUFFICIENT_DATA (ver abajo).
El primero de la clasificación. Siempre está presente.
object[]
Todos los candidatos, ordenados según el objetivo.

Cómo leer la respuesta

  • recommended siempre está presente, incluso sin suficiente historial. Nunca necesitas una rama especial: decision_source te indica cuánto confiar en ella.
  • decision_source: MERCHANT_HISTORY: al menos un candidato alcanzó la muestra mínima; la clasificación refleja estadísticas reales sobre tus pagos reportados.
  • decision_source: INSUFFICIENT_DATA: ningún candidato alcanzó la muestra mínima de eventos reportados recientes. La clasificación completa igualmente se devuelve, y la recomendación recurre a los mejores datos disponibles o, como último recurso, al orden de la solicitud. Lee el sample_size de cada candidato para ver cuánto historial lo respalda antes de confiar en el orden.
  • sample_size es la honestidad de la recomendación. Una tasa de aprobación alta sobre 12 eventos no es la misma señal que sobre 12,000.
  • La ranking completa siempre se devuelve, ordenada según tu objetivo. Si el candidato recomendado rechaza el pago, toma la siguiente entrada: reintento en cascada sin una segunda llamada.

Estadísticas por BIN

Si reportas el BIN de la tarjeta en tus eventos CARD (payment_method_details.card.bin en la API de reporte de transacciones), envía el mismo BIN aquí en payment.payment_method.details.card.bin. Para cada candidato, la clasificación usa el segmento más específico que alcanza la muestra mínima, en el país del pago:
  1. BIN de 8 dígitos: cuando envías 8 dígitos y ese BIN exacto tiene suficiente historial reportado.
  2. BIN de 6 dígitos: los primeros 6 dígitos (también el segmento que se usa cuando envías un BIN de 6 dígitos).
  3. País: proveedor, país y método de pago, como sin un BIN.
  4. Método de pago: proveedor y método de pago en todos los países.
Un BIN sin historial reportado simplemente pasa a los segmentos de país y método de pago: la respuesta es exactamente la que obtendrías sin enviarlo. Un valor que no tenga exactamente 6 u 8 dígitos se ignora, nunca se rechaza.

Estadísticas por iniciación

Si reportas initiation (CIT o MIT) en tus eventos (en la API de reporte de transacciones), envía el mismo payment.initiation aquí. CIT y MIT se aprueban de forma muy distinta según el proveedor, por lo que, en cada nivel de segmento anterior, la clasificación primero prueba el historial con la misma iniciación y solo si este no alcanza la muestra mínima usa el nivel completo. El orden efectivo es: BIN8 + iniciación → BIN8 → BIN6 + iniciación → BIN6 → país + iniciación → país → método de pago + iniciación → método de pago. Los eventos que reportaste sin iniciación cuentan solo en las estadísticas sin iniciación (nivel completo). Una solicitud sin payment.initiation se evalúa sobre todo el segmento, exactamente como antes de usar este campo: la respuesta no cambia. approval_rate, avg_latency_ms y sample_size siempre reflejan el segmento realmente usado.

Elegir un objetivo

optimize_for ordena la clasificación: APPROVAL_RATE (predeterminado), LATENCY o BALANCED (una combinación ponderada de ambos). Todavía no hay un objetivo de costo: la API de reporte no recopila comisiones, y Yuno no clasifica con datos que no tiene. LATENCY y BALANCED clasifican según el latency_ms que reportas en cada evento. Si tus eventos reportados no incluyen latency_ms, no hay latencia sobre la cual clasificar: LATENCY devuelve los candidatos en el orden de la solicitud, y BALANCED pondera solo la tasa de aprobación. Reporta latency_ms (el tiempo de ida y vuelta del proveedor tal como lo mediste) para usar cualquiera de los dos objetivos.

Los candidatos son tu capa de restricciones

La recomendación siempre es uno de los candidates que envías: Yuno nunca propone un proveedor que no incluiste. Envía solo los proveedores que este pago realmente puede usar (elegibilidad, contratos, volúmenes comprometidos), y la recomendación respeta esas restricciones por construcción.

Reintentos

No hay encabezado de idempotencia en este endpoint, y no se necesita: cada llamada calcula una recomendación nueva con un recommendation_id nuevo, y solicitar una recomendación no cambia ningún estado. Reintentar tras una falla de red siempre es seguro.

Ejemplos

Errores

Los errores devuelven un code y un arreglo messages.

Autorizaciones

PUBLIC-API-KEY
string
header
predeterminado:<Your PUBLIC-API-KEY>
requerido
PRIVATE-SECRET-KEY
string
header
predeterminado:<Your PRIVATE-SECRET-KEY>
requerido

Cuerpo

application/json
account_id
string<uuid>
requerido
Ejemplo:

"7825fc5e-e50a-4248-9ae8-5d3786afb0be"

payment
object
requerido
candidates
object[]
requerido
Required array length: 2 - 20 elements
merchant_order_id
string
Maximum string length: 255
Ejemplo:

"order_45678"

optimize_for
enum<string>
predeterminado:APPROVAL_RATE
Opciones disponibles:
APPROVAL_RATE,
LATENCY,
BALANCED
Ejemplo:

"APPROVAL_RATE"

Respuesta

OK

recommendation_id
string<uuid>
Ejemplo:

"3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d"

merchant_order_id
string | null
Ejemplo:

"order_45678"

optimized_for
enum<string>
Opciones disponibles:
APPROVAL_RATE,
LATENCY,
BALANCED
Ejemplo:

"APPROVAL_RATE"

decision_source
enum<string>
Opciones disponibles:
MERCHANT_HISTORY,
INSUFFICIENT_DATA
Ejemplo:

"MERCHANT_HISTORY"

ranking
object[]