Gestión de Sesión: GET /api/auth/me y POST /api/auth/logout

Una vez que el afiliado inicia sesión mediante POST /api/auth/login, el servidor establece una cookie de sesión HTTP firmada con una duración de 8 horas (maxAge: 60 * 60 * 8). Esta cookie es enviada automáticamente por el navegador en cada petición subsiguiente, permitiendo a la API identificar al usuario autenticado a través de event.context.user. Esta página documenta los tres endpoints de gestión de sesión: consultar la sesión activa, cerrarla y recuperar contraseña olvidada.

GET /api/auth/me

Devuelve los datos del usuario autenticado en la sesión actual. El middleware global de la aplicación inyecta el usuario en event.context.user antes de que llegue al handler; si la sesión no existe o expiró, el endpoint responde con 401. Autenticación: Requiere cookie de sesión válida.

Respuestas

boolean

true cuando hay una sesión activa válida.

string

"Usuario autenticado" en caso de éxito.

object

Objeto que contiene la información del usuario de la sesión.

Show Propiedades de data

object

Datos del usuario autenticado actualmente.

Show Propiedades de user

string

Nombre de usuario único.

string

Correo electrónico del usuario (en mayúsculas).

string

Nombres del afiliado (en mayúsculas).

string

Apellidos del afiliado (en mayúsculas).

string

Código del tipo de documento, por ejemplo "CC".

string

Número de documento de identidad.

string

Teléfono móvil del afiliado.

string[]

Lista de roles asignados al usuario (ej. ["afiliado"], ["administrator"]).

Tabla de errores

Código HTTP	Causa	Descripción
`401`	Sin sesión	No hay cookie de sesión o la sesión ha expirado.

Ejemplo — cURL

curl -X GET http://localhost:4000/api/auth/me \
  -H 'Content-Type: application/json' \
  -b cookies.txt

Ejemplo — Respuesta exitosa `200`

{
  "success": true,
  "message": "Usuario autenticado",
  "data": {
    "user": {
      "username": "juan.perez",
      "email": "JUAN.PEREZ@EMPRESA.COM",
      "nombres": "JUAN CARLOS",
      "apellidos": "PÉREZ GÓMEZ",
      "tipo_documento": "CC",
      "numero_documento": "1012345678",
      "telefono": "3001234567",
      "roles": ["afiliado"]
    }
  }
}

Ejemplo — Error `401`

{
  "success": false,
  "message": "No autenticado",
  "error": "No autenticado"
}

POST /api/auth/logout

Cierra la sesión del usuario autenticado limpiando la cookie de sesión del servidor mediante clearUserSession. Después de esta llamada, cualquier petición que requiera autenticación devolverá 401 hasta que el usuario vuelva a hacer login. Autenticación: Requiere cookie de sesión válida (aunque puede llamarse sin sesión activa sin causar error).

Respuestas

boolean

Siempre true en la respuesta de logout exitoso.

string

"Sesión cerrada correctamente".

null

Siempre null.

Ejemplo — cURL

curl -X POST http://localhost:4000/api/auth/logout \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -c cookies.txt

Ejemplo — Respuesta exitosa `200`

{
  "success": true,
  "message": "Sesión cerrada correctamente",
  "data": null
}

Después de llamar a este endpoint, elimina el archivo de cookies local (cookies.txt) si usas cURL, o borra la cookie nuxt-session de tu cliente HTTP para garantizar que no se envíe en futuras peticiones.

POST /api/auth/recovery

Inicia el proceso de recuperación de contraseña para un afiliado que olvidó sus credenciales. El endpoint envía un email al correo registrado del usuario con un enlace o código para restablecer la contraseña. Autenticación: No requiere autenticación previa.

Cuerpo de la petición

El cuerpo es leído directamente con readBody (sin validación Zod estricta en este handler). Se recomienda enviar los siguientes campos:

string

Correo electrónico asociado a la cuenta. El servicio de recuperación usa este campo para identificar al usuario.

string

Nombre de usuario alternativo para identificar la cuenta cuando no se dispone del email.

Respuestas

boolean

true cuando el proceso de recuperación fue iniciado y el email fue enviado.

string

Confirmación del envío del email de recuperación.

object

Datos de confirmación del proceso de recuperación devueltos por el backend.

Tabla de errores

Código HTTP	Causa	Descripción
`404`	Usuario no encontrado	No existe un usuario con el email o username proporcionado.
`502`	Error de backend	Fallo al conectar con el servicio de autenticación o al enviar el email.

Ejemplo — cURL

curl -X POST http://localhost:4000/api/auth/recovery \
  -H 'Content-Type: application/json' \
  -d '{"email": "juan.perez@empresa.com"}'

Ejemplo — Respuesta exitosa `200`

{
  "success": true,
  "data": {
    "message": "Se ha enviado un enlace de recuperación a su correo registrado."
  }
}

POST /api/validacion/codigo-firma

Valida un código de 6 dígitos enviado por el afiliado durante el proceso de firma digital. Si el código es correcto, invoca el servicio de Sisuweb para crear las claves de firma digital (keypublic, keyprivate, certificado) asociadas al usuario autenticado. Autenticación: Requiere cookie de sesión válida.

Cuerpo de la petición

El cuerpo de la petición se valida con Zod antes de procesarse.

string

required

Código de firma de exactamente 6 caracteres recibido por el afiliado. La validación Zod aplica z.string().length(6).

Respuestas

boolean

true cuando el código es válido y las claves de firma digital fueron generadas exitosamente.

string

"Datos obtenidos exitosamente." en caso de éxito.

object

Claves de la firma digital generada para el usuario.

Show Propiedades de data

string | null

Certificado digital generado por el servicio de Sisuweb. null si el servicio no lo devolvió.

string | null

Clave pública del par de claves de firma. null si el servicio no lo devolvió.

string | null

Clave privada del par de claves de firma. null si el servicio no lo devolvió.

string | null

Contraseña de la clave privada tal como la devuelve el servicio (nótese la ortografía passowrd, que refleja el campo original de Sisuweb). null si el servicio no lo devolvió.

Tabla de errores

Código HTTP	Causa	Descripción
`200`	Código inválido	El cuerpo no pasa la validación Zod (`codigo` ausente o con longitud distinta de 6). `success: false` en el cuerpo.
`401`	Sin sesión	No hay cookie de sesión o la sesión ha expirado.
`200`	Error interno	El servicio de Sisuweb falló o el usuario no fue encontrado. `success: false` en el cuerpo.

Este endpoint devuelve 200 incluso en algunos errores de validación o de servicio, con success: false en el cuerpo de la respuesta. El cliente debe verificar siempre el campo success antes de usar el resultado.

Ejemplo — cURL

curl -X POST http://localhost:4000/api/validacion/codigo-firma \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"codigo": "482931"}'

Ejemplo — Respuesta exitosa `200`

{
  "success": true,
  "message": "Datos obtenidos exitosamente.",
  "data": {
    "certificado": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
    "keypublic": "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...",
    "keyprivate": "-----BEGIN PRIVATE KEY-----\nMIIEvAIB...",
    "passowrd": "482931"
  }
}

Ejemplo — Error de validación (código inválido)

{
  "success": false,
  "message": "Código inválido o faltante"
}

Duración de la sesión

La sesión de Comfaca Créditos tiene una duración de 8 horas configuradas en nuxt.config.ts:

nuxtSession: {
  maxAge: 60 * 60 * 8  // 8 horas en segundos = 28 800 segundos
}

Parámetro	Valor
Duración máxima	8 horas
Mecanismo	Cookie HTTP `nuxt-session` firmada con JWT
Renovación	No automática — el usuario debe volver a hacer login al expirar
Cierre explícito	`POST /api/auth/logout`

Las sesiones no se renuevan automáticamente. Si el afiliado realiza una petición con una sesión expirada, recibirá un 401. La aplicación frontend debe interceptar estos errores y redirigir al usuario a la pantalla de login.

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

Gestión de Sesión: GET /api/auth/me y POST /api/auth/logout

GET /api/auth/me

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

Ejemplo — Error `401`

POST /api/auth/logout

Respuestas

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

POST /api/auth/recovery

Cuerpo de la petición

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

POST /api/validacion/codigo-firma

Cuerpo de la petición

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

Ejemplo — Error de validación (código inválido)

Duración de la sesión

​GET /api/auth/me

​Respuestas

​Tabla de errores

​Ejemplo — cURL

​Ejemplo — Respuesta exitosa 200

​Ejemplo — Error 401

​POST /api/auth/logout

​Respuestas

​Ejemplo — cURL

​Ejemplo — Respuesta exitosa 200

​POST /api/auth/recovery

​Cuerpo de la petición

​Respuestas

​Tabla de errores

​Ejemplo — cURL

​Ejemplo — Respuesta exitosa 200

​POST /api/validacion/codigo-firma

​Cuerpo de la petición

​Respuestas

​Tabla de errores

​Ejemplo — cURL

​Ejemplo — Respuesta exitosa 200

​Ejemplo — Error de validación (código inválido)

​Duración de la sesión

GET /api/auth/me

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

Ejemplo — Error `401`

POST /api/auth/logout

Respuestas

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

POST /api/auth/recovery

Cuerpo de la petición

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

POST /api/validacion/codigo-firma

Cuerpo de la petición

Respuestas

Tabla de errores

Ejemplo — cURL

Ejemplo — Respuesta exitosa `200`

Ejemplo — Error de validación (código inválido)

Duración de la sesión