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

limit

number

default:"10"

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

offset

number

default:"0"

Desplazamiento para la paginación. Entero no negativo.

rol

string

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

estado

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)

busqueda

string

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

Response

data

object

Show Estructura de la respuesta

usuarios

array

Lista de usuarios transformados al formato del panel.

Show Campos de cada usuario

number

ID numérico del usuario.

username

string

Nombre de usuario único.

string

Correo electrónico.

nombres

string

Nombres del usuario.

apellidos

string

Apellidos del usuario.

full_name

string

Nombre completo concatenado.

numero_documento

string

Número de documento de identidad.

rol

string

Rol principal (primer elemento del array roles).

roles

array

Array completo de roles asignados al usuario.

estado

string

Estado calculado: active, inactive o suspended.

fecha_creacion

string

Fecha de creación del registro.

telefono

string

Teléfono de contacto.

total

number

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

conteo_roles

object

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

conteo_estados

object

Show Campos de conteo

active

number

Usuarios activos.

inactive

number

Usuarios inactivos.

suspended

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

data

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

username

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.

password

string

required

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

nombre

string

required

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

apellido

string

required

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

roles

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.

disabled

boolean

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

tipo_documento

string

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

numero_documento

string

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

telefono

string

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

Response

data

object

Show Campos del usuario creado

number

ID asignado al nuevo usuario.

username

string

Username de la cuenta creada.

string

Correo electrónico registrado.

full_name

string

Nombre completo generado a partir de nombre y apellido.

roles

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

username

string

Nuevo username (máx. 255 caracteres).

string

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

password

string

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

nombre

string

Nombres actualizados (máx. 100 caracteres).

apellido

string

Apellidos actualizados (máx. 100 caracteres).

roles

array

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

disabled

boolean

true para suspender la cuenta, false para reactivarla.

tipo_documento

string

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

numero_documento

string

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

telefono

string

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

Response

data

object

Show Campos del usuario actualizado

number

ID del usuario.

username

string

Username actualizado.

string

Correo electrónico actualizado.

full_name

string

Nombre completo actualizado.

roles

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`

Build docs developers (and LLMs) love

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

Documentation Index

​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

Build docs developers (and LLMs) love

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`