Crear Cliente
Visión General
Este endpoint crea un recurso de Cliente en la plataforma PaaS al vincularlo con un Comercio (Merchant) existente que el Banco Patrocinador (Banco Sponsor) aprobó manualmente. Solo admite clientes de tipo BUSINESS (Comercio). Si la operación tiene éxito, devuelve el identificador único del cliente recién creado, sus datos de contacto, metadatos de identificación y un estado inicial ACTIVE (Activo) con marcas de tiempo. En versiones futuras, los flujos de incorporación digital reemplazarán el proceso manual de aprobación del Banco Patrocinador.
Detalles del Endpoint
| Parámetro | Descripción |
|---|---|
| Endpoint | https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers |
| Método | POST |
| Encabezados | Content-Type: application/json, Authorization |
| Autenticación | Token de Acceso (Bearer Token) |
Cuerpo de la Solicitud
| Parámetro | Tipo | Restricciones | Obligatario | Descripción |
|---|---|---|---|---|
| type | String | ENUM: BUSINESS | Sí | Tipo de cliente (BUSINESS). |
| business_name | String | 1 - 140 | Sí | Nombre legal de la empresa. |
| String | 1–35 | Sí | Dirección de correo electrónico del cliente. | |
| mobile_phone_number | String | Formato E.164, hasta 15 dígitos | Sí | Número de teléfono de contacto (ej. +573402977997). |
| identification_type | String | ENUM: NIT | Sí | Tipo de documento de identificación (NIT). |
| identification_number | String | 9 dígitos | Sí | Número de identificación único del cliente, sin dígito verificador. |
Ejemplo de Solicitud
11
11
curl --location 'https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer TU_TOKEN_DE_ACCESO' \--data '{ "type": "BUSINESS", "business_name": "ENTITY_NAME", "email": "email@yourdomain.com", "mobile_phone_number": "MOBILE_PHONE_NUMBER", "identification_type": "NIT", "identification_number": "ENTITY_NIT_NUMBER"}'Cuerpo de la Respuesta
- Código HTTP: 200 OK
- Devuelve el cliente recién creado y sus metadatos.
Ejemplo de Respuesta
9
9
{ "id": "cde52c0b-029e-47a7-b6fe-58996680611f", "mobile_phone_number": "MOBILE_PHONE_NUMBER", "type": "BUSINESS", "business_name": "ENTITY_NAME", "identification_type": "NIT", "email": "email@domain.com", "identification_number": "NIT_NUMBER"}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 la entidad. |
| 500 Server Error | Error del servidor | Se produjo un error inesperado al procesar la validación. |
Buenas Prácticas
- Asegúrate de que el tipo y número de identificación coincidan con los datos proporcionados durante el registro inicial. Esto es fundamental para que el Banco Patrocinador (Sponsor Bank) pueda validar correctamente la información y evitar errores en etapas posteriores del flujo.