Destinatarios y resolución de llaves (Bre-B)

Antes de dispersar tienes tres formas de identificar el destino:

1. Destinatario guardado (recipientId) — para beneficiarios recurrentes.
2. Resolución de llave (resolutionId) — para pagos únicos: resuelves la llave, confirmas el titular y pagas.
3. Llave directa (keyType + keyValue) — el gateway crea el destinatario por ti al dispersar.

Tipos de llave Bre-B

keyType	Formato del keyValue
ID	Documento: hasta 18 alfanuméricos, sin guiones ni espacios
PHONE	Celular: 10 dígitos, empieza por 3 (se acepta MOBILE como alias)
EMAIL	Correo: máx 92 caracteres (30 antes del @, 61 después)
ALPHA	Alias: empieza con @, 6–21 caracteres alfanuméricos en total
BCODE	Código de comercio: 10 dígitos, empieza por 00

El formato se valida antes de llamar a la red; un valor inválido responde 400 con el detalle.

Crear destinatario

POST /v1/co/breb/recipients

{
  "keyType": "PHONE",
  "keyValue": "3001234567",
  "alias": "Proveedor XYZ"
}

Campo	Tipo	Requerido	Descripción
keyType	string	✅	Ver tabla de tipos
keyValue	string	✅	Valor de la llave Bre-B del destinatario
alias	string	❌	Nombre amigable para identificarlo

Response 201 Created:

{
  "recipientId": "rcpt_8a7b6c",
  "keyType": "PHONE",
  "keyValue": "3001234567"
}

Listar destinatarios

GET /v1/co/breb/recipients

Query param	Descripción
pageSize	Resultados por página (1–100, default 20)
pageNumber	Página (default 1)

{
  "recipients": [
    {
      "recipientId": "rcpt_8a7b6c",
      "keyType": "PHONE",
      "keyValue": "3001234567",
      "alias": "Proveedor XYZ",
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "pagination": { "total_items": 1, "total_pages": 1 }
}

Consultar destinatario

GET /v1/co/breb/recipients/{recipientId}

{
  "recipientId": "rcpt_8a7b6c",
  "keyType": "PHONE",
  "keyValue": "3001234567",
  "alias": "Proveedor XYZ"
}

Eliminar destinatario

DELETE /v1/co/breb/recipients/{recipientId}

{ "recipientId": "rcpt_8a7b6c", "status": "DELETED" }

Resolver destinatario

POST /v1/co/breb/recipients/{recipientId}/resolve

Consulta a la red Bre-B (banco receptor) los datos actuales del titular de la llave del destinatario. Úsalo para mostrar el nombre del beneficiario antes de confirmar un pago.

{
  "recipientId": "rcpt_8a7b6c",
  "resolutionId": "res_1f2e3d",
  "keyType": "PHONE",
  "keyValue": "3001234567",
  "alias": "Proveedor XYZ",
  "owner": { "name": "MARIA FERNANDA G." },
  "account": { "participant_name": "Banco ABC" },
  "receptorNode": "NODE-01",
  "lastResolvedAt": "2026-06-01T10:00:00.000Z"
}

Resolver una llave (pago único)

POST /v1/co/breb/resolve-key

Resuelve a quién pertenece una llave sin crear un destinatario. El resolutionId devuelto se usa directamente en Dispersión — ideal para pagos esporádicos.

{ "keyType": "PHONE", "keyValue": "3001234567" }

Campo	Tipo	Requerido	Descripción
keyValue	string	✅	Valor de la llave a resolver
keyType	string	❌	Tipo de llave; si lo envías se valida el formato

Response 200 OK:

{
  "resolutionId": "res_9d8c7b",
  "keyType": "PHONE",
  "keyValue": "3001234567",
  "owner": { "name": "MARIA FERNANDA G." },
  "participant": { "name": "Banco ABC" },
  "account": { "account_type": "SAVINGS" },
  "receptorNode": "NODE-01",
  "resolvedAt": "2026-06-01T10:00:00.000Z",
  "expiresAt": "2026-06-01T10:05:00.000Z"
}

Precaución

La resolución expira (expiresAt). Usa el resolutionId en la dispersión antes de que venza; si expiró, vuelve a resolver.

Validar una llave

POST /v1/co/breb/validate-key

Verifica que una llave exista y esté activa, y opcionalmente compara datos del titular/cuenta sin exponer información personal: cada campo enviado responde MATCH / NO MATCH.

{
  "keyType": "PHONE",
  "keyValue": "3001234567",
  "owner": { "name": "MARIA FERNANDA G." }
}

Response 200 OK:

{
  "keyType": "PHONE",
  "keyValue": "3001234567",
  "participant": { "name": "MATCH" },
  "account": null,
  "owner": { "name": "MATCH" }
}

Si la llave no existe o no está activa, responde 404.

Errores

Código	Causa
400	keyType fuera del enum o keyValue con formato inválido
403	Servicio Bre-B no habilitado, o producción no habilitada para tu cuenta
404	Llave no encontrada o no activa (solo validate-key), o recipientId inexistente
409	Comercio sin onboarding Bre-B
422	Bre-B rechazó la operación
502	Bre-B no disponible — reintenta