R4 Conecta
Versión 3.0

Documentación Técnica

Especificaciones completas de la API, flujos de autenticación, webhooks y ejemplos de código detallados.

Documentación Técnica API R4 Conecta

Desarrollado por: dPana Soft

Tabla de Contenidos

  1. Introducción
  2. Requisitos Técnicos
  3. Autenticación y Seguridad
  4. Endpoints
  5. Códigos de Error
  6. Ejemplos con Bruno API

Introducción

La API R4 Conecta permite la integración con servicios bancarios para procesamiento de pagos móviles, transferencias, débitos y créditos inmediatos.

URL Base: https://r4conecta.mibanco.com.ve

Protocolo: HTTPS (TLS 1.2+)

Formato: JSON

Requisitos Técnicos

Infraestructura Requerida

  • Dominio propio registrado a nombre de la empresa
  • Certificado TLS 1.2+ válido emitido por autoridad certificadora confiable
  • IP Whitelisting para endpoints de notificación:
    • 45.175.213.98
    • 200.74.203.91
    • 204.199.249.3

Headers Requeridos

Todos los endpoints requieren los siguientes headers:

```http Content-Type: application/json Authorization: {TOKEN_HMAC_SHA256} Commerce: {COMMERCE_TOKEN} X-License-Key: {LICENSE_KEY} ```

Generación del Token de Autorización

El token de autorización se genera usando HMAC-SHA256:

```javascript const crypto = require('crypto');

function generateAuthToken(data, commerceSecret) { return crypto .createHmac('sha256', commerceSecret) .update(data) .digest('hex'); } ```

Autenticación y Seguridad

Sistema de Licencias

La API utiliza un sistema de licencias con validación de fechas. El hash de licencia se genera usando:

  • Token COMMERCE: Usado como clave de encriptación AES-256
  • Rango de fechas: Fecha de inicio y fin en formato YYYY-MM-DD

Generación del hash:

```bash

Establecer el token COMMERCE en el ambiente

export COMMERCE=tu_commerce_token

Generar hash de licencia

node dist/tools/generateLicense.js 2024-01-01 2025-12-31 ```

El hash generado debe:

  1. Copiarse a la variable _LIC en el archivo .env
  2. Incluirse en el header X-License-Key en cada petición

Importante: Si cambias el token COMMERCE, debes regenerar el hash de licencia.

Token COMMERCE

El token COMMERCE es un valor único proporcionado por el banco que se utiliza para:

  1. Autenticación: Header Commerce en cada petición
  2. Firma HMAC-SHA256: Clave para generar el header Authorization
  3. Encriptación de licencia: Clave para encriptar/desencriptar el hash de licencia

Rate Limiting

  • Límite: 100 peticiones por 15 minutos por IP
  • Header de respuesta: X-RateLimit-Remaining

Endpoints

1. Consulta Tasa BCV

Obtiene la tasa de cambio oficial del Banco Central de Venezuela.

Endpoint: POST /api/bcv

Authorization Token: HMAC-SHA256 de fechavalor + moneda

Request: ```json { "Moneda": "USD", "Fechavalor": "2024-07-23" } ```

Response (Éxito): ```json { "code": "00", "fechavalor": "2024-07-23", "tipocambio": 36.5314 } ```

Validaciones:

  • Moneda: Código ISO de 3 caracteres (USD, EUR, etc.)
  • Fechavalor: Formato YYYY-MM-DD

2. Consulta Cliente (Webhook)

Endpoint implementado por el cliente para validar usuarios antes de aceptar pagos móviles.

Endpoint: POST {dominio_cliente}/R4consulta

Authorization: UUID generado por el comercio

Request: ```json { "IdCliente": "13536734", "Monto": "135.36", "TelefonoComercio": "04129196699" } ```

Response (Cliente Aceptado): ```json { "status": true } ```

Response (Cliente Rechazado): ```json { "status": false } ```

3. Notificación Pago Móvil (Webhook)

Endpoint implementado por el cliente para recibir notificaciones de pagos móviles entrantes.

Endpoint: POST {dominio_cliente}/R4notifica

Authorization: UUID generado por el comercio

Request: ```json { "IdComercio": "13536734", "TelefonoComercio": "04125555555", "TelefonoEmisor": "04145555555", "Concepto": "PRUEBA", "BancoEmisor": "134", "Monto": "123.13", "FechaHora": "2024-12-05T16:50:48.421Z", "Referencia": "83736278", "CodigoRed": "00" } ```

Response (Notificación Aceptada): ```json { "abono": true } ```

Validaciones:

  • IdComercio: 8 dígitos numéricos
  • TelefonoComercio, TelefonoEmisor: 11 dígitos (formato 04XXXXXXXXX)
  • BancoEmisor: 3-4 dígitos
  • Monto: Máximo 8 enteros y 2 decimales
  • CodigoRed: Código de respuesta interbancaria

4. Gestión de Pagos (Dispersión)

Permite realizar pagos a múltiples beneficiarios desde una transacción recibida.

Endpoint: POST /api/pagos

Authorization Token: HMAC-SHA256 de monto + fecha

Request: ```json { "monto": "10.00", "fecha": "07/08/2024", "Referencia": "1293912", "personas": [ { "nombres": "Victor Maceros", "documento": "V05503673", "destino": "01020488760100026670", "montoPart": "4.00" }, { "nombres": "Jorge Perez", "documento": "J696886684", "destino": "01341032660321048077", "montoPart": "6.00" } ] } ```

Response (Éxito): ```json { "success": true, "message": "Dispersión exitosa" } ```

Response (Error): ```json { "error": "ERROR SECRETO NO VALIDO", "success": false, "message": "No se pudo completar la dispersión" } ```

5. Vuelto (Pago Móvil Saliente)

Procesa un pago móvil a un beneficiario.

Endpoint: POST /api/vuelto

Authorization Token: HMAC-SHA256 de TelefonoDestino + Monto + Banco + Cedula

Request: ```json { "TelefonoDestino": "04145555555", "Cedula": "V12345678", "Banco": "0102", "Monto": "1000.00", "Concepto": "PRUEBA", "Ip": "0.0.0.0" } ```

Response (Aprobado): ```json { "code": "00", "message": "TRANSACCION EXITOSA", "reference": "15558293" } ```

Códigos de Error Comunes:

  • 08: Token Inválido
  • 14: Combo celular-cédula no registrado
  • 51: No tiene fondos disponibles
  • 55: Teléfono origen no existe
  • 56: Número de celular no coincide con cédula
  • 80: Cédula del receptor inválida

6. Generar OTP

Inicia el proceso de generación de OTP para débito inmediato.

Endpoint: POST /api/otp/generar

Authorization Token: HMAC-SHA256 de Banco + Monto + Telefono + Cedula

Request: ```json { "Banco": "0192", "Monto": "50.00", "Telefono": "04145555555", "Cedula": "V12345678" } ```

Response: ```json { "code": "202", "message": "Se ha recibido el mensaje de forma satisfactoria", "success": true } ```

7. Débito Inmediato

Completa la operación de débito inmediato usando el OTP generado.

Endpoint: POST /api/debito/inmediato

Authorization Token: HMAC-SHA256 de Banco + Cedula + Telefono + Monto + OTP

Request: ```json { "Banco": "0191", "Monto": "50.00", "Telefono": "04145555555", "Cedula": "V12345678", "Nombre": "Maria Perez", "OTP": "19807849", "Concepto": "pago Condominio1" } ```

Response (Aceptado): ```json { "code": "ACCP", "message": "Operación Aceptada", "reference": "16142940", "id": "6785d97e-2092-49f0-9f7d-3d5921f0b13f" } ```

Response (En Espera): ```json { "code": "AC00", "message": "Operación en Espera de Respuesta del Receptor", "Id": "e63a7892-f00f-46a4-b7d1-a6e8ac7ab094" } ```

8. Crédito Inmediato (Por Teléfono)

Realiza un crédito inmediato usando el número de teléfono del beneficiario.

Endpoint: POST /api/credito/inmediato

Authorization Token: HMAC-SHA256 de Banco + Cedula + Telefono + Monto

Request: ```json { "Banco": "0163", "Cedula": "V12345678", "Telefono": "04145555555", "Monto": "1.00", "Concepto": "Prueba 854" } ```

Response: ```json { "code": "ACCP", "message": "Operación Aceptada", "reference": "87882878", "id": "ce85d97e-2092-49f0-9f7d-3d5921f0b13c" } ```

9. Crédito Inmediato (Por Cuenta)

Realiza un crédito inmediato usando el número de cuenta de 20 dígitos.

Endpoint: POST /api/credito/cuenta

Authorization Token: HMAC-SHA256 de Cedula + Cuenta + Monto

Request: ```json { "Cedula": "V12345678", "Cuenta": "01690547895468745212", "Monto": "1.00", "Concepto": "Prueba 854" } ```

10. Domiciliación por Cuenta

Domicilia pagos usando número de cuenta de 20 dígitos.

Endpoint: POST /api/domiciliacion/cuenta

Authorization Token: HMAC-SHA256 de cuenta

Request: ```json { "docId": "V12345678", "nombre": "Raul Rojas", "cuenta": "01344578987450000015", "monto": "1.33", "concepto": "Pago" } ```

Response (Éxito): ```json { "codigo": "202", "mensaje": "Se ha recibido el mensaje de forma satisfactoria", "uuid": "04c8a596-f1c5-4c68-a984-2216ff984317" } ```

11. Domiciliación por Teléfono

Domicilia pagos usando número de teléfono.

Endpoint: POST /api/domiciliacion/telefono

Authorization Token: HMAC-SHA256 de telefono

Request: ```json { "docId": "V12345678", "telefono": "04145555555", "nombre": "Raul Lopez", "banco": "0134", "monto": "1.20", "concepto": "Pago" } ```

Nota: El primer envío es para afiliación, no genera cobro.

12. Consultar Operaciones

Consulta el estado de operaciones realizadas usando el UUID.

Endpoint: POST /api/consulta-operaciones

Authorization Token: HMAC-SHA256 de Id

Request: ```json { "Id": "e63a7892-f00f-46a4-b7d1-a6e8ac7ab094" } ```

Response: ```json { "code": "ACCP", "reference": "16413121", "success": true } ```

13. Cobro C2P

Procesa un cobro de cliente a comercio (C2P).

Endpoint: POST /api/c2p/cobro

Authorization Token: HMAC-SHA256 de TelefonoDestino + Monto + Banco + Cedula

Request: ```json { "TelefonoDestino": "04145555555", "Cedula": "V12345678", "Concepto": "PRUEBA", "Banco": "0105", "Ip": "192.168.1.20", "Monto": "1.15", "Otp": "13309525" } ```

Response (Aprobado): ```json { "message": "TRANSACCION EXITOSA", "code": "00", "reference": "59707278" } ```

14. Anulación C2P

Anula una transacción C2P previamente procesada.

Endpoint: POST /api/c2p/anular

Authorization Token: HMAC-SHA256 de Banco

Request: ```json { "Cedula": "V12345678", "Banco": "0105", "Referencia": "58945790" } ```

Response (Aprobado): ```json { "message": "TRANSACCION EXITOSA", "code": "00", "reference": "59707278" } ```

Códigos de Error

Códigos de Red Interbancaria

Código Descripción
00 APROBADO
01 REFERIRSE AL CLIENTE
05 TIEMPO DE RESPUESTA EXCEDIDO
12 TRANSACCION INVALIDA
13 MONTO INVALIDO
14 NUMERO TELEFONO RECEPTOR ERRADO
30 ERROR DE FORMATO
41 SERVICIO NO ACTIVO
43 SERVICIO NO ACTIVO
55 TOKEN INVALIDO
56 CELULAR NO COINCIDE
57 NEGADA POR EL RECEPTOR
62 CUENTA RESTRINGIDA
68 RESPUESTA TARDIA, PROCEDE REVERSO
80 CEDULA O PASAPORTE ERRADO
87 TIME OUT
90 CIERRE BANCARIO EN PROCESO
91 INSTITUCION NO DISPONIBLE
92 BANCO RECEPTOR NO AFILIADO
99 ERROR EN NOTIFICACION

Códigos ISO 20022 (Débito/Crédito Inmediato)

Código Descripción
ACCP Operación Aceptada
AC00 Operación en Espera de Respuesta del Receptor
AB01 Tiempo de espera agotado
AB07 Agente fuera de línea
AC01 Número de cuenta incorrecto
AC04 Cuenta cancelada
AC06 Cuenta bloqueada
AC09 Moneda no válida
AG01 Transacción Restringida
AG09 Pago no recibido
AG10 Agente suspendido o excluido
AM02 Monto de la transacción no permitido
AM04 Saldo insuficiente
AM05 Operación duplicada
BE01 Datos del cliente no corresponden a la cuenta
BE20 Longitud del nombre invalida
CH20 Número de decimales incorrecto
CUST Cancelación solicitada por el deudor
DS02 Operación Cancelada
DT03 Fecha de procesamiento no bancaria no válida
DU01 Identificación de mensaje duplicado
ED05 Liquidación Fallida
FF05 Código del producto incorrecto
FF07 Código del sub producto incorrecto
MD01 No posee afiliación
MD09 Afiliación inactiva
MD15 Monto incorrecto
MD21 Cobro no permitido
MD22 Afiliación suspendida
RC08 Código del Banco no existe en el sistema
RJCT Operación Rechazada
TKCM Código único de operación de débito incorrecto
VE01 Fuera del horario permitido
TM01 Rechazo técnico

Ejemplos con Bruno API

Colección Bruno: R4 Conecta API

Configuración de Entorno

Crear archivo environments/production.bru:

``` vars { baseUrl: https://r4conecta.mibanco.com.ve commerce: YOUR_COMMERCE_TOKEN licenseKey: YOUR_LICENSE_KEY } ```

1. Consulta BCV

Archivo: bcv/consulta-tasa.bru

``` meta { name: Consulta Tasa BCV type: http seq: 1 }

post { url: {{baseUrl}}/api/bcv body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "Moneda": "USD", "Fechavalor": "2024-07-23" } }

script:pre-request { const crypto = require('crypto'); const data = req.body.Fechavalor + req.body.Moneda; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

2. Vuelto (Pago Móvil)

Archivo: vuelto/pago-movil.bru

``` meta { name: Vuelto - Pago Móvil type: http seq: 2 }

post { url: {{baseUrl}}/api/vuelto body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "TelefonoDestino": "04145555555", "Cedula": "V12345678", "Banco": "0102", "Monto": "100.00", "Concepto": "Pago de prueba", "Ip": "192.168.1.1" } }

script:pre-request { const crypto = require('crypto'); const body = req.body; const data = body.TelefonoDestino + body.Monto + body.Banco + body.Cedula; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

3. Generar OTP

Archivo: debito/generar-otp.bru

``` meta { name: Generar OTP type: http seq: 3 }

post { url: {{baseUrl}}/api/otp/generar body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "Banco": "0192", "Monto": "50.00", "Telefono": "04145555555", "Cedula": "V12345678" } }

script:pre-request { const crypto = require('crypto'); const body = req.body; const data = body.Banco + body.Monto + body.Telefono + body.Cedula; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

4. Débito Inmediato

Archivo: debito/debito-inmediato.bru

``` meta { name: Débito Inmediato type: http seq: 4 }

post { url: {{baseUrl}}/api/debito/inmediato body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "Banco": "0191", "Monto": "50.00", "Telefono": "04145555555", "Cedula": "V12345678", "Nombre": "Maria Perez", "OTP": "19807849", "Concepto": "Pago servicio" } }

script:pre-request { const crypto = require('crypto'); const body = req.body; const data = body.Banco + body.Cedula + body.Telefono + body.Monto + body.OTP; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

5. Crédito Inmediato

Archivo: credito/credito-inmediato.bru

``` meta { name: Crédito Inmediato type: http seq: 5 }

post { url: {{baseUrl}}/api/credito/inmediato body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "Banco": "0163", "Cedula": "V12345678", "Telefono": "04145555555", "Monto": "100.00", "Concepto": "Pago a proveedor" } }

script:pre-request { const crypto = require('crypto'); const body = req.body; const data = body.Banco + body.Cedula + body.Telefono + body.Monto; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

6. Consultar Operaciones

Archivo: consultas/consultar-operacion.bru

``` meta { name: Consultar Operación type: http seq: 6 }

post { url: {{baseUrl}}/api/consulta-operaciones body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "Id": "e63a7892-f00f-46a4-b7d1-a6e8ac7ab094" } }

script:pre-request { const crypto = require('crypto'); const data = req.body.Id; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

7. Cobro C2P

Archivo: c2p/cobro.bru

``` meta { name: Cobro C2P type: http seq: 7 }

post { url: {{baseUrl}}/api/c2p/cobro body: json auth: none }

headers { Content-Type: application/json Commerce: {{commerce}} X-License-Key: {{licenseKey}} }

body:json { { "TelefonoDestino": "04145555555", "Cedula": "V12345678", "Concepto": "Cobro servicio", "Banco": "0105", "Ip": "192.168.1.20", "Monto": "50.00", "Otp": "13309525" } }

script:pre-request { const crypto = require('crypto'); const body = req.body; const data = body.TelefonoDestino + body.Monto + body.Banco + body.Cedula; const token = crypto.createHmac('sha256', bru.getEnvVar('commerce')) .update(data) .digest('hex'); req.setHeader('Authorization', token); } ```

Notas Importantes

  1. Validación de Licencia: Todas las peticiones requieren un hash de licencia válido con fechas activas.

  2. Rate Limiting: Máximo 100 peticiones cada 15 minutos por IP.

  3. Timeout: Las peticiones tienen un timeout de 30 segundos.

  4. Webhooks: Los endpoints de consulta y notificación deben ser implementados por el cliente con certificado TLS válido.

  5. Operaciones Asíncronas: Débito y crédito inmediato pueden retornar código AC00 (en espera). Usar endpoint de consulta de operaciones para verificar el estado final.

  6. Seguridad: Nunca exponer el token COMMERCE en el frontend. Todas las peticiones deben realizarse desde el backend.

Desarrollado por dPana Soft

Última actualización: 2025

Volver al Inicio Ir a Guía Usuario