POST /api/auth/login

El endpoint de login es la puerta de entrada a Comfaca Créditos en Línea. Recibe las credenciales del afiliado, las valida contra el backend de autenticación y, si son correctas, establece una cookie de sesión segura con una vida útil de 8 horas. Todos los endpoints protegidos de la API requieren que esta cookie esté presente y sea válida. La validación del cuerpo de la petición se realiza con Zod antes de llegar al servicio de autenticación; cualquier campo faltante o inválido devuelve un 422 con los detalles del error antes de realizar ninguna consulta al backend.

Autenticación: No requiere autenticación previa.

Cuerpo de la petición

username

string

required

Nombre de usuario registrado en Comfaca Créditos. Debe tener al menos 3 caracteres. Generalmente corresponde al número de documento o al email del afiliado.

password

string

required

Contraseña del usuario. Debe tener al menos 8 caracteres.

Respuestas

success

boolean

true cuando las credenciales son válidas y la sesión fue creada exitosamente.

message

string

Mensaje descriptivo del resultado, por ejemplo "Login completado.".

data

object

Objeto con los datos del usuario autenticado y el token de sesión.

Show Propiedades de data

data.user

object

Datos del usuario autenticado.

Show Propiedades de user

data.user.username

string

Nombre de usuario único en el sistema.

data.user.email

string

Correo electrónico del usuario.

data.user.nombres

string

Nombres del afiliado tal como fueron registrados (en mayúsculas).

data.user.apellidos

string

Apellidos del afiliado (en mayúsculas).

data.user.tipo_documento

string

Código del tipo de documento de identidad (ej. "CC", "CE").

data.user.numero_documento

string

Número de documento de identidad del afiliado.

data.user.telefono

string

Número de teléfono móvil del afiliado.

data.user.roles

string[]

Lista de roles asignados al usuario, por ejemplo ["afiliado"] o ["administrator"].

data.message

string

Mensaje adicional proveniente del servicio de autenticación.

Tabla de errores

Código HTTP	Causa	Descripción
`401`	Credenciales inválidas	El `username` o `password` no coinciden con ningún usuario registrado.
`422`	Error de validación Zod	El cuerpo de la petición no cumple el esquema: `username` < 3 caracteres, `password` < 8 caracteres o campos ausentes.
`500` / `502`	Error interno	Fallo al conectar con el backend de autenticación o error inesperado del servidor.

Ejemplo — cURL

curl -X POST http://localhost:4000/api/auth/login \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{"username": "usuario@empresa.com", "password": "miPassword123"}'

La bandera -c cookies.txt guarda la cookie de sesión en un archivo local. Úsala junto con -b cookies.txt en las peticiones subsiguientes para enviar la sesión automáticamente.

Ejemplo — Respuesta exitosa `200`

{
  "success": true,
  "message": "Login completado.",
  "data": {
    "user": {
      "username": "usuario@empresa.com",
      "email": "USUARIO@EMPRESA.COM",
      "nombres": "JUAN CARLOS",
      "apellidos": "PÉREZ GÓMEZ",
      "tipo_documento": "CC",
      "numero_documento": "1012345678",
      "telefono": "3001234567",
      "roles": ["afiliado"]
    },
    "message": "Bienvenido a Comfaca Créditos."
  }
}

Ejemplo — Error `401` (credenciales inválidas)

{
  "success": false,
  "message": "Error en el proceso de login.",
  "error": "Credenciales inválidas"
}

Ejemplo — Error `422` (validación Zod)

{
  "success": false,
  "message": "Error en el proceso de login.",
  "error": "Password debe tener al menos 8 caracteres"
}

La sesión creada por este endpoint tiene una duración máxima de 8 horas (maxAge: 60 * 60 * 8). Pasado ese tiempo, la cookie expira automáticamente y el usuario deberá autenticarse de nuevo. Para cerrar la sesión de forma explícita, consulta POST /api/auth/logout.

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

POST /api/auth/login — Iniciar Sesión en Comfaca Créditos

Cuerpo de la petición

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

Ejemplo — Error `401` (credenciales inválidas)

Ejemplo — Error `422` (validación Zod)

Build docs developers (and LLMs) love

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

Documentation Index