Logs

Tag: logs
Descripción: Operaciones para consulta y gestión de logs de auditoría

---

1. Crear registro de log (POST /logs)

• Descripción: Crea un nuevo registro de actividad en el sistema (usualmente automático)
• Operation ID: LogsController_create
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o sistema interno)

Request Body

{
    "action": "user_login",
    "userId": 123,
    "companyId": 456,
    "details": "Inicio de sesión exitoso",
    "metadata": {
        "ip": "192.168.1.1",
        "device": "Mobile/Android"
    }
}

Responses

Código	Descripción
201	Log creado exitosamente
400	Datos de entrada inválidos
401	No autorizado

---

2. Listar todos los logs (GET /logs)

• Descripción: Obtiene los registros de actividad con filtros avanzados
• Operation ID: LogsController_findAll
• Autenticación requerida: 🔒 Sí (ROLE_AUDITOR)

Query Parameters

Parámetro	Tipo	Requerido	Descripción
page	integer	❌ No	Número de página (default: 1)
limit	integer	❌ No	Límite por página (default: 50, max: 200)
userId	integer	❌ No	Filtrar por ID de usuario
companyId	integer	❌ No	Filtrar por ID de compañía
action	string	❌ No	Filtrar por tipo de acción
startDate	datetime	❌ No	Fecha inicio (ISO 8601)
endDate	datetime	❌ No	Fecha fin (ISO 8601)
sortBy	string	❌ No	Campo para ordenar (timestamp, action)
sortOrder	string	❌ No	Orden (asc/desc)

Responses

Código	Descripción
200	Lista de logs obtenida
400	Parámetros inválidos
401	No autorizado

---

3. Obtener logs por usuario (GET /logs/user/:userId)

• Descripción: Obtiene los registros de actividad de un usuario específico
• Operation ID: LogsController_findByUser
• Autenticación requerida: 🔒 Sí (ROLE_AUDITOR o usuario propietario)

Path Parameters

Parámetro	Tipo	Descripción
userId	integer	ID del usuario

Query Parameters

Parámetro	Tipo	Requerido	Descripción
days	integer	❌ No	Últimos N días (default: 30)

Responses

Código	Descripción
200	Logs del usuario obtenidos
401	No autorizado
404	Usuario no encontrado

---

4. Obtener logs por compañía (GET /logs/company/:companyId)

• Descripción: Obtiene los registros de actividad de una compañía específica
• Operation ID: LogsController_findByCompany
• Autenticación requerida: 🔒 Sí (ROLE_AUDITOR o admin de compañía)

Path Parameters

Parámetro	Tipo	Descripción
companyId	integer	ID de la compañía

Query Parameters

Parámetro	Tipo	Requerido	Descripción
action	string	❌ No	Filtrar por tipo de acción

Responses

Código	Descripción
200	Logs de la compañía obtenidos
401	No autorizado
404	Compañía no encontrada

---

5. Obtener log específico (GET /logs/:id)

• Descripción: Obtiene un registro de actividad específico por su ID
• Operation ID: LogsController_findOne
• Autenticación requerida: 🔒 Sí (ROLE_AUDITOR)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del log

Responses

Código	Descripción
200	Log obtenido exitosamente
401	No autorizado
404	Log no encontrado

---

6. Actualizar log (PATCH /logs/:id)

• Descripción: Actualiza los detalles o metadata de un log (uso restringido)
• Operation ID: LogsController_update
• Autenticación requerida: 🔒 Sí (ROLE_SUPER_ADMIN)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del log

Request Body

{
    "details": "Corrección: Inicio de sesión fallido",
    "metadata": {
        "reason": "Credenciales inválidas"
    }
}

Responses

Código	Descripción
200	Log actualizado exitosamente
400	Datos de entrada inválidos
401	No autorizado
403	Prohibido
404	Log no encontrado

---

7. Eliminar log (DELETE /logs/:id)

• Descripción: Elimina permanentemente un registro de actividad (uso altamente restringido)
• Operation ID: LogsController_remove
• Autenticación requerida: 🔒 Sí (ROLE_SUPER_ADMIN)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del log

Responses

Código	Descripción
204	Log eliminado exitosamente
401	No autorizado
403	Prohibido
404	Log no encontrado

---

Resumen de Endpoints de Logs

Método	Endpoint	Descripción	Permiso Requerido
POST	/logs	Crear nuevo log	ROLE_ADMIN/Sistema
GET	/logs	Listar logs con filtros	ROLE_AUDITOR
GET	/logs/user/:userId	Obtener logs por usuario	ROLE_AUDITOR/Usuario
GET	/logs/company/:companyId	Obtener logs por compañía	ROLE_AUDITOR/Admin
GET	/logs/:id	Obtener log específico	ROLE_AUDITOR
PATCH	/logs/:id	Actualizar log	ROLE_SUPER_ADMIN
DELETE	/logs/:id	Eliminar log permanentemente	ROLE_SUPER_ADMIN

Modelo de Datos

interface Log {
    id: number;
    action: string;
    details: string;
    timestamp: string; // ISO 8601
    userId: number;
    companyId: number;
    metadata: Record<string, any>;
    createdAt: string; // ISO 8601
    updatedAt: string; // ISO 8601
    user?: User;      // Relación opcional
    company?: Company;// Relación opcional
}

Ejemplo de Respuesta Completa

{
    "id": 789,
    "action": "user_login",
    "details": "Inicio de sesión exitoso",
    "timestamp": "2023-05-20T14:30:45.000Z",
    "userId": 123,
    "companyId": 456,
    "metadata": {
        "ip": "192.168.1.1",
        "device": "Mobile/Android",
        "location": "New York, US"
    },
    "createdAt": "2023-05-20T14:30:45.000Z",
    "updatedAt": "2023-05-20T14:30:45.000Z",
    "user": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "company": {
        "id": 456,
        "name": "Acme Corp"
    }
}