Usuarios

Endpoints para registro, consulta y gestión de usuarios.

Navegación Rápida

📝 Registro de Usuario
👤 Consultar Perfil
✏️ Editar Perfil
🔐 Cambiar Contraseña
🔑 Recuperar Contraseña

Registro de Usuario

Crea una nueva cuenta de usuario en la plataforma.

Este endpoint solo requiere API Key, no necesita autenticación previa.

Endpoint

POST /user/

Headers

Content-Type: application/json
Accept: application/json
x-api-key: [API_KEY]

Request Body

Campo	Tipo	Requerido	Descripción
`username`	string	✅	Debe ser email válido para PANEL/API
`email`	string	✅	Correo electrónico (se convierte a minúsculas)
`password`	string	✅	Contraseña (max 100 chars)
`phone`	string	✅	Número de teléfono sin código país
`country_code`	string	❌	Código de país (ej: `57` para Colombia)
`first_name`	string	❌	Nombre (max 100 chars)
`last_name`	string	❌	Apellido (max 100 chars)

Campo	Tipo	Requerido	Descripción
`document_type`	string	❌	Tipo: `CC`, `CE`, `NIT`, `PASSPORT`
`document_number`	string	❌	Número de documento
`type_person`	int	✅	`1` = NATURAL, `2` = JURIDICAL
`country_company_incorporation`	string	⚠️	Requerido si `type_person=2`
`gender`	string	❌	Género del usuario
`date_birth`	string	❌	Fecha de nacimiento
`platform`	string	❌	`API`, `PANEL`, `IOS`, `ANDROID`
`referal_code`	string	❌	Código de referido
`profile_picture`	string	❌	URL de foto de perfil

request.json

{
  "username": "usuario@ejemplo.com",
  "email": "usuario@ejemplo.com",
  "password": "Password123!",
  "first_name": "Juan",
  "last_name": "Pérez",
  "phone": "3001234567",
  "country_code": "57",
  "document_type": "CC",
  "document_number": "1234567890",
  "type_person": 1,
  "platform": "API"
}

curl -X POST https://dev.backend.colurs.co/user/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: [API_KEY]" \
  -d '{
    "username": "usuario@ejemplo.com",
    "email": "usuario@ejemplo.com",
    "password": "Password123!",
    "first_name": "Juan",
    "last_name": "Pérez",
    "phone": "3001234567",
    "country_code": "57",
    "document_type": "CC",
    "document_number": "1234567890",
    "type_person": 1,
    "platform": "API"
}'

Tipos de Persona

Valor	Tipo	Descripción
`1`	NATURAL	Persona natural
`2`	JURIDICAL	Persona jurídica (empresa)

⚠️

Para personas jurídicas (type_person=2): El campo country_company_incorporation es obligatorio.

Campos para Persona Jurídica

Si type_person=2, puedes enviar datos del representante legal:

Campo	Descripción
`document_type_legal`	Tipo de documento del representante
`document_number_legal`	Número de documento del representante
`name_legal`	Nombre del representante
`last_name_legal`	Apellido del representante
`date_birth_legal`	Fecha de nacimiento del representante
`gender_legal`	Género del representante

Validaciones

⚠️

El sistema valida que no existan duplicados antes de crear el usuario.

✅ Email único — No puede existir otro usuario con el mismo email
✅ Username único — No puede existir otro usuario con el mismo username
✅ Teléfono único — No puede existir otro usuario con el mismo teléfono
✅ Documento único — No puede existir otro usuario con el mismo documento
✅ Username = Email — Para plataformas PANEL y API, el username debe ser un email válido

Respuesta Exitosa

201 CREATED

{
  "id": 123,
  "username": "usuario@ejemplo.com",
  "email": "usuario@ejemplo.com",
  "first_name": "Juan",
  "last_name": "Pérez"
}

Errores

Código	Error	Descripción
`400`	`InvalidReferrer`	Código de referido inválido
`400`	`ProfileAlreadyReferred`	El perfil ya tiene un referido asignado
`404`	`ReferalCodeNotExist`	El código de referido no existe
`400`	`TypePersonRequired`	Tipo de persona requerido
`400`	`InfoBusinessDoesNotExist`	Información de negocio no existe
`400`	`IntegrationException`	Error en integración externa

Consultar Perfil

Obtiene la información del perfil del usuario autenticado.

Endpoint

GET /user/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]

Parámetros Query

Parámetro	Tipo	Descripción
`lite`	boolean	Retorna versión reducida del perfil

Respuesta

GET /user/

{
  "id": 123,
  "uuid": "abc-123-def-456",
  "username": "usuario@ejemplo.com",
  "email": "usuario@ejemplo.com",
  "first_name": "Juan",
  "last_name": "Pérez",
  "alias": "jperez",
  "phone": "3001234567",
  "country": "CO",
  "country_code": "57",
  "city": "Bogotá",
  "address": "Calle 123 #45-67",
  "document_type": "CC",
  "document_number": "1234567890",
  "phone_verified": true,
  "email_verified": true,
  "type_person": "NATURAL",
  "level": 5,
  "document_status": "APPROVED",
  "has_pin": true,
  "has_otp": false,
  "roles": ["user"],
  "last_login": "2024-01-15T10:30:00Z",
  "platform": "API"
}

GET /user/?lite=true

{
  "id": 123,
  "username": "usuario@ejemplo.com",
  "email": "usuario@ejemplo.com",
  "phone_verified": true,
  "email_verified": true,
  "level": 5
}

Datos Básicos:

id, uuid, username, email
first_name, last_name, alias, url
phone, country_code, country, city, address
document_type, document_number
gender, date_birth, date_expiration
profile_picture

Estado:

phone_verified, email_verified
type_person (NATURAL/JURIDICAL)
level, document_status
has_pin, has_otp
platform, last_login, ip

Fees y Límites:

fee_iva, fee_pse, withdraw_fee
fee_payment, fee_withdraw, fee_reload, fee_send
fee_efecty, fee_baloto
reload_tier_1, reload_tier_2, reload_tier_3, reload_tier_4
min_transaction_quantity, max_transaction_quantity
min_reload_quantity, max_reload_quantity
balance_limit, amount_balance_limit

Configuración:

payment_methods_configuration
roles (grupos del usuario)
onboarding (estado del proceso)
country_company_incorporation
wallet_info_enabled
has_uma_profile
show_referral_panel
merchant_id, is_merchant

Campos del Perfil

Campo	Tipo	Descripción
`id`	int	ID único del perfil
`uuid`	string	UUID universal
`username`	string	Nombre de usuario (email)
`email`	string	Correo electrónico
`first_name`	string	Nombre
`last_name`	string	Apellido
`phone`	string	Teléfono
`country_code`	string	Código de país
`phone_verified`	boolean	¿Teléfono verificado?
`email_verified`	boolean	¿Email verificado?
`type_person`	string	`NATURAL` o `JURIDICAL`
`level`	int	Nivel de validación (0-5)
`has_pin`	boolean	¿Tiene PIN configurado?
`has_otp`	boolean	¿Tiene 2FA habilitado?
`is_merchant`	boolean	¿Es comerciante?

Editar Perfil

Actualiza la información del perfil del usuario autenticado.

Endpoint

POST /edit_profile/

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Campos Editables

Editar datos personales

{
  "first_name": "Juan Carlos",
  "last_name": "Pérez García",
  "alias": "jcperez",
  "phone": "3009876543",
  "gender": "M",
  "date_birth": "1990-01-15",
  "date_expiration": "2030-01-15",
  "profile_picture": "https://ejemplo.com/foto.jpg"
}

Editar ubicación

{
  "country": "CO",
  "city": "Medellín",
  "address": "Carrera 50 #10-20"
}

Editar IVA

{
  "fee_iva": 19.0
}

Esto crea o actualiza un CustomConfiguration para el perfil.

Configurar métodos de pago

{
  "payment_methods_configuration": {
    "pse": true,
    "nequi": true,
    "bancolombia": true,
    "efecty": false
  }
}

Configurar métodos de recarga

{
  "payment_methods_configuration_reload": {
    "bancolombia": true,
    "pse": true,
    "nequi": false
  }
}

Aplicar Código de Referido

Aplicar código de referido

{
  "referal_code": "ABC123"
}

🎁

Al aplicar un código de referido válido, se actualizan automáticamente: - max_transaction_quantity - payment_methods_configuration - payment_methods_configuration_reload

Respuesta Exitosa

200 OK

{
  "message": "Profile edited successfully"
}

O para configuraciones específicas:

200 OK

{
  "result": "ok"
}

Errores

Código	Error	Descripción
`404`	`UNABLE_TO_GET_PROFILE`	Perfil no encontrado
`400`	`UserToEditExist`	El usuario a editar ya existe
`400`	`UserByEmail`	Email ya en uso por otro usuario
`400`	`UserByPhoneExist`	Teléfono ya en uso por otro usuario

Cambiar Contraseña

Actualiza la contraseña del usuario autenticado.

🔒

Por seguridad, se requiere la contraseña actual y confirmar la nueva contraseña.

Endpoint

PUT /profile/change-password

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Request

request.json

{
  "old_password": "ContraseñaActual123",
  "new_password": "NuevaContraseña456!",
  "new_password_confirmation": "NuevaContraseña456!"
}

Campo	Tipo	Requerido	Descripción
`old_password`	string	✅	Contraseña actual
`new_password`	string	✅	Nueva contraseña
`new_password_confirmation`	string	✅	Confirmación de nueva contraseña

Validaciones

✅ La contraseña actual debe ser correcta
✅ new_password debe ser igual a new_password_confirmation
✅ Rate limiting implementado para prevenir ataques de fuerza bruta

Respuesta

200 OK

{
  "message": "Password updates successfully."
}

Errores

Código	Error	Descripción
`429`	`PasswordInTimeout`	Demasiados intentos, espera antes de reintentar
`400`	`PasswordNotMatch`	Contraseña actual incorrecta

Recuperar Contraseña

Proceso para recuperar acceso cuando el usuario olvidó su contraseña.

Este endpoint solo requiere API Key, no necesita autenticación.

Endpoint - Solicitar Recuperación

POST /password_recovery_request/

Headers

Content-Type: application/json
x-api-key: [API_KEY]

Request

request.json

{
  "email": "usuario@ejemplo.com"
}

Flujo de Recuperación

Paso 1: Solicitar recuperación

El usuario envía su email al endpoint /password_recovery_request/.

Paso 2: Recibir código

El sistema envía un código de verificación al email del usuario.

Paso 3: Validar código

El usuario ingresa el código recibido para validar su identidad.

Paso 4: Establecer nueva contraseña

El usuario puede establecer una nueva contraseña.

Niveles de Validación

El sistema maneja diferentes niveles de verificación de identidad:

📊

El nivel determina qué operaciones puede realizar el usuario.

Nivel	Estado	Descripción
`0`	🔴 Sin validar	Usuario recién creado
`1`	🟡 Pendiente	Documentos enviados, en revisión
`2`	🟠 Con errores	Documentos rechazados
`5`	🟢 Validado	Verificación completa

Nivel 0 - Sin validar

Usuario nuevo, solo puede ver su perfil. No puede realizar transacciones.

Nivel 1 - Pendiente

Documentos enviados, esperando aprobación del equipo de compliance.

Nivel 2 - Con errores

Documentos rechazados por alguna razón. El usuario debe reenviar documentación.

Nivel 5 - Completamente validado

Acceso completo a todas las funcionalidades de la plataforma.

Colaboradores

Si el usuario es un colaborador (no un perfil regular), la respuesta del GET /user/ retorna datos del ColaboratorSerializer en lugar del ProfileSerializer.

👥

Los colaboradores son usuarios con roles especiales que pertenecen a una organización.

Autenticación Verificación