Guía de API y Banca Digital del Banco de Venezuela

Endpoints disponibles

La API del Banco de Venezuela expone los siguientes endpoints RESTful para operaciones de banca digital empresarial. Todos los endpoints requieren autenticación mediante token JWT y deben ser consumidos con HTTPS exclusivamente.

{
  "codigo": 200,
  "datos": [
    {
      "cuenta": "0102-0547-81-0001234567",
      "saldo": 2580000.00,
      "moneda": "VES"
    }
  ]
}

{
  "codigo": 201,
  "datos": {
    "idOperacion": "TXN-2024-89321",
    "estado": "pendiente",
    "fecha": "2024-11-15T14:30:00Z"
  }
}

{
  "codigo": 200,
  "datos": [],
  "paginacion": {
    "cursor": "abc123",
    "limite": 50
  }
}

{
  "codigo": 201,
  "datos": {
    "idBeneficiario": "BEN-44567",
    "estado": "activo"
  }
}

{
  "codigo": 200,
  "datos": {
    "usdVes": 38.50,
    "eurVes": 41.20
  }
}

{
  "codigo": 200,
  "datos": {
    "total": 150,
    "exitosos": 148,
    "fallidos": 2
  }
}

Pasos de integración

Siga estos pasos para integrar su aplicación con la API de banca digital del Banco de Venezuela. El proceso completo toma aproximadamente 5 días hábiles desde la solicitud inicial hasta la puesta en producción.

1. Solicitud de credenciales

   Registre su empresa en el portal de desarrolladores de Gina Capital para obtener las credenciales de acceso. Necesitará su RIF, documento constitutivo y una carta de autorización firmada por el representante legal. El equipo de integración revisará su solicitud en un plazo máximo de 48 horas hábiles.

2. Configuración de entorno

   Configure su servidor con las variables de entorno necesarias. Debe incluir las claves API proporcionadas, la URL base del entorno sandbox para pruebas y los certificados SSL requeridos para la comunicación segura con los servidores del Banco de Venezuela.

   BDV_API_KEY=sk_live_xxxxxxxxxxxx
   BDV_API_SECRET=xxxxxxxxxxxxxxxx
   BDV_SANDBOX_URL=https://sandbox.bancodevenezuela.com/api/v1
   BDV_PRODUCTION_URL=https://api.bancodevenezuela.com/v1

3. Autenticación y tokens

   Implemente el flujo de autenticación OAuth 2.0 para obtener tokens de acceso. El endpoint de autenticación devuelve un token JWT con expiración de 60 minutos que debe incluirse en el encabezado Authorization de todas las solicitudes posteriores.

   curl -X POST https://api.bancodevenezuela.com/v1/auth \
     -H "Content-Type: application/json" \
     -d '{"api_key": "sk_live_xxxxxxxxxxxx"}'

4. Pruebas en sandbox

   Realice todas las pruebas necesarias en el entorno sandbox antes de migrar a producción. El sandbox replica todas las funcionalidades del entorno productivo utilizando datos simulados. Ejecute pruebas unitarias, de integración y de carga para verificar el correcto funcionamiento de su implementación.

5. Certificación y pase a producción

   Una vez completadas las pruebas, solicite la certificación oficial. El equipo de Gina Capital realizará una revisión de seguridad y funcionalidad. Después de la aprobación, recibirá las credenciales de producción y podrá comenzar a operar con los servicios financieros del Banco de Venezuela.

Esquemas de datos

Los siguientes esquemas JSON definen la estructura de datos utilizada por la API del Banco de Venezuela. Todos los campos marcados como requeridos deben ser proporcionados en las solicitudes POST y PUT. Los campos opcionales pueden omitirse según la necesidad del cliente.

{
  "cuentaOrigen": "string",
  "cuentaDestino": "string",
  "monto": "number",
  "moneda": "string",
  "referencia": "string",
  "concepto": "string"
}

{
  "nombre": "string",
  "rif": "string",
  "banco": "string",
  "cuenta": "string",
  "tipoCuenta": "string",
  "email": "string"
}

{
  "codigo": "number",
  "mensaje": "string",
  "detalles": "string",
  "timestamp": "string",
  "ruta": "string"
}

{
  "cursor": "string",
  "limite": "number",
  "total": "number",
  "siguiente": "string"
}

Límites de uso y rate limiting

La API del Banco de Venezuela implementa rate limiting para garantizar la estabilidad del servicio para todos los clientes. Los límites varían según el plan contratado y el tipo de endpoint. Superar estos límites resultará en respuestas HTTP 429.

Encabezados de rate limiting

Cada respuesta de la API incluye encabezados HTTP que informan sobre el estado actual de tu cuota de solicitudes. Estos encabezados te permiten implementar estrategias de backoff y reintento de manera eficiente sin exceder los límites establecidos por el Banco de Venezuela.

X-RateLimit-Limit: 1500
X-RateLimit-Remaining: 1342
X-RateLimit-Reset: 1701542400
Retry-After: 45

Autenticación y seguridad

El sistema de autenticación de la API del Banco de Venezuela utiliza OAuth 2.0 con flujo de concesión de credenciales de cliente. Cada solicitud debe incluir un token JWT en el encabezado de autorización. Los tokens tienen una vigencia máxima de 60 minutos y deben renovarse antes de su expiración para evitar interrupciones en el servicio.

Para obtener un token de acceso, debe enviar una solicitud POST al endpoint de autenticación con sus credenciales API. El servidor responderá con un token JWT firmado y su tiempo de expiración en segundos. Guarde este token de forma segura y nunca lo exponga en público o en código del lado del cliente.

POST /api/v1/auth
Content-Type: application/json

{
  "apiKey": "sk_live_xxxxxxxxxxxx",
  "apiSecret": "xxxxxxxxxxxxxxxx"
}

Respuesta:
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600,
  "tipo": "Bearer"
}

Se recomienda implementar un mecanismo de renovación automática de tokens que verifique el tiempo restante antes de cada solicitud. Si el token está próximo a expirar, el sistema debe solicitar uno nuevo de forma transparente sin afectar la experiencia del usuario final de la aplicación.

Manejo de errores y códigos de respuesta

Todas las respuestas de la API del Banco de Venezuela siguen una estructura uniforme que facilita el manejo de errores en el cliente. Cada respuesta incluye un código numérico, un mensaje descriptivo y detalles adicionales cuando es relevante. Implementar un manejo adecuado de estos códigos es fundamental para construir aplicaciones robustas.

La API utiliza códigos HTTP estándar para indicar el resultado de cada operación. Los errores de validación devuelven código 422 con detalles específicos sobre los campos que no cumplen con las reglas de negocio. Los errores de autenticación devuelven 401 y los de autorización devuelven 403 respectivamente.

Para errores transitorios como los códigos 429 y 500, se recomienda implementar una estrategia de reintento con backoff exponencial. El encabezado Retry-After indica el tiempo en segundos que debe esperar antes de realizar una nueva solicitud al mismo endpoint de la API.

Ejemplos de código por lenguaje

A continuación presentamos ejemplos de integración en los lenguajes de programación más utilizados por nuestros clientes empresariales. Cada ejemplo muestra cómo realizar una consulta de saldo utilizando la API del Banco de Venezuela, incluyendo autenticación, construcción de la solicitud y procesamiento de la respuesta.

const apiKey = 'sk_live_xxxxxxxxxxxx';
const response = await fetch(
  'https://api.bancodevenezuela.com/v1/saldos',
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const data = await response.json();
console.log(data.datos);

import requests
headers = {'Authorization': 'Bearer sk_live_xxxxxxxxxxxx'}
response = requests.get(
  'https://api.bancodevenezuela.com/v1/saldos',
  headers=headers
)
data = response.json()
print(data['datos'])

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
  'https://api.bancodevenezuela.com/v1/saldos');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer sk_live_xxxxxxxxxxxx'
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data['datos']);

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.bancodevenezuela.com/v1/saldos"))
  .header("Authorization", "Bearer sk_live_xxxxxxxxxxxx")
  .GET().build();
HttpResponse<String> response =
  client.send(request, BodyHandlers.ofString());
System.out.println(response.body());

Estos ejemplos cubren los casos de uso más frecuentes en la integración con la API del Banco de Venezuela. Para implementaciones en otros lenguajes, consulte la documentación completa de la API que incluye ejemplos adicionales y guías detalladas de integración paso a paso.

Webhooks y notificaciones en tiempo real

La API del Banco de Venezuela ofrece webhooks para notificar eventos en tiempo real a su aplicación. Los webhooks eliminan la necesidad de realizar consultas periódicas a la API, permitiendo que su sistema reciba actualizaciones instantáneas cuando ocurren eventos relevantes en las cuentas de su empresa.

Para configurar webhooks, debe registrar una URL de callback en el portal de desarrolladores. El sistema enviará solicitudes POST a esta URL cada vez que ocurra un evento suscrito. Es importante que su servidor responda con un código 200 dentro de los 5 segundos siguientes para confirmar la recepción del evento.

{
  "evento": "transferencia.completada",
  "idOperacion": "TXN-89321",
  "monto": 500000.00,
  "moneda": "VES",
  "estado": "completada"
}

{
  "evento": "saldo.actualizado",
  "cuenta": "0102-0547-81-0001234567",
  "saldoAnterior": 2000000.00,
  "saldoActual": 2500000.00,
  "diferencia": 500000.00
}

La implementación de webhooks requiere que su servidor sea accesible públicamente y cuente con un certificado SSL válido. Se recomienda verificar la autenticidad de cada webhook mediante la validación de la firma HMAC incluida en el encabezado de la solicitud entrante para garantizar la seguridad.