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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

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

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](https://docs.y.uno/es/reference/reporting/report-transactions.md). 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.**

> [!NOTE]
>
> **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](https://docs.y.uno/es/reference/reporting/report-transactions.md). 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](#bin-level-statistics)) y por iniciación `CIT`/`MIT` cuando envías una (consulta [Estadísticas por iniciación](#initiation-level-statistics)), 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

**account\_id** `string (UUID)` *required*

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.

**merchant\_order\_id** `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.

**payment** `object` *required*

El contexto del pago con el que se evalúa la recomendación.

**propiedades**

**amount** `object` *required*

**propiedades**

**currency** `string` *required*

Código de moneda ISO 4217, por ejemplo `USD`.

**value** `number` *required*

Monto de la transacción. Debe ser `≥ 0`.

**country** `string` *required*

Código de país ISO 3166-1 alpha-2, por ejemplo `US`. Selecciona el segmento de estadísticas.

**payment\_method** `object` *required*

**propiedades**

**type** `string` *required*

Por ejemplo `CARD`, `PIX`, `WALLET`. Selecciona el segmento de estadísticas.

**details** `object`

Opcional. `card.bin`: el BIN de la tarjeta, exactamente de **6 u 8 dígitos**. Cuando ese BIN tiene suficiente historial reportado, la clasificación se evalúa con sus propias estadísticas (consulta [Estadísticas por BIN](#bin-level-statistics)); de lo contrario, o para cualquier otro valor, las estadísticas recurren al país y al método de pago.

**initiation** `enum`

Opcional. `CIT` (iniciada por el titular de la tarjeta) o `MIT` (iniciada por el comercio). Cuando la envías, y la misma iniciación tiene suficiente historial reportado en el segmento, la clasificación se evalúa con las estadísticas propias de esa iniciación (consulta [Estadísticas por iniciación](#initiation-level-statistics)); de lo contrario, recurre a todo el segmento. Omítela para clasificar sobre todo el segmento exactamente como antes.

**candidates** `object[]` *required*

Los proveedores a clasificar. Entre **2 y 20** elementos: una recomendación sobre un solo candidato no tiene sentido.

**elemento**

**provider\_id** `string` *required*

Código del proveedor, por ejemplo `ADYEN`, `STRIPE`, `DLOCAL`.

**merchant\_connection\_id** `string`

Opcional. Dato de paso para tu propio registro: se devuelve exactamente como se envió, sin validar.

**optimize\_for** `enum` (default: APPROVAL\_RATE)

El objetivo que optimiza la clasificación. `APPROVAL_RATE` (predeterminado), `LATENCY` o `BALANCED`.

## Respuesta

**recommendation\_id** `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](https://docs.y.uno/es/reference/reporting/report-transactions.md#recommendation-id-for-outcome-attribution) para atribuir el resultado a esta recomendación.

**merchant\_order\_id** `string`

Eco del campo de la solicitud, cuando se proporcionó; `null` en caso contrario.

**optimized\_for** `enum`

El objetivo aplicado a la clasificación.

**decision\_source** `enum`

Cómo se decidió la clasificación: `MERCHANT_HISTORY` o `INSUFFICIENT_DATA` (ver abajo).

**recommended** `object`

El primero de la clasificación. Siempre está presente.

**propiedades**

**provider\_id** `string`

El código del proveedor recomendado.

**merchant\_connection\_id** `string`

El `merchant_connection_id` del candidato, cuando se proporcionó.

**ranking** `object[]`

Todos los candidatos, ordenados según el objetivo.

**elemento**

**provider\_id** `string`

Código del proveedor.

**merchant\_connection\_id** `string`

El `merchant_connection_id` del candidato, cuando se proporcionó.

**approval\_rate** `number`

`SUCCEEDED / (SUCCEEDED + DECLINED)` sobre el historial reportado, `0`–`1`. `null` cuando no hay datos.

**avg\_latency\_ms** `integer`

Latencia promedio de autorización en milisegundos sobre `SUCCEEDED + DECLINED`. `null` cuando no hay datos.

**sample\_size** `integer`

Total de pagos reportados en el segmento durante la ventana, en todos los estados: cuánto historial respalda las métricas de este candidato.

### 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](https://docs.y.uno/es/reference/reporting/report-transactions.md)), 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](https://docs.y.uno/es/reference/reporting/report-transactions.md)), 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

```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl -X POST 'https://api-sandbox.y.uno/v1/routing/recommendations' \
  -H 'public-api-key: <YOUR_PUBLIC_KEY>' \
  -H 'private-secret-key: <YOUR_SECRET_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
    "merchant_order_id": "order_45678",
    "payment": {
      "amount": { "currency": "USD", "value": 99.00 },
      "country": "US",
      "payment_method": { "type": "CARD", "details": { "card": { "bin": "45717360" } } }
    },
    "candidates": [
      { "provider_id": "ADYEN", "merchant_connection_id": "acct-adyen-us-1" },
      { "provider_id": "STRIPE" },
      { "provider_id": "DLOCAL" }
    ],
    "optimize_for": "APPROVAL_RATE"
  }'
```

```json 200 — MERCHANT_HISTORY theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "recommendation_id": "3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d",
  "merchant_order_id": "order_45678",
  "optimized_for": "APPROVAL_RATE",
  "decision_source": "MERCHANT_HISTORY",
  "recommended": { "provider_id": "ADYEN", "merchant_connection_id": "acct-adyen-us-1" },
  "ranking": [
    { "provider_id": "ADYEN",  "merchant_connection_id": "acct-adyen-us-1", "approval_rate": 0.9987, "avg_latency_ms": 180, "sample_size": 767 },
    { "provider_id": "STRIPE", "merchant_connection_id": null, "approval_rate": 0.9167, "avg_latency_ms": 150, "sample_size": 60 },
    { "provider_id": "DLOCAL", "merchant_connection_id": null, "approval_rate": 0.8000, "avg_latency_ms": 210, "sample_size": 60 }
  ]
}
```

```json 200 — INSUFFICIENT_DATA theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "recommendation_id": "7249c858-1f0f-4654-93e7-ebe34bc5048f",
  "merchant_order_id": "order_45678",
  "optimized_for": "APPROVAL_RATE",
  "decision_source": "INSUFFICIENT_DATA",
  "recommended": { "provider_id": "ADYEN", "merchant_connection_id": null },
  "ranking": [
    { "provider_id": "ADYEN",  "merchant_connection_id": null, "approval_rate": null, "avg_latency_ms": null, "sample_size": 0 },
    { "provider_id": "STRIPE", "merchant_connection_id": null, "approval_rate": null, "avg_latency_ms": null, "sample_size": 0 }
  ]
}
```

```json 400 — Too Few Candidates theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "code": "INVALID_PARAMETERS",
  "messages": ["The field 'candidates' has a value less than allowed."]
}
```

## Errores

Los errores devuelven un `code` y un arreglo `messages`.

| HTTP | `code` | Cuándo |
| - | - | - |
| `400` | `INVALID_PARAMETERS` | Cuerpo mal formado, un campo obligatorio ausente, menos de 2 o más de 20 candidatos, un `country`/`currency` que no es ISO, o un enum no válido (`optimize_for`, `initiation`). |
| `400` | `INVALID_ACCOUNT_ID` | `account_id` está mal formado o no pertenece a tu organización. |
| `401` | `INVALID_CREDENTIALS` | Encabezados `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` ausentes o no válidos. |
| `403` | `PRODUCT_NOT_ENABLED` | La API de recomendaciones de enrutamiento no está habilitada para tu organización. Contacta a tu KAM. |
| `502` | `ROUTING_UPSTREAM_ERROR` | No se pudo establecer conexión con el servicio de enrutamiento. |


## OpenAPI

````yaml openapi/es/organizations/routing/get-routing-recommendations.json POST /routing/recommendations
openapi: 3.1.0
info:
  title: Routing API - Recommendations
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /routing/recommendations:
    post:
      summary: Obtener una recomendación de enrutamiento
      description: >-
        Clasifica los proveedores candidatos con el historial de pagos fuera de
        Yuno que la propia cuenta reportó, y devuelve el candidato recomendado
        junto con la clasificación completa. Se habilita por organización.
      operationId: get-routing-recommendations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - payment
                - candidates
              properties:
                account_id:
                  type: string
                  format: uuid
                  example: 7825fc5e-e50a-4248-9ae8-5d3786afb0be
                merchant_order_id:
                  type: string
                  maxLength: 255
                  example: order_45678
                payment:
                  type: object
                  required:
                    - amount
                    - country
                    - payment_method
                  properties:
                    amount:
                      type: object
                      required:
                        - currency
                        - value
                      properties:
                        currency:
                          type: string
                          example: USD
                          description: Código de moneda ISO 4217.
                        value:
                          type: number
                          minimum: 0
                          example: 99
                    country:
                      type: string
                      example: US
                      description: Código de país ISO 3166-1 alpha-2.
                    payment_method:
                      type: object
                      required:
                        - type
                      properties:
                        type:
                          type: string
                          example: CARD
                        details:
                          type: object
                          description: >-
                            Opcional. Detalles del método de pago que refinan el
                            segmento de estadísticas.
                          properties:
                            card:
                              type: object
                              properties:
                                bin:
                                  type: string
                                  description: >-
                                    El BIN de la tarjeta: exactamente 6 u 8
                                    dígitos. Selecciona el segmento de
                                    estadísticas del BIN cuando tiene suficiente
                                    historial reportado en el país del pago
                                    (primero el BIN de 8 dígitos, luego los
                                    primeros 6 dígitos); de lo contrario, la
                                    clasificación recurre a los segmentos de
                                    país y método de pago. Cualquier otro valor
                                    se ignora, nunca se rechaza.
                                  example: '45717360'
                    initiation:
                      type: string
                      enum:
                        - CIT
                        - MIT
                      example: CIT
                candidates:
                  type: array
                  minItems: 2
                  maxItems: 20
                  items:
                    type: object
                    required:
                      - provider_id
                    properties:
                      provider_id:
                        type: string
                        example: ADYEN
                      merchant_connection_id:
                        type: string
                        example: acct-adyen-us-1
                optimize_for:
                  type: string
                  enum:
                    - APPROVAL_RATE
                    - LATENCY
                    - BALANCED
                  default: APPROVAL_RATE
                  example: APPROVAL_RATE
            example:
              account_id: 7825fc5e-e50a-4248-9ae8-5d3786afb0be
              merchant_order_id: order_45678
              payment:
                amount:
                  currency: USD
                  value: 99
                country: US
                payment_method:
                  type: CARD
              candidates:
                - provider_id: ADYEN
                  merchant_connection_id: acct-adyen-us-1
                - provider_id: STRIPE
                - provider_id: DLOCAL
              optimize_for: APPROVAL_RATE
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  recommendation_id:
                    type: string
                    format: uuid
                    example: 3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d
                  merchant_order_id:
                    type: string
                    nullable: true
                    example: order_45678
                  optimized_for:
                    type: string
                    enum:
                      - APPROVAL_RATE
                      - LATENCY
                      - BALANCED
                    example: APPROVAL_RATE
                  decision_source:
                    type: string
                    enum:
                      - MERCHANT_HISTORY
                      - INSUFFICIENT_DATA
                    example: MERCHANT_HISTORY
                  recommended:
                    type: object
                    properties:
                      provider_id:
                        type: string
                        example: ADYEN
                      merchant_connection_id:
                        type: string
                        nullable: true
                        example: acct-adyen-us-1
                  ranking:
                    type: array
                    items:
                      type: object
                      properties:
                        provider_id:
                          type: string
                          example: ADYEN
                        merchant_connection_id:
                          type: string
                          nullable: true
                          example: acct-adyen-us-1
                        approval_rate:
                          type: number
                          nullable: true
                          example: 0.9987
                        avg_latency_ms:
                          type: integer
                          nullable: true
                          example: 180
                        sample_size:
                          type: integer
                          example: 767
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_PARAMETERS
                  messages:
                    type: array
                    items:
                      type: string
                    example:
                      - The field 'candidates' has a value less than allowed.
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_CREDENTIALS
                  messages:
                    type: array
                    items:
                      type: string
                    example:
                      - Invalid Credentials
        '403':
          description: Prohibido
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PRODUCT_NOT_ENABLED
                  messages:
                    type: array
                    items:
                      type: string
                    example:
                      - >-
                        The Routing Recommendations API is enabled per
                        organization. Contact your Key Account Manager (KAM) to
                        activate it.
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ROUTING_UPSTREAM_ERROR
                  messages:
                    type: array
                    items:
                      type: string
                    example:
                      - routing service unavailable.
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
      x-default: <Your PUBLIC-API-KEY>
    sec1:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY
      x-default: <Your PRIVATE-SECRET-KEY>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.