GET /v1/fx/rates/:market/history

Devuelve la cotización vigente en una fecha pasada para un market específico. Útil para reportes contables, auditoría, backfill de datos y análisis retrospectivo.

El endpoint busca el registro más cercano a esa fecha o anterior (no posterior). Esto es importante: en días no hábiles del BCV, el valor "vigente" es el último publicado.

Request

GET /v1/fx/rates/:market/history?date=YYYY-MM-DD HTTP/1.1
Host: api.cotizave.com
X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d

Path parameters

Query parameters

Ejemplos de request

Tasa BCV del 1 de marzo de 2026:

curl "https://api.cotizave.com/v1/fx/rates/reference/history?date=2026-03-01" \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

Tasa Binance P2P del 15 de enero de 2026:

curl "https://api.cotizave.com/v1/fx/rates/binance/history?date=2026-01-15" \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"

Response

200 OK

{
  "market": "reference",
  "date": "2026-03-01",
  "rate": 472.18,
  "updated_at": "2026-03-01T14:00:00Z",
  "captured_at": "2026-03-01T14:05:12Z"
}

Schema de respuesta

updated_at vs captured_at

Los dos timestamps suelen ser distintos:

• updated_at: cuándo el dato fue producido por la fuente original. Para BCV es la hora de publicación oficial; para P2P, la hora del último trade observado.
• captured_at: cuándo Cotizave consumió e indexó ese dato. Suele estar dentro de los siguientes minutos.

Para auditoría contable normalmente importa updated_at. Para reproducir "qué sabíamos en ese momento", importa captured_at.

Comportamiento "closest-or-before"

El endpoint devuelve el registro más cercano a la fecha pedida, pero nunca posterior. Ejemplos:

• Si pides BCV del domingo y BCV no publicó, recibes el valor del viernes previo.
• Si pides una fecha previa al primer registro disponible, recibes 404 resource_not_found.
• Si pides una fecha en el futuro, recibes 400 invalid_format.

Esto es a propósito: para reportes legales y contables el valor "vigente" en un día no hábil del BCV es el último publicado, no una proyección.

Errores posibles

Casos de uso típicos

Reproducir una factura emitida en el pasado

Para auditar o reemitir una factura con la tasa BCV original:

async function tasaDelDia(fechaIso) {
  const res = await fetch(
    `https://api.cotizave.com/v1/fx/rates/reference/history?date=${fechaIso}`,
    { headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY } }
  )
  const { rate, updated_at } = await res.json()
  return { rate, publicadaEn: updated_at }
}

const { rate, publicadaEn } = await tasaDelDia('2026-02-14')
// usar 'rate' como tasa de la factura del 14-feb

Backfill de series temporales

Para reconstruir tu propia tabla de tasas mensual:

const market = 'parallel'
const dates = ['2026-01-31', '2026-02-28', '2026-03-31', '2026-04-30']

for (const date of dates) {
  const res = await fetch(
    `https://api.cotizave.com/v1/fx/rates/${market}/history?date=${date}`,
    { headers: { 'X-API-Key': key } }
  )
  if (!res.ok) continue
  const data = await res.json()
  await db.insert('rate_history', { market, date, rate: data.rate })
}

Notas importantes

Zona horaria

El parámetro date se interpreta en UTC. Si tu negocio opera en huso horario VET (UTC-4), considera que "hoy" en VET puede ser "ayer" en UTC para algunas horas del día.

Profundidad histórica

El histórico se persiste a partir de la incorporación de cada market al producto. Si pides una fecha previa a esa incorporación, recibes resource_not_found. Para BCV (reference) la profundidad es la mayor del producto.