Documentación chevron_right Introducción

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 de la API
BASE URL https://api-bcv-sua.vercel.app
Formato: JSON
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.

Gestión de Credenciales

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 GitHub

¡Key Generada con Éxito!

Copia tu clave ahora. Por seguridad, no volverá a aparecer en pantalla.

warning Importante: Una vez cierres esta ventana, no podrás recuperar el acceso a esta clave específica.
warning
Atenció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.

GET BASE URL /ping

Health check. Devuelve {"status":"ok"} si activo.

Venezuela — Cotizaciones

GET .../v1 /usd

Oficial: Tasa BCV para el Dólar

GET .../v1 /usd-par

Paralelo: Tasa paralela para el Dólar (Binance)

GET .../v1 /usd-all

Todo: Todas las fuentes del Dólar

GET .../v1 /eur

Oficial: Tasa BCV para el Euro

GET .../v1 /eur-par

Paralelo: Tasa paralela para el Euro (Binance)

GET .../v1 /eur-all

Todo: Todas las fuentes del Euro

GET .../v1 /cotizaciones

Resumen Oficial: Solo tasas BCV (USD + EUR)

GET .../v1 /cotizaciones-par

Resumen Paralelo: Solo tasas paralelas (Binance)

GET .../v1 /cotizaciones-all

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.

GET .../v1 /estado

Estado del servicio y última actualización del sistema (Deprecado).

GET .../v1 /historicos/dolares

Histórico completo de cotizaciones del Dólar (Deprecado).

GET .../v1 /historicos/euros

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.

fetch.js
// 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)

sync_alt

* 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
pubspec.yaml
dependencies:
  dotenv: ^4.2.0
  http: ^1.6.0
  path: ^1.9.0
lib/mian.dart
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
bin/mian.dart
import 'package:dotenv/dotenv.dart';
import 'package:main/mian.dart';

final env = DotEnv()..load();

Future<void> main() async {
  await getRates(env);
}
terminal
Comandos de Ejecución
flutter pub get 
dart run 

Python

api.py
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}")
terminal
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?
  1. Asegúrate de tener la última versión del script.
  2. Si la API devuelve una lista vacía, el script lanzará un error indicando que no hay datos.
  3. 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

v1.5 Marzo 28-30, 2026
  • Nuevos endpoints /usd-par /usd-all /eur-par /eur-all /cotizaciones-par y /cotizaciones-all para 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/estado y /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).
v1.4 Marzo 26, 2026
  • 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.
v1.3 Marzo 21, 2026
  • Migración de base de datos SQLite a Turso (LibSQL).
  • Corrección de fallos en la actualización de montos en tiempo real.
v1.2 Marzo 14, 2026
  • Agregado valorAnterior y fechaAnterior para comparativas.
  • Normalización de nombres: "Oficial" a "Dolar".
  • Sistema de mensajes de error detallados.
  • Validación y verificación robusta de API-KEYS.
v1.1 Marzo 10, 2026
  • Despliegue oficial en Vercel.
  • Implementación de API-KEYS sociales (GitHub Auth).
  • Rate limit (60 req/min) y sistema de cola (embudo) para peticiones.
v1.0 Marzo 9, 2026
  • Nacimiento del proyecto en EsJS.
  • Migración a JavaScript puro y adopción de Bun como runtime principal.