Crear Destinatario

Visión General

Este endpoint crea un nuevo Destinatario para un Cliente específico al registrar una clave de pago en el nodo Bre-B de Visionamos – Passport. Los Destinatarios representan cuentas o llaves destino (correo, teléfono, alfanumérico, identificación nacional o código de entidad) que se usan al iniciar pagos.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/recipients/breb
Método	POST
Encabezados	Content-Type: application/json, Authorization
Autenticación	Token de Acceso (Bearer Token)

Cuerpo de la Solicitud

Parámetro	Tipo	Restricciones	Requerido	Descripción
entity_customer_id	String	UUID	Sí	Identificador único del cliente que está creando el destinatario.
key_type	String	ENUM: `ID`, `MOBILE`, `EMAIL`, ALPHA, `BCODE`	Sí	Tipo de llave utilizada para identificar al destinatario. `ID`: hasta 18 caracteres alfanuméricos sin guiones, espacios ni caracteres especiales. `PHONE`: número móvil de 10 dígitos, debe comenzar con 3. `EMAIL`: correo (máx. 92 caracteres; 30 antes del “@”, 61 después). `ALPHA`: alfanumérico de 6-21 caracteres, inicia con “@” e incluye letras y números. `BCODE`: número de entidad comercial de 10 dígitos, comienza con “00”.
key_value	String	Varía según `key_type`.	Sí	Valor de la llave del destinatario (por ejemplo, una dirección de correo electrónico).
alias	String		No	Un comentario o nombre para el destinatario.

Ejemplo de Solicitud

JSON
    
 
curl --location 'https://api.paas.sandbox.co.passportfintech.com/v1/recipients/breb' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c",
    "key": {  
        "key_type": "PHONE",
        "key_value": "3975999158"  
    },
    "alias": "Pepito SAS5"
}'
Copy

Asegúrate de que el entity_customer_id y los datos del destinatario sean válidos antes de hacer la solicitud.

Cuerpo de la Respuesta

Código HTTP: 200 OK
Retorna los datos del destinatario creado junto con su ID único.

Ejemplo de Respuesta

JSON
    
 
{
    "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c",
    "key": {
        "key_type": "PHONE",
        "key_value": "3975999158"
    },
    "type": "BREB",
    "updated_at": "2025-10-10T07:43:41.267Z",
    "created_at": "2025-10-10T07:43:41.267Z",
    "alias": "Pepito SAS5",
    "id": "daa209f9-fbdf-4f2b-aadc-db42fe16358c"
}
Copy

El campo id es el identificador único del destinatario, que se utilizará para futuras transacciones Bre-B.

Errores Comunes y Manejo

Código HTTP	Significado	Descripción
400 Bad Request	Datos inválidos	Faltan campos requeridos o contienen valores incorrectos.
401 Unauthorized	Token inválido	El token de acceso ha expirado o es inválido.
403 Forbidden	Acceso denegado	La solicitud no está autorizada para validar crear un destinatario.
500 Server Error	Error del servidor	Se produjo un error inesperado durante la creación del destinatario.

Buenas Prácticas

Verifica que el customer_id pertenezca a un cliente válido.
Valida que el key_type y el key_value del destinatario sean correctos y cumplan con el formato esperado.

Última actualización el