Ir al contenido
Bolívar Connect

Dar de alta un beneficiario de dispersión

POST/beneficiariesProbar

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST
/beneficiaries
curl --request POST \
  --url http://localhost:3000/v1/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "fullName": "María Gómez", "nationalId": "V12345678", "bankCode": "0134", "accountNumber": "01340000123456789012", "phone": "04141234567" }'

Scope beneficiaries:write. El alta es idempotente por (cédula, banco, instrumento): reenviar los mismos datos devuelve el mismo beneficiario (created: false) en vez de duplicarlo.

phone hace falta SIEMPRE, también para transferencia: el riel de bolívares exige el móvil del beneficiario en los dos instrumentos, y un beneficiario sin teléfono falla al dispersar aunque se haya dado de alta sin problema. La transferencia necesita además accountNumber.

Se valida antes de gastar una llamada al riel:

  • cédula o RIF V/E/J/G/P + 6 a 9 dígitos (V12345678);

  • bankCode de 4 dígitos, y del catálogo del instrumento que vas a usar (GET /payouts/banks?method=…);

  • accountNumber sólo dígitos, de 16 a 20 —en la práctica venezolana son 20— y empieza por el bankCode;

  • phone en formato 04XXXXXXXXX (obligatorio para dispersar por cualquiera de los dos instrumentos).

El rechazo más frecuente de un banco venezolano es que el nombre o la cédula no coincidan con el titular de esa cuenta o ese teléfono: manda el fullName tal como lo tiene el banco destino.

Authorizations

Sección titulada «Authorizations»

Request Bodyrequired

Sección titulada «Request Bodyrequired»
Media typeapplication/json

phone es necesario para dispersar por cualquiera de los dos instrumentos: el riel de bolívares exige el móvil del beneficiario también en transferencia. Para transferencia hace falta además accountNumber.

El alta acepta un beneficiario con sólo uno de los dos campos —no se rechaza— pero un beneficiario sin phone fallará al dispersar con beneficiary_missing_phone.

object
fullName
required

Nombre del titular TAL COMO lo tiene el banco destino

string
nationalId
required

Cédula o RIF: V/E/J/G/P + 6 a 9 dígitos

string
bankCode
required

Banco destino, 4 dígitos

string
accountNumber

Sólo dígitos, de 16 a 20 (en la práctica venezolana, 20), y debe empezar por el bankCode. Necesario para transferencia.

string
nullable
phone

Móvil del beneficiario, formato 04XXXXXXXXX. Necesario para los DOS instrumentos, no sólo para pago móvil.

string
nullable
asset
string
Allowed values: BS USD USDC VESC
country
string
Examples

Abono en cuenta (transferencia) — el móvil también hace falta

{
  "fullName": "María Gómez",
  "nationalId": "V12345678",
  "bankCode": "0134",
  "accountNumber": "01340000123456789012",
  "phone": "04141234567"
}

Responses

Sección titulada «Responses»

201

Sección titulada «201»

Beneficiario (nuevo o ya existente)

Media typeapplication/json
object
id
string format: uuid
full_name
string
national_id
string
bank_code
string
account_number
string
nullable
phone
string
nullable
asset
string
Allowed values: BS USD USDC VESC
country
string
status
string
Allowed values: active blocked
payout_count

Cuántas dispersiones le han llegado bien. Señal antifraude.

integer
last_success_at
string format: date-time
nullable
last_failure_reason
string
nullable
created_at
string format: date-time
created

False si ya existía con esos datos

boolean
Example
{
  "id": "8ade3e33-6f1c-4d0a-9d33-2c6b0a41f7e2",
  "full_name": "María Gómez",
  "national_id": "V12345678",
  "bank_code": "0134",
  "account_number": "01340000123456789012",
  "phone": "04141234567",
  "asset": "BS",
  "country": "VE",
  "status": "active",
  "payout_count": 0,
  "last_success_at": null,
  "last_failure_reason": null,
  "created_at": "2026-08-31T19:02:11.004Z",
  "created": true
}

400

Sección titulada «400»

Error con código estable

Media typeapplication/json
object
error
object
meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object
key
additional properties
any
type
string
Allowed values: invalid_request_error authentication_error rate_limit_error provider_error api_error
code

Código ESTABLE. Programa contra esto.

string
message
string
request_id
string
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

401

Sección titulada «401»

Error con código estable

Media typeapplication/json
object
error
object
meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object
key
additional properties
any
type
string
Allowed values: invalid_request_error authentication_error rate_limit_error provider_error api_error
code

Código ESTABLE. Programa contra esto.

string
message
string
request_id
string
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

403

Sección titulada «403»

Error con código estable

Media typeapplication/json
object
error
object
meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object
key
additional properties
any
type
string
Allowed values: invalid_request_error authentication_error rate_limit_error provider_error api_error
code

Código ESTABLE. Programa contra esto.

string
message
string
request_id
string
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}