> ## 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 tasas de cambio

> Consulta la tasa de cambio diaria oficial de Yuno, la misma referencia que Yuno usa en sus propios reportes, para que tus precios y tu conciliación coincidan con los nuestros.

Los comercios que venden a través de fronteras necesitan una única tasa de referencia para fijar precios en una moneda y conciliar en otra. Este endpoint devuelve la **tasa de cambio diaria oficial de Yuno**, la misma referencia que Yuno usa en sus propios reportes, expresada como **unidades de la moneda por 1 USD**.

Se publican alrededor de 161 monedas por día. `USD` se publica con una tasa de `1`.

> [!NOTE]
>
> **Habilitado por organización**
>
> Esta API requiere activación para tu organización. Contacta a tu Key Account Manager (KAM) para habilitarla.

## Qué es y qué no es

Esta es una **tasa de referencia**, publicada una vez por día para un día cerrado. Yuno no se compromete a procesar ni liquidar a esta tasa.

* Es de solo lectura: sin cotizaciones, sin bloqueo de tasa, sin conversión aplicada a un pago.
* No es una tasa en vivo ni intradía. El valor de un día es final una vez que se cierra la carga diaria.
* Para convertir una transacción real en el checkout, usa [Conversion Rate](https://docs.y.uno/es/reference/conversion-rate/get-conversion-rate.md). Es un producto distinto: una cotización de un proveedor para una transacción.

## Elegir qué solicitas

Todos los parámetros son opcionales, y la forma de la respuesta depende de lo que envíes:

| Envías | Obtienes |
| - | - |
| Nada | El último día disponible, todas las monedas. |
| `currency=COP` | El último día disponible, solo esa moneda. |
| `start_date=2026-09-28` | Ese día, todas las monedas. |
| `start_date=2026-09-28&end_date=2026-09-30` | Ese rango, todas las monedas. |
| `start_date=…&currency=COP` | El día o el rango, solo esa moneda. |

`end_date` es el único parámetro con un complemento: no se puede usar sin `start_date`. Todo lo demás funciona por sí solo.

**Límites del rango:** hasta 31 días cuando se omite `currency`, y hasta 366 días cuando solicitas una sola moneda.

### El último día disponible

Sin fechas, obtienes el día publicado más reciente en lugar de una fecha que tengas que calcular. El día actual nunca se entrega, porque su valor no es final hasta que se cierra la carga diaria, así que el día más nuevo que puedes recibir es ayer (UTC).

Si una carga diaria se retrasa, esta también es la forma segura de consultar: recibes el día más nuevo que realmente existe en lugar de una respuesta vacía para un día que nunca se publicó.

## Cómo leer la respuesta

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "base_currency": "USD",
  "rates": [
    { "fx_date": "2026-09-28", "currency": "BRL", "rate": 5.3214 },
    { "fx_date": "2026-09-28", "currency": "COP", "rate": 3306.859716727782946 },
    { "fx_date": "2026-09-28", "currency": "USD", "rate": 1 }
  ]
}
```

Tres reglas se cumplen en toda respuesta:

1. **Ordenada** por `fx_date` y luego por `currency`.
2. **Un valor por moneda por día.** Cuando existe más de una fuente para un día, el desempate ocurre dentro de Yuno y no forma parte de este contrato.
3. **Lo que no existe simplemente está ausente.** Un día o una moneda sin tasa publicada no aparece en `rates`, y un rango sin nada publicado devuelve `200` con un arreglo vacío, no un error. Trata un `rates` vacío como "no hay nada publicado para lo que pediste", nunca como una falla.

> [!WARNING]
>
> **Interpreta `rate` con un tipo decimal.**
>
> Las tasas tienen hasta 15 decimales. `3306.859716727782946` leído como double se convierte en `3306.859716727783`, y la diferencia aparecerá en la conciliación. Usa el tipo decimal o de números grandes de tu lenguaje, no un float: `BigDecimal` en Java, `decimal.Decimal` en Python, `shopspring/decimal` en Go, una librería decimal en JavaScript en lugar de solo `JSON.parse`.

### Códigos de moneda

Los códigos son en su mayoría ISO 4217, pero el conjunto publicado también incluye códigos que no son monedas fiduciarias, como `BTC`, `XAU` (oro) y `XAG` (plata). Un código bien formado que Yuno no publica no es un error: se devuelve como un arreglo `rates` vacío.

## Almacenamiento en caché

Un día publicado nunca cambia, por lo que una respuesta de un día pasado se puede almacenar en caché indefinidamente. Consultar sin fechas es la única solicitud cuya respuesta cambia, una vez por día.

## Errores

Los errores devuelven un `code` y un arreglo `messages`. El mensaje nombra el parámetro con el problema.

| HTTP | `code` | Cuándo |
| - | - | - |
| 400 | `INVALID_PARAMETERS` | `end_date` enviado sin `start_date`; una fecha que no es `YYYY-MM-DD` o que no existe; `end_date` anterior a `start_date`; `end_date` posterior a ayer (UTC); un rango que excede el límite; un `currency` que no tiene tres letras. |
| 401 | `NOT_AUTHENTICATED` / `INVALID_CREDENTIALS` | Faltan los encabezados `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` o no son válidos. |
| 403 | `PRODUCT_NOT_ENABLED` | "The FX Rates API is enabled per organization. Contact your Key Account Manager (KAM) to activate it." |
| 503 | `SERVICE_UNAVAILABLE` | La fuente de tasas no está disponible temporalmente. Reintenta; los datos no cambian. |


## OpenAPI

````yaml openapi/es/fx-rates/get-fx-rates.json GET /fx-rates
openapi: 3.1.0
info:
  title: Yuno FX Rates API
  version: '1.0'
servers:
  - url: https://api-sandbox.y.uno/v1
  - url: https://api.y.uno/v1
security: []
paths:
  /fx-rates:
    get:
      summary: Obtener tipos de cambio
      description: >-
        Devuelve el tipo de cambio diario oficial de Yuno para una moneda o para
        todas, expresado en unidades de la moneda por 1 USD. Sin fechas,
        devuelve el último día disponible.
      operationId: getFxRates
      parameters:
        - in: header
          name: PUBLIC-API-KEY
          schema:
            type: string
          description: Tu clave de API pública.
        - in: header
          name: PRIVATE-SECRET-KEY
          schema:
            type: string
          description: Tu clave secreta privada. Nunca la expongas del lado del cliente.
        - in: query
          name: start_date
          required: false
          schema:
            type: string
            format: date
            example: '2026-09-28'
          description: >-
            Primer día del rango, inclusive, como `YYYY-MM-DD`. Omítelo para
            obtener el último día disponible.
        - in: query
          name: end_date
          required: false
          schema:
            type: string
            format: date
            example: '2026-09-30'
          description: >-
            Último día del rango, inclusive, como `YYYY-MM-DD`. Solo es válido
            junto con `start_date`, toma ese valor por defecto y no puede ser
            posterior a ayer (UTC).
        - in: query
          name: currency
          required: false
          schema:
            type: string
            minLength: 3
            maxLength: 3
            example: COP
          description: >-
            Un código de moneda de 3 letras. Omítelo para obtener todas las
            monedas publicadas en esos días.
      responses:
        '200':
          description: 'OK: los tipos de cambio publicados para los días solicitados.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  base_currency:
                    type: string
                    description: >-
                      Siempre `USD` en esta versión. Es explícito para que la
                      lectura no sea ambigua.
                    example: USD
                  rates:
                    type: array
                    items:
                      type: object
                      properties:
                        fx_date:
                          type: string
                          format: date
                          description: Día para el que se publica el tipo de cambio.
                          example: '2026-09-28'
                        currency:
                          type: string
                          description: >-
                            Código de moneda de 3 letras. En su mayoría ISO
                            4217; el conjunto publicado también incluye códigos
                            que no son monedas fiduciarias, como `BTC`, `XAU` y
                            `XAG`.
                          example: COP
                        rate:
                          type: number
                          description: >-
                            Unidades de esta moneda por 1 unidad de
                            `base_currency`, con hasta 15 decimales. `USD` se
                            publica con una tasa de 1. Procésalo con un tipo
                            decimal: un double lo redondea sin avisar.
                          example: 3306.859716727783
              examples:
                one_day_every_currency:
                  summary: One day, every currency
                  value:
                    base_currency: USD
                    rates:
                      - fx_date: '2026-09-28'
                        currency: BRL
                        rate: 5.3214
                      - fx_date: '2026-09-28'
                        currency: COP
                        rate: 3306.859716727783
                      - fx_date: '2026-09-28'
                        currency: USD
                        rate: 1
                no_rate_published:
                  summary: A day with no published rate
                  value:
                    base_currency: USD
                    rates: []
        '400':
          description: >-
            Solicitud incorrecta: `INVALID_PARAMETERS` (a un parámetro de
            consulta le falta su complemento, tiene un formato incorrecto o está
            fuera de rango).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                end_date_without_start_date:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The query parameter 'end_date' can only be used together
                        with 'start_date'.
                end_date_after_yesterday:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The query parameter 'end_date' must not be later than
                        yesterday (UTC).
                range_over_the_limit:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The range between 'start_date' and 'end_date' must not
                        exceed 31 days when 'currency' is omitted.
        '403':
          description: >-
            Prohibido: `PRODUCT_NOT_ENABLED` (el producto no está habilitado
            para tu organización).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                product_not_enabled:
                  value:
                    code: PRODUCT_NOT_ENABLED
                    messages:
                      - >-
                        The FX Rates API is enabled per organization. Contact
                        your Key Account Manager (KAM) to activate it.
        '503':
          description: >-
            Servicio no disponible: `SERVICE_UNAVAILABLE` (la fuente de los
            tipos de cambio no está disponible temporalmente).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                service_unavailable:
                  value:
                    code: SERVICE_UNAVAILABLE
                    messages:
                      - >-
                        The FX rates service is temporarily unavailable, please
                        retry.

````

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