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

# Monedas y tasas de cambio (v2)

> Consultar la moneda base, las monedas activas del negocio y sus tasas de cambio

**Permiso requerido:** `currencies` (se asigna en **Integraciones externas**; las integraciones con acceso total heredado ya lo incluyen)

Estos endpoints son de solo lectura y existen únicamente en v2 (`https://api.filexpress.app/api/external/v2`). Úsalos para saber en qué monedas puedes emitir documentos y qué tasa se aplicará, antes de llamar a [Crear venta](/docs/api/v2/ventas.md#crear-venta) o [Registrar compra](/docs/api/v2/compras.md#registrar-compra).

> [!NOTE]
>
> Si el negocio no tiene habilitada la multi-moneda, los tres endpoints responden `403` con `code: "currency_not_enabled"`. Sin el permiso `currencies` responden `403` con `required_scope: "currencies"`.

## Listar monedas

```http theme={null}
GET /currencies
```

Devuelve la moneda base del negocio y las monedas extranjeras activas.

```json theme={null}
{
  "status": true,
  "data": {
    "base_currency_code": "USD",
    "currencies": [
      { "code": "USD", "name": "Dólar estadounidense", "symbol": "$", "decimals": 2, "is_base": true },
      { "code": "GTQ", "name": "Quetzal guatemalteco", "symbol": "Q", "decimals": 2, "is_base": false }
    ]
  }
}
```

| Campo | Descripción |
| - | - |
| `base_currency_code` | Moneda base del negocio, en la que se guardan y contabilizan todos los documentos. |
| `currencies[].code` | Código de 3 letras que se envía en `currency_code`. |
| `currencies[].name` / `symbol` | Nombre y símbolo de la moneda. |
| `currencies[].decimals` | Decimales con que se redondean los montos de esa moneda. |
| `currencies[].is_base` | `true` solo en la moneda base. |

Solo aparecen la moneda base y las monedas extranjeras **activas** del negocio; una moneda inactiva no se puede usar en documentos (`currency_not_enabled`).

## Listar tasas de cambio

```http theme={null}
GET /exchange-rates?currency=GTQ&from=2026-10-01&to=2026-10-31&per_page=50
```

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `currency` | string | No | Código de la moneda (por ejemplo `GTQ`). Sin él, todas las monedas. |
| `from` | date | No | Fecha de vigencia desde (`YYYY-MM-DD`). |
| `to` | date | No | Fecha de vigencia hasta (`YYYY-MM-DD`). |
| `per_page` | integer | No | 1 a 200. Por defecto 50. |
| `page` | integer | No | Página. |

Ordenadas de la más reciente a la más antigua. Solo se listan las tasas del negocio de la integración.

```json theme={null}
{
  "status": true,
  "data": {
    "base_currency_code": "USD",
    "rates": [
      { "id": "9a10c2f4-...", "currency_code": "GTQ", "rate": "0.13000000", "effective_date": "2026-10-20", "source": "manual" },
      { "id": "7b31d8e0-...", "currency_code": "GTQ", "rate": "0.12800000", "effective_date": "2026-10-15", "source": "manual" }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "total": 2
  }
}
```

| Campo | Descripción |
| - | - |
| `rates[].rate` | Unidades de moneda **base** por 1 unidad de la moneda extranjera, como texto con 8 decimales. |
| `rates[].effective_date` | Fecha desde la que rige la tasa. |
| `rates[].source` | Origen de la tasa: `manual` o `api`. |

> [!NOTE]
>
> Este listado no es paginado con el objeto `pagination` de otros módulos: la paginación viene como `current_page`, `last_page`, `per_page` y `total` dentro de `data`.

## Resolver la tasa de un documento

```http theme={null}
GET /exchange-rates/resolve?branch_id={branch_id}&currency=GTQ&date=2026-10-17
```

Devuelve la tasa que FileXpress usaría para un documento de esa sucursal, moneda y fecha: la del día o, si no hay, la última anterior. Una tasa específica de la sucursal tiene prioridad sobre la general del negocio.

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `branch_id` | uuid | Sí | Sucursal del negocio de la integración. Ver `GET /branches` en v1. |
| `currency` | string | Sí | Código de 3 letras. Debe ser la moneda base o una moneda activa. |
| `date` | date | No | Fecha del documento. Por defecto, hoy. |

```json theme={null}
{
  "status": true,
  "data": {
    "currency_code": "GTQ",
    "base_currency_code": "USD",
    "rate": "0.12800000",
    "effective_date": "2026-10-15",
    "exact": false,
    "source": "manual"
  }
}
```

| Campo | Descripción |
| - | - |
| `rate` | Tasa que se aplicaría (unidades de base por 1 unidad de la moneda). |
| `effective_date` | Fecha de la tasa encontrada. |
| `exact` | `true` si la tasa es de la misma fecha consultada; `false` si se usó una anterior. |
| `source` | `manual`, `api` o `base` (cuando consultas la moneda base, con tasa `1.00000000`). |

**Errores**

| `code` | HTTP | Causa |
| - | - | - |
| `validation_error` | `422` | `currency` ausente o que no tiene 3 letras, o `branch_id` que no pertenece al negocio. |
| `currency_not_enabled` | `422` | La moneda no está activa para el negocio. |
| `exchange_rate_not_found` | `404` | No hay tasa a esa fecha ni anterior. Registra una tasa en FileXpress o envía `exchange_rate` en el documento. |

```json theme={null}
{
  "status": false,
  "code": "exchange_rate_not_found",
  "message": "No hay tasa de cambio para GTQ a la fecha 2026-10-01 ni anterior. Registre una tasa de cambio o envíe exchange_rate en el documento.",
  "errors": { "exchange_rate": "Sin tasa de cambio para GTQ al 2026-10-01." }
}
```

> [!TIP]
>
> Para evitar sorpresas, resuelve la tasa con la fecha del documento antes de emitirlo y envíala como `exchange_rate` si tu sistema ya la fijó (por ejemplo, la tasa de la caja del día). Si no la envías, el servidor aplica la misma resolución.


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