Comenzando
Bienvenido a la documentación oficial de SUA-BCV. Nuestra API proporciona acceso en tiempo real a las tasas de cambio regionales y datos de conversión de moneda en un formato JSON altamente eficiente y optimizado.
Configuración del Entorno (.env)
Para mayor seguridad, te recomendamos guardar tu API Key en un archivo .env en la raíz de tu proyecto:
API_KEY=tu_clave_personal_aqui
key Autenticación
Para acceder a la API, debes incluir tu clave de API en el encabezado x-api-key de cada solicitud.
Genera una clave de acceso personal con 1 mes de duración para empezar a consumir la API de inmediato:
info Necesitas iniciar sesión con GitHub para generar y gestionar tus API Keys.
Iniciar Sesión con GitHubAtención
Todas las rutas /v1/* requieren el encabezado x-api-key: TU_CLAVE. No compartas tus claves públicamente.
Endpoints
Listado de puntos de acceso disponibles en la API SUA-BCV.
Diagnóstico
Health check para verificar la disponibilidad de la API.
Health check. Devuelve {"status":"ok"} si activo.
Venezuela — Cotizaciones
Oficial: Tasa BCV para el Dólar
Paralelo: Tasa paralela para el Dólar (Binance)
Todo: Todas las fuentes del Dólar
Oficial: Tasa BCV para el Euro
Paralelo: Tasa paralela para el Euro (Binance)
Todo: Todas las fuentes del Euro
Resumen Oficial: Solo tasas BCV (USD + EUR)
Resumen Paralelo: Solo tasas paralelas (Binance)
Todo: Todas las fuentes de USD y EUR juntas
Endpoints Deprecados
Estos endpoints serán eliminados en futuras versiones. No los uses en nuevos proyectos.
Estado del servicio y última actualización del sistema (Deprecado).
Histórico completo de cotizaciones del Dólar (Deprecado).
Histórico completo de cotizaciones del Euro (Deprecado).
JavaScript (Bun)
Ejemplo de cómo consumir la API y procesar los datos en una aplicación moderna.
// 1. Configurar control de tiempo (Timeout de 15s) const controller = new AbortController(); const id = setTimeout(() => controller.abort(), 15000); // 2. Realizar petición segura a la API const respuesta = await fetch('https://api-bcv-sua.vercel.app/v1/usd', { headers: { 'x-api-key': 'TU_API_KEY' }, signal: controller.signal }); clearTimeout(id); // 3. Procesar datos const datos = await respuesta.json(); console.log(`Tasa BCV: Bs. ${datos.valor}`);
currency_exchange Calculadora de Divisas (BCV)
* Tasa utilizada: Cargando... Bs/$
Dart (Console Application)
Ejemplo de una aplicación de consola en Dart con soporte para variables de entorno y peticiones HTTP.
pubspec.yaml
dependencies: dotenv: ^4.2.0 http: ^1.6.0 path: ^1.9.0
lib/mian.dart
import 'package:http/http.dart' as http; import 'dart:convert'; import 'package:dotenv/dotenv.dart'; Future<void> getRates(DotEnv env) async { // Asegúrate de que dotenv esté inicializado antes de llamar a esta función final apiKey = env['API_KEY'] ?? ''; final res = await http.get( Uri.parse('https://api-bcv-sua.vercel.app/v1/usd'), headers: { 'x-api-key': apiKey } ); if (res.statusCode == 200) { final data = jsonDecode(res.body); if (data is List && data.isNotEmpty) { print('Tasa oficial: \$${data[0]["valor"]}'); } else { print('Respuesta inesperada: \$${res.body}'); } } else { print('Error: \$${res.statusCode}'); } }
bin/mian.dart
import 'package:dotenv/dotenv.dart'; import 'package:main/mian.dart'; final env = DotEnv()..load(); Future<void> main() async { await getRates(env); }
Comandos de Ejecución
flutter pub get dart run
Python
import requests import os from dotenv import load_dotenv # Carga las variables desde el archivo .env load_dotenv() # Accede a las variables api_key = os.getenv('API_KEY') if not api_key: raise ValueError("No se encontró la variable de entorno API_KEY. Asegúrate de definirla en tu archivo .env.") url = "https://api-bcv-sua.vercel.app/v1/usd" headers = { "x-api-key": api_key } try: response = requests.get(url, headers=headers) response.raise_for_status() data = response.json() # Si la respuesta es una lista, toma el primer elemento if isinstance(data, list): if len(data) > 0: data = data[0] else: raise ValueError("La respuesta de la API es una lista vacía.") print(f"{data['nombre']}: {data['valor']}") except requests.RequestException as e: print(f"Error al hacer la solicitud: {e}") except Exception as e: print(f"Error inesperado: {e}")
Comandos de Ejecución
pip install requests python-dotenv python main.py
report_problem Errores Comunes
Solución al error "list indices must be integers or slices, not str"
Este error ocurre porque la respuesta de la API es una lista y no un diccionario. Para solucionarlo, el script debe verificar si la respuesta es una lista y tomar el primer elemento antes de acceder a las claves.
¿Qué hacer si ves este error?
- Asegúrate de tener la última versión del script.
- Si la API devuelve una lista vacía, el script lanzará un error indicando que no hay datos.
- Si la API devuelve datos, el script los procesará correctamente.
Solución en Python
# Procesa la respuesta de la API data = response.json() if isinstance(data, list): if len(data) > 0: data = data[0] else: raise ValueError("La respuesta de la API es una lista vacía.") print(f"{data['nombre']}: {data['valor']}")
Solución en JavaScript
let data = await response.json(); // Si es array, toma el primer elemento if (Array.isArray(data)) { data = data.length > 0 ? data[0] : null; } if (data) { console.log(`${data.nombre}: ${data.valor}`); }
Solución en Dart
final data = jsonDecode(res.body); // Validación de tipo de dato if (data is List && data.isNotEmpty) { final firstItem = data[0]; print('Datos: ${firstItem["valor"]}'); }
Registro de Cambios
- Nuevos endpoints
/usd-par/usd-all/eur-par/eur-all/cotizaciones-pary/cotizaciones-allpara separar la gestión de las tasas oficiales de las paralelas. - Lógica de fin de semana: Se mantiene la tasa del viernes hasta el lunes.
- Limpieza de Endpoints: Se movieron
/v1/estadoy/v1/historicos/*a la sección de Deprecados. - Optimización Móvil: Mejora en la visualización de rutas y navegación (v1.5.1).
- Lógica de persistencia de tasa diaria hasta medianoche.
- Ajustes en el workflow de cron con GitHub Actions.
- Mejoras de compatibilidad con Vercel Edge Functions.
- Migración de base de datos SQLite a Turso (LibSQL).
- Corrección de fallos en la actualización de montos en tiempo real.
- Agregado
valorAnterioryfechaAnteriorpara comparativas. - Normalización de nombres: "Oficial" a "Dolar".
- Sistema de mensajes de error detallados.
- Validación y verificación robusta de API-KEYS.
- Despliegue oficial en Vercel.
- Implementación de API-KEYS sociales (GitHub Auth).
- Rate limit (60 req/min) y sistema de cola (embudo) para peticiones.
- Nacimiento del proyecto en EsJS.
- Migración a JavaScript puro y adopción de Bun como runtime principal.