API para integradores

Si tu empresa prefiere integrarse en vez de usar nuestra caja o el widget, Bolívar Connect te da una API sobre tu propia cuenta del Banco de Venezuela. Registras una vez la llave que te da el BDV y, desde ahí, tu sistema verifica los pagos que recibes, consulta tu saldo y da vuelto con tu API key de Bolívar Connect.

Beta

Esta API está probada contra una cuenta real del BDV en producción, pero todavía puede cambiar la forma de algunas respuestas. Avísanos antes de llevarla a producción.

Cómo funciona

1. Genera tu llave en BDVenLínea Empresas (API de Conciliación) para tu cuenta jurídica.

2. Regístrala en Bolívar Connect. Comprobamos con el banco que la llave abre la cuenta que declaras; si no, no se guarda.

   curl -X PUT $BASE/v1/bancos/bdv/credencial \
     -H "x-api-key: $KEY" -H 'content-type: application/json' \
     -d '{"apiKey":"<tu llave del BDV>","cuenta":"0102…","rif":"J123456789","telefono":"04141234567"}'

   La respuesta nunca incluye la llave: sólo "llave": "••••A5B2".

3. Úsala con tu API key de Bolívar Connect:

   # Pagos recibidos hoy, de cualquier banco
   curl $BASE/v1/bancos/bdv/pagos -H "x-api-key: $KEY"
   
   # Verificar un pago por los últimos dígitos de la referencia y el monto
   curl -X POST $BASE/v1/bancos/bdv/verificaciones -H "x-api-key: $KEY" \
     -H 'content-type: application/json' \
     -d '{"referencia":"2135","monto":"500.00","pedido":"A-102"}'

Endpoints

Método	Ruta	Permiso	Qué hace
PUT	/v1/bancos/bdv/credencial	tenant:write	Registra o reemplaza tu llave del BDV
GET	/v1/bancos/bdv/credencial	tenant:write o bdv:read	Estado de tu credencial (sin la llave)
PATCH	/v1/bancos/bdv/credencial	tenant:write	Activa el movimiento de dinero y fija el tope diario
DELETE	/v1/bancos/bdv/credencial	tenant:write	Revoca la credencial y borra la llave cifrada
GET	/v1/bancos/bdv/credencial/usos	tenant:write o bdv:read	Cada uso que se hizo de tu llave
GET	/v1/bancos/bdv/saldo	bdv:read	Saldo disponible y retenido
GET	/v1/bancos/bdv/pagos	bdv:read	Pagos recibidos hoy y si ya se verificaron
POST	/v1/bancos/bdv/verificaciones	bdv:verify	Verifica un pago y lo marca como usado
POST	/v1/bancos/bdv/vueltos	bdv:move	Da vuelto por Pago Móvil (mueve dinero)
GET	/v1/bancos/bdv/comisiones?periodo=hoy|30d	bdv:read	Comisiones del banco por operación

Registrar, configurar y revocar la llave tocan tu cuenta real: con una key sk_test_ responden 403 live_key_required. Las lecturas, la verificación y el vuelto con sk_test_ salen de un banco simulado.

Verificar un pago

estado puede ser:

Estado	Significado
aprobado	El pago está en tu cuenta, por el monto exacto, y quedó marcado como usado para pedido
ya_usado	Ese comprobante ya pagó otro pedido (pedido dice cuál)
monto_distinto	La referencia existe pero por otro monto (pago.monto)
ambiguo	Varios pagos terminan en esos dígitos: manda más
no_encontrado	No hay ningún pago con esa referencia hoy
referencia_corta	Hacen falta al menos 4 dígitos

El «ya usado» lo garantiza nuestra base de datos: un mismo comprobante no puede pagar dos pedidos aunque llegue a la vez por la web, la caja y tu API.

Dar vuelto: tres llaves para mover dinero

Un vuelto sale de tu cuenta, así que hacen falta las tres cosas:

1. Una API key con el permiso bdv:move. Las keys por defecto no lo tienen; créala aparte: POST /v1/tenant/api-keys con "scopes": ["bdv:move"].
2. El movimiento de dinero activado con un tope diario: PATCH /v1/bancos/bdv/credencial con {"moverDinero": true, "limiteDiario": "500.00"}. Sin tope no se activa.
3. El header Idempotency-Key. Si reenvías la misma petición con la misma key, no se paga dos veces.

Si el banco no confirma el resultado, la respuesta es "estado": "desconocido". No reenvíes con otra Idempotency-Key: revisa primero tus movimientos.

Cómo protegemos tu llave

• Cifrada con AWS KMS (cifrado envolvente, AES-256-GCM). En nuestra base de datos sólo hay texto cifrado; la clave maestra nunca sale de AWS.
• Atada a tu empresa: el cifrado lleva tu identificador, así que tu llave no puede descifrarse para otro cliente.
• Sólo escritura: ningún endpoint la devuelve, ni a ti.
• Se usa sólo en memoria, justo al llamar al banco, y nunca se escribe en logs.
• Mover dinero está apagado hasta que tú lo actives, y siempre con tope.
• Auditoría: ves cada uso en /credencial/usos.
• Revocación: la borras aquí o la revocas en BDVenLínea cuando quieras. Si el banco la rechaza, la marcamos como inválida y te avisamos.

Errores

Código	Cuándo
bank_credential_missing	No has registrado tu llave
bank_credential_invalid	El banco rechazó la llave o el servicio no está afiliado
bank_credential_mismatch	La cuenta no corresponde a esa llave
money_movement_disabled	El movimiento de dinero no está activado
daily_limit_exceeded	El vuelto superaría tu tope diario
idempotency_key_required	Falta Idempotency-Key en una operación con dinero
bank_rejected	El banco rechazó la operación (saldo, datos del beneficiario…)
bank_unavailable	El banco no respondió; reintenta