Recomendaciones de enrutamiento
Obtener una recomendación de enrutamiento
Envía el contexto del pago y tus proveedores candidatos: Yuno devuelve la ruta recomendada, clasificada según tu propio historial de transacciones reportadas.
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
- Reportas los resultados de tus transacciones fuera de Yuno mediante la API de reporte de transacciones. Solo los pagos con
origin: REPORTEDalimentan las estadísticas: el tráfico procesado por Yuno es una población distinta y se mantiene fuera de forma deliberada. - Antes de enrutar un pago, llamas a este endpoint con el contexto del pago y tus proveedores candidatos.
- 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/MITcuando envías una (consulta Estadísticas por iniciación), y devuelve la clasificación ordenada según tu objetivo. - Enrutas el pago tú mismo y reportas su resultado con el
recommendation_iddevuelto aquí, y Yuno atribuye el resultado a esta recomendación exacta. Si el evento reportado no incluye unrecommendation_id, Yuno recurre al mismomerchant_order_idque enviaste aquí.
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
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.
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.
Los proveedores a clasificar. Entre 2 y 20 elementos: una recomendación sobre un solo candidato no tiene sentido.
El objetivo que optimiza la clasificación.
APPROVAL_RATE (predeterminado), LATENCY o BALANCED.Respuesta
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.Cómo leer la respuesta
recommendedsiempre está presente, incluso sin suficiente historial. Nunca necesitas una rama especial:decision_sourcete 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 elsample_sizede cada candidato para ver cuánto historial lo respalda antes de confiar en el orden.sample_sizees 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
rankingcompleta 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 eventosCARD (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:
- BIN de 8 dígitos: cuando envías 8 dígitos y ese BIN exacto tiene suficiente historial reportado.
- 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).
- País: proveedor, país y método de pago, como sin un BIN.
- Método de pago: proveedor y método de pago en todos los países.
Estadísticas por iniciación
Si reportasinitiation (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 loscandidates 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 unrecommendation_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 uncode y un arreglo messages.
Autorizaciones
Cuerpo
application/json
Respuesta
OK