Consulta tasas de cambio
Busca un proveedor, consulta su tasa vigente cuando esté disponible o revisa el historial. Las tasas vigentes aparecen solo cuando el servicio tiene datos recientes; la API no garantiza la oferta en tiempo real de un banco.
Empieza con el explorador de arriba. Si no hay una cotización vigente, usa la consulta de historial en Consultar el historial. El par predeterminado es USD/DOP.
Entender la respuesta
Cada cotización incluye el proveedor, el par de monedas, buy, sell y la fecha de observación. Si falta un precio o la fecha y hora de observación, la API devuelve null.
buyes la tasa que usa el proveedor cuando te compra la moneda base.selles la tasa que usa el proveedor cuando te vende la moneda base.channelindica dónde aplica la cotización, por ejemplo, en una oficina o en un canal en línea.
Conectar tu aplicación
Primero descubre el identificador del proveedor, los pares de monedas, los canales y la disponibilidad de cada fuente:
curl '__API_ORIGIN__/v1/exchange-rate-providers'
Después solicita una serie específica. Este ejemplo pide la cotización de USD/DOP del proveedor para oficina:
curl '__API_ORIGIN__/v1/exchange-rates?provider=banreservas&base=USD&channel=office'
const apiOrigin = '__API_ORIGIN__';
const response = await fetch(`${apiOrigin}/v1/exchange-rates?provider=banreservas&base=USD&channel=office`);
if (!response.ok) throw new Error(`La consulta de tasas falló: ${response.status}`);
const { rates, unavailable } = await response.json();
console.log({ rates, unavailable });
Conserva buy y sell como textos decimales hasta que tu aplicación defina cómo redondearlos. Evita los números binarios de punto flotante cuando necesites cálculos exactos.
La respuesta puede incluir varias cotizaciones en rates y una lista unavailable con las series solicitadas que no tienen un resultado elegible. Una solicitud para una serie específica puede devolver 503 cuando el servicio no puede producir una respuesta vigente y confiable. Usa el historial cuando necesites observaciones capturadas.
Elegir fuentes directas o secundarias
La consulta más reciente usa por defecto una fuente directa reciente, como el canal propio calificado del proveedor o una publicación suya. La API no sustituye silenciosamente una cotización de oficina por una de internet ni combina los valores de buy y sell de fuentes distintas.
Para incluir una fuente intermediaria calificada, actívala de forma explícita:
curl '__API_ORIGIN__/v1/exchange-rates?base=USD&allowSecondary=true'
Conserva source y sourceKind junto con la cotización. Las observaciones directas, secundarias y heredadas representan evidencias diferentes y no deben presentarse como una misma serie.
Consultar el historial capturado
Solicita un proveedor y par de monedas en un rango máximo de 31 días:
curl '__API_ORIGIN__/v1/exchange-rates/history?provider=banreservas&base=USD&from=2024-01-01&to=2024-01-31'
El historial conserva cambios capturados, incluidas varias observaciones del mismo día cuando la fuente las permite. Los registros antiguos pueden tener solo una fecha de observación y por eso devuelven una hora null. El servicio registra lo que sus recolectores capturan; un intervalo vacío no demuestra que la tasa se mantuvo igual.
El historial admite filtros opcionales de channel y source. La página predeterminada contiene 100 observaciones y el máximo es 500. Para pedir otra página, envía el nextCursor devuelto con los mismos filtros. Reinicia sin cursor cuando quieras incluir observaciones incorporadas después de la primera página.
Gestionar cotizaciones no disponibles o desactualizadas
400 significa que debes corregir un filtro. 404 significa que el identificador del proveedor no existe. 503 significa que el servicio no puede producir una respuesta vigente y confiable; una colección fallida no vuelve vigente una cotización anterior. Un proveedor puede tener historial sin una cotización vigente, así que revisa currentAvailable en el catálogo.
Las respuestas exitosas pueden almacenarse hasta 60 segundos, sin superar la vigencia indicada por el servicio. No guardes en caché los errores. Esta API informa cotizaciones publicadas o capturadas; no convierte dinero, ejecuta transacciones ni certifica la oferta actual de un banco.