Monedas y tasas de cambio (v2)

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 o Registrar compra.

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

GET /currencies

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

{
  "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

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.

{
  "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`.

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

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.

{
  "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.

{
  "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." }
}

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.

Primeros Pasos

API v2

Facturación

Recursos Humanos

Contabilidad

Inventario

Proyectos

Cuentas por cobrar y pagar

Precios y promociones

Caja

Referencia interactiva

Monedas y tasas de cambio (v2)

Listar monedas

Listar tasas de cambio

Resolver la tasa de un documento

​Listar monedas

​Listar tasas de cambio

​Resolver la tasa de un documento

Listar monedas

Listar tasas de cambio

Resolver la tasa de un documento