Exchange CR
ENEnglish
Documentación

Documentación de la API

Todo lo que necesitás para integrar el tipo de cambio de Costa Rica en tus aplicaciones.

Introducción

La API de ExchangeCR expone el tipo de cambio oficial USD/CRC (BCCR) mediante una REST API versionada. Todas las rutas viven bajo /api/v1 y devuelven JSON con un formato consistente.

Base URLhttps://exchangecr.com/api/v1

Autenticación

Todos los endpoints —excepto /health, /openapi.json y /postman.json— requieren tu API key en el header x-api-key.

curl -H "x-api-key: YOUR_API_KEY" \
  https://exchangecr.com/api/v1/exchange-rate/latest
Solicitar API key

Formato de respuesta

Cada respuesta usa un envelope consistente: éxito con los datos, o error con un mensaje y un código legible.

// Success
{ "success": true, "data": { } }

// Error
{ "success": false, "message": "...", "error": "CODE" }

Catálogo de errores

StatuserrorCuándo
400BAD_REQUESTParámetros inválidos o faltantes (fecha, días, rango).
401UNAUTHORIZEDFalta o es inválida la API key.
404NOT_FOUNDNo existe dato para lo solicitado.
429RATE_LIMITEDDemasiadas solicitudes (ver Retry-After).
500INTERNAL_ERRORError interno del servidor.
503—Health check: base de datos inaccesible.

Límites de uso

60 solicitudes por minuto por cliente (por API key, o por IP si no hay key), con X-RateLimit-Limit y X-RateLimit-Remaining. Además, cada API key tiene un cupo de 5.000 solicitudes al mes: las respuestas incluyen X-Quota-Limit y X-Quota-Remaining, y superarlo devuelve 429 con el código QUOTA_EXCEEDED. ¿Necesitás más? Contactanos para un plan personalizado.

Endpoints

Tipo de cambio

GET/exchange-rate/latestRequiere API key

Último tipo de cambio

Obtén la tasa de compra y venta más reciente del par USD/CRC.

GET/exchange-rate?date=YYYY-MM-DDRequiere API key

Por fecha específica

Consulta el tipo de cambio de un día puntual.

  • • date — required (YYYY-MM-DD)
GET/exchange-rate/history?days=30Requiere API key

Historial

Los últimos N días de tasas (hasta 365), ideal para gráficos.

  • • days — 1–365, default 30
GET/exchange-rate/range?from=&to=Requiere API key

Rango de fechas

Todas las tasas entre dos fechas para análisis de períodos.

  • • from, to — required (max 366 days)

Conversor

GET/convert?amount=1000&from=USD&to=CRCRequiere API key

Conversor de montos

Convierte montos entre USD y CRC con la tasa oficial.

  • • amount — required (> 0)
  • • from, to — USD | CRC
  • • rate — buy | sell (default sell)
  • • date — optional

Analítica

GET/exchange-rate/analytics?days=30Requiere API key

Analítica

Promedio, mínimo, máximo, variación, volatilidad y tendencia ya calculados.

  • • days — default 30, or from & to
GET/exchange-rate/stats?period=monthly&from=&to=Requiere API key

Estadísticas por período

Agregados mensuales o anuales para un rango de fechas.

  • • period — monthly | yearly
  • • from, to — required
GET/exchange-rate/chart?days=90&points=60Requiere API key

Datos para gráficos

Serie optimizada y reducida a N puntos, con línea de tendencia.

  • • days — default 30
  • • points — 2–500, default 90

Bancos (ventanilla)

GET/banking/ratesRequiere API key

Tasas por institución

Compra y venta de dólares por banco y casa de cambio (ventanilla).

  • • date — optional
  • • type — optional (entity type)
GET/banking/best?operation=sellRequiere API key

Mejor tasa

Qué institución compra o vende dólares al mejor precio, con ranking.

  • • operation — buy | sell (required)

Inteligencia artificial

GET/insights?days=30&locale=esRequiere API key

AI Market Insights

Resumen con IA de las causas probables de los movimientos y un veredicto.

  • • days — default 30
  • • locale — es | en

Sistema

GET/healthPúblico

Estado del servicio

Verifica la disponibilidad de la API y la última fecha registrada.

GET/openapi.jsonPúblico

OpenAPI 3.1 spec

Machine-readable spec of every endpoint.

GET/postman.jsonPúblico

Postman collection

Import into Postman to try everything.

Cómo consumir

SDK oficial (JavaScript / TypeScript)

import { ExchangeCR } from "@exchangecr/sdk";

const client = new ExchangeCR({ apiKey: process.env.EXCHANGE_API_KEY });
const latest = await client.getLatest();
const { result } = await client.convert({ amount: 1000, from: "USD", to: "CRC" });

Next.js / JavaScript (fetch)

const res = await fetch(
  "https://exchangecr.com/api/v1/exchange-rate/latest",
  { headers: { "x-api-key": process.env.EXCHANGE_API_KEY } }
);
const { data } = await res.json();
console.log(data.sell);

Swift (URLSession)

var req = URLRequest(url: URL(string: "https://exchangecr.com/api/v1/exchange-rate/latest")!)
req.setValue("YOUR_API_KEY", forHTTPHeaderField: "x-api-key")
let (data, _) = try await URLSession.shared.data(for: req)

cURL

curl -H "x-api-key: YOUR_API_KEY" \
  "https://exchangecr.com/api/v1/exchange-rate/history?days=30"

Google Sheets

Usá funciones personalizadas para traer el tipo de cambio directo a una hoja. Pegá el script en Extensiones → Apps Script, guardá tu key con setExchangeApiKey('...') una vez, y empezá a usar =EXCHANGE…

FunciónDevuelve
=EXCHANGERATE([date],[type])La tasa (₡ por 1 USD), última o por fecha
=EXCHANGECONVERT(amount,from,to)Monto convertido entre USD y CRC
=EXCHANGEHISTORY([days])Tabla Fecha · Compra · Venta
=EXCHANGEBEST(operation)Mejor institución · compra · venta
=EXCHANGEANALYTICS([days])Promedio, min, max, variación, volatilidad
Descargar ExchangeCR.gs

Widgets embebibles

Mostrá el tipo de cambio en tu sitio con un iframe. Sin API key, se actualiza solo.

<iframe src="https://exchangecr.com/es/widget?theme=auto"
        width="360" height="150" style="border:0"></iframe>

Herramientas

Swagger

Referencia interactiva para probar cada endpoint.

Postman

Colección lista para importar.

Status

Disponibilidad del servicio en vivo.