Cómo consultar la tasa BCV vía API REST

Paso 1: Obtener una API key

Crea tu cuenta en app.cotizave.com. El plan gratuito no requiere tarjeta de crédito: solo ingresa tu correo, elige una contraseña y confirma tu email. En el dashboard verás tu API key generada automáticamente — cópiala al portapapeles.

El plan gratis incluye un número razonable de requests por día para proyectos personales o integraciones pequeñas. Si necesitas mayor volumen, los planes de pago aumentan la cuota y habilitan endpoints adicionales como historial y tasas paralelas en tiempo real.

Si tienes dudas sobre qué endpoints incluye cada plan, revisa ¿Existe una API oficial del Banco Central de Venezuela? — ahí explicamos por qué el BCV no ofrece acceso programático directo y cómo Cotizave resuelve ese problema.

Paso 2: Hacer la primera llamada (cURL)

Con tu API key en mano, abre una terminal y ejecuta:

curl https://api.cotizave.com/v1/fx/rates/reference \
  -H "X-API-Key: YOUR_KEY"

Respuesta JSON:

{
  "market": "reference",
  "currency": "USD",
  "rate": 47.23,
  "updated_at": "2026-05-02T14:00:00Z"
}

Los cuatro campos:

• market — mercado de referencia. reference indica la tasa BCV oficial.
• currency — divisa base del par. Siempre USD para la tasa BCV.
• rate — bolívares por un dólar según la publicación más reciente del BCV.
• updated_at — timestamp ISO 8601 UTC del último snapshot disponible. Úsalo para saber si tus datos son frescos sin necesitar llamadas innecesarias.

Paso 3: Adaptar a tu lenguaje

Node.js (fetch nativo)

Node 18+ incluye fetch nativo. Guarda tu key como variable de entorno COTIZAVE_KEY y nunca la escribas directo en el código fuente.

const res = await fetch('https://api.cotizave.com/v1/fx/rates/reference', {
  headers: { 'X-API-Key': process.env.COTIZAVE_KEY }
})
const data = await res.json()
console.log(`1 USD = ${data.rate} VES (BCV)`)

Python (requests)

Instala requests con pip install requests. El parámetro timeout=10 evita que tu proceso quede colgado si la red falla.

import requests, os

res = requests.get(
    'https://api.cotizave.com/v1/fx/rates/reference',
    headers={'X-API-Key': os.environ['COTIZAVE_KEY']},
    timeout=10,
)
data = res.json()
print(f"1 USD = {data['rate']} VES (BCV)")

PHP (cURL)

La extensión cURL viene incluida en prácticamente cualquier instalación de PHP. Usa getenv() para leer la key desde el entorno del servidor.

$ch = curl_init('https://api.cotizave.com/v1/fx/rates/reference');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('COTIZAVE_KEY')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
echo "1 USD = {$data['rate']} VES (BCV)";

Google Sheets (Apps Script)

La función IMPORTDATA no sirve aquí porque no permite enviar headers de autenticación. La solución correcta es Apps Script: desde la hoja abre Extensiones → Apps Script, pega el código y guarda la API key en Archivo → Propiedades del proyecto → Script properties.

function getTasaBCV() {
  const res = UrlFetchApp.fetch('https://api.cotizave.com/v1/fx/rates/reference', {
    headers: { 'X-API-Key': PropertiesService.getScriptProperties().getProperty('COTIZAVE_KEY') }
  })
  const data = JSON.parse(res.getContentText())
  return data.rate
}

Una vez guardado, escribe =getTasaBCV() en cualquier celda y la hoja mostrará la tasa BCV actual. Para que se refresque automáticamente, crea un disparador (trigger) en Apps Script para ejecutar la función cada hora o cada día.

Paso 4: Manejar errores y rate limits

• Errores de red o timeout: implementa retry con backoff exponencial. Empieza con 1 segundo de espera, duplica en cada intento. Tres intentos suelen ser suficientes.
• HTTP 429 (Too Many Requests): la respuesta incluye el header Retry-After con los segundos que debes esperar. Tu cliente debe leer ese valor y pausar antes de reintentar — no uses un delay fijo.
• Respuesta inválida o inesperada: valida que data.rate sea un número mayor que cero antes de usarlo en cálculos. Un null o NaN en una conversión puede generar facturas con montos incorrectos.

Errores comunes

• Olvidar el header X-API-Key: la API responde 401 Unauthorized. Asegúrate de que el header esté presente en cada request.
• Usar HTTP en vez de HTTPS: la API no acepta tráfico sin cifrar. Usa siempre https://.
• Key hardcodeada en código fuente público: si subes tu API key a GitHub, cualquiera puede usarla. Guárdala siempre en variables de entorno o gestores de secretos como AWS Secrets Manager o Vault.
• No guardar updated_at: sin este campo no puedes saber si la tasa que tienes en cache ya fue reemplazada. Persiste el timestamp junto al valor de la tasa.

¿Qué hago con la tasa una vez la tengo?

• ERP y contabilidad: inyecta la tasa BCV diaria a tu sistema contable para que todas las facturas en divisa queden registradas con el tipo de cambio oficial correcto.
• E-commerce: actualiza los precios en bolívares de tu tienda automáticamente cada vez que el BCV publique una nueva tasa, eliminando la actualización manual.
• Dashboard interno: muestra en tiempo real la tasa BCV junto a la paralela y el P2P para que tu equipo tome decisiones con datos actualizados.
• Alertas Slack o email: compara la tasa nueva con la anterior; si la variación supera un umbral, envía una notificación automática al canal de tu equipo financiero.

Recursos

Preguntas frecuentes