API Admin de Gestión de Usuarios — Comfaca Créditos

El módulo de gestión de usuarios permite a los administradores de Comfaca Créditos en Línea mantener el directorio completo de cuentas del sistema. Desde estos endpoints es posible consultar el listado de usuarios con sus roles y estados, acceder al perfil detallado de cualquier cuenta, crear nuevos usuarios directamente desde el panel administrativo y aplicar cambios como modificación de roles, activación/suspensión de cuentas y actualización de datos personales. El sistema utiliza el username como identificador único en la mayoría de los flujos internos.

Todos los endpoints bajo /api/admin/users requieren una sesión activa con rol administrador. Los intentos de acceso sin privilegios recibirán 401 Unauthorized o 403 Forbidden.

GET /api/admin/users

Lista todos los usuarios del sistema con soporte de filtros por rol, estado y búsqueda de texto libre. Además de la lista, la respuesta incluye conteos por rol y por estado para alimentar los widgets del panel.

Query Parameters

number

default:"10"

Número máximo de usuarios a devolver. Entero positivo.

number

default:"0"

Desplazamiento para la paginación. Entero no negativo.

string

Filtra usuarios que tengan este rol en su array roles. Ejemplos: admin, user_trabajador, asesor.

string

Filtra por estado de la cuenta. Valores reconocidos:

active — usuario activo (is_active: true y disabled: false)
inactive — usuario inactivo (is_active: false)
suspended — usuario suspendido (disabled: true)

string

Búsqueda de texto libre sobre full_name, email y username.

Response

object

Show Estructura de la respuesta

array

Lista de usuarios transformados al formato del panel.

Show Campos de cada usuario

number

ID numérico del usuario.

string

Nombre de usuario único.

string

Correo electrónico.

string

Nombres del usuario.

string

Apellidos del usuario.

string

Nombre completo concatenado.

string

Número de documento de identidad.

string

Rol principal (primer elemento del array roles).

array

Array completo de roles asignados al usuario.

string

Estado calculado: active, inactive o suspended.

string

Fecha de creación del registro.

string

Teléfono de contacto.

number

Total de usuarios en el sistema (antes del filtrado local).

object

Objeto con el conteo de usuarios por cada rol. Ejemplo: { "admin": 3, "user_trabajador": 120, "asesor": 8 }.

object

Show Campos de conteo

number

Usuarios activos.

number

Usuarios inactivos.

number

Usuarios suspendidos.

curl -X GET "https://app.comfaca.com/api/admin/users?rol=user_trabajador&estado=active&limit=20" \
  -H "Cookie: nuxt-session=<token>"

GET /api/admin/users/:id

Obtiene el perfil completo de un usuario específico por su ID numérico.

Path Parameters

number

required

ID numérico del usuario. Se valida que sea un entero válido antes de ejecutar la consulta.

Response

object

Objeto Usuario con todos los campos del perfil. Ver estructura completa en la sección de tipos al final de esta página.

curl -X GET "https://app.comfaca.com/api/admin/users/7" \
  -H "Cookie: nuxt-session=<token>"

{
  "success": true,
  "message": null,
  "data": {
    "id": "7",
    "username": "carlos.perez",
    "nombres": "Carlos Andrés",
    "apellidos": "Pérez Gómez",
    "email": "carlos.perez@empresa.com",
    "tipo_documento": "CC",
    "numero_documento": "10245678",
    "rol": "user_trabajador",
    "estado": "active",
    "ultimo_acceso": "2024-11-14T08:30:00.000Z",
    "fecha_creacion": "2023-06-01T10:00:00.000Z",
    "telefono": "3001234567"
  },
  "timestamp": "2024-11-15T17:00:00.000Z"
}

POST /api/admin/users/create

Crea una nueva cuenta de usuario desde el panel administrativo. A diferencia del registro público, este endpoint permite asignar roles específicos y configurar el estado de la cuenta desde el momento de la creación.

Body

string

required

Nombre de usuario único en el sistema (máx. 255 caracteres). Se usa como identificador en todas las solicitudes vinculadas al usuario.

string

required

Correo electrónico válido del usuario (máx. 255 caracteres). Debe ser único en el sistema.

string

required

Contraseña inicial de la cuenta. Mínimo 8 caracteres. El usuario puede cambiarla posteriormente.

string

required

Nombre(s) del usuario (máx. 100 caracteres).

string

required

Apellido(s) del usuario (máx. 100 caracteres).

array

Array de strings con los roles a asignar. Roles disponibles en el sistema: admin, user_trabajador, asesor. Si se omite, se asigna el rol por defecto según la configuración del servicio.

boolean

Si es true, la cuenta se crea suspendida. Por defecto false (cuenta activa).

string

Tipo de documento de identidad (máx. 20 caracteres). Ejemplo: CC, CE, TI, Pasaporte.

string

Número de documento de identidad (máx. 20 caracteres).

string

Teléfono de contacto del usuario (máx. 20 caracteres).

Response

object

Show Campos del usuario creado

number

ID asignado al nuevo usuario.

string

Username de la cuenta creada.

string

Correo electrónico registrado.

string

Nombre completo generado a partir de nombre y apellido.

array

Array de roles asignados.

curl -X POST "https://app.comfaca.com/api/admin/users/create" \
  -H "Content-Type: application/json" \
  -H "Cookie: nuxt-session=<token>" \
  -d '{
    "username": "maria.torres",
    "email": "maria.torres@hospital.com",
    "password": "Segura#2024",
    "nombre": "María Lucía",
    "apellido": "Torres Vargas",
    "roles": ["user_trabajador"],
    "disabled": false,
    "tipo_documento": "CC",
    "numero_documento": "52345678",
    "telefono": "3109876543"
  }'

{
  "success": true,
  "message": "Usuario creado exitosamente",
  "data": {
    "id": 145,
    "username": "maria.torres",
    "email": "maria.torres@hospital.com",
    "full_name": "María Lucía Torres Vargas",
    "roles": ["user_trabajador"]
  },
  "timestamp": "2024-11-15T17:20:00.000Z"
}

PUT /api/admin/users/:id

Actualiza los datos de un usuario existente. Todos los campos son opcionales. Permite cambiar el rol, suspender/activar la cuenta, actualizar datos personales o restablecer la contraseña.

Path Parameters

number

required

ID numérico del usuario a actualizar.

Body

string

Nuevo username (máx. 255 caracteres).

string

Nuevo correo electrónico (máx. 255 caracteres).

string

Nueva contraseña. Mínimo 8 caracteres. Solo enviar si se desea restablecer la contraseña.

string

Nombres actualizados (máx. 100 caracteres).

string

Apellidos actualizados (máx. 100 caracteres).

array

Array de roles a asignar. Reemplaza completamente los roles actuales del usuario.

boolean

true para suspender la cuenta, false para reactivarla.

string

Tipo de documento (máx. 20 caracteres).

string

Número de documento (máx. 20 caracteres).

string

Teléfono de contacto (máx. 20 caracteres).

Response

object

Show Campos del usuario actualizado

number

ID del usuario.

string

Username actualizado.

string

Correo electrónico actualizado.

string

Nombre completo actualizado.

array

Roles vigentes tras la actualización.

# Suspender una cuenta y cambiar su rol
curl -X PUT "https://app.comfaca.com/api/admin/users/145" \
  -H "Content-Type: application/json" \
  -H "Cookie: nuxt-session=<token>" \
  -d '{
    "disabled": true,
    "roles": ["asesor"]
  }'

Endpoints de Autoservicio de Usuario

Los usuarios autenticados (cualquier rol) también pueden gestionar su propio perfil a través de los siguientes endpoints. Estos no requieren rol administrador:

GET /api/user/perfil

Obtiene el perfil del usuario actualmente autenticado. Devuelve los datos personales, tipo de documento y configuración de la cuenta.

PUT /api/user/perfil

Actualiza los datos del perfil propio: nombres, apellidos, teléfono, dirección, ciudad, barrio y tipo de vivienda.

PUT /api/user/password-change

Permite al usuario cambiar su propia contraseña proporcionando la contraseña actual y la nueva. Requiere confirmación de la nueva contraseña.

Los endpoints de autoservicio validan que el usuario solo pueda modificar su propio perfil. Un administrador que desee cambiar datos de otro usuario debe usar PUT /api/admin/users/:id.

Tipo `Usuario`

Estructura TypeScript completa del objeto usuario en el contexto administrativo:

interface Usuario {
  id: string
  username: string
  nombres: string
  apellidos: string
  email: string
  tipo_documento: string
  numero_documento: string
  rol: string
  estado: string           // "active" | "inactive" | "suspended"
  ultimo_acceso: string
  fecha_creacion: string
  telefono?: string
  codigo_categoria?: string
  empresa_nit?: string
  empresa_razon_social?: string
  direccion?: string
  ciudad?: string
  barrio?: string
  tipo_vivienda?: string
  personas_a_cargo?: number

  // Alias para compatibilidad con useShowUser
  nombre?: string
  apellido?: string
  tipo_identificacion?: string
}

Tipo `CreateUserForm`

Estructura del formulario de creación/edición de usuario:

interface CreateUserForm {
  // Credenciales
  username: string
  email: string
  password: string
  confirmPassword: string
  roles: string[]
  disabled: boolean

  // Datos personales
  nombre: string
  apellido: string
  tipo_documento: string
  numero_documento: string
  phone: string
}

// EditUserForm es un alias de CreateUserForm
type EditUserForm = CreateUserForm;

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

API Admin de Gestión de Usuarios — Comfaca Créditos

GET /api/admin/users

Query Parameters

Response

GET /api/admin/users/:id

Path Parameters

Response

POST /api/admin/users/create

Body

Response

PUT /api/admin/users/:id

Path Parameters

Body

Response

Endpoints de Autoservicio de Usuario

GET /api/user/perfil

PUT /api/user/perfil

PUT /api/user/password-change

Tipo `Usuario`

Tipo `CreateUserForm`

​GET /api/admin/users

​Query Parameters

​Response

​GET /api/admin/users/:id

​Path Parameters

​Response

​POST /api/admin/users/create

​Body

​Response

​PUT /api/admin/users/:id

​Path Parameters

​Body

​Response

​Endpoints de Autoservicio de Usuario

GET /api/user/perfil

PUT /api/user/perfil

PUT /api/user/password-change

​Tipo Usuario

​Tipo CreateUserForm

GET /api/admin/users

Query Parameters

Response

GET /api/admin/users/:id

Path Parameters

Response

POST /api/admin/users/create

Body

Response

PUT /api/admin/users/:id

Path Parameters

Body

Response

Endpoints de Autoservicio de Usuario

Tipo `Usuario`

Tipo `CreateUserForm`