# API - project.linkedcorp.net

## Base URL

- Desarrollo: `http://localhost:4019/api`
- Producción: `https://project.linkedcorp.net/api`

## Autenticacion

- Tipo: Bearer JWT (`Authorization: Bearer <token>`), emitido por `/api/auth/login`.
- El backend revalida `is_active` del usuario en cada request (no solo la firma del JWT).

## Formato de respuesta

```json
{
  "success": true,
  "data": {},
  "error": null
}
```

## Endpoints principales

### Auth
- `POST /api/auth/login` — `{ email, password }` → `{ token, user }`. Si el usuario no esta
  `active` (`pending_verification`/`pending_approval`) o `is_active=0`, `403` con mensaje especifico.
- `POST /api/auth/register` — público. `{ name, email, password }` → si es el primer usuario del
  sistema: `{ bootstrap: true, token, user }` (superadmin, sesion directa); si no:
  `{ bootstrap: false }` y se envia (o loguea, sin SMTP) un correo de verificación.
- `GET /api/auth/verify-email?token=...` — público. Pasa el usuario a `pending_approval` y notifica
  in-app a los `admin`/`superadmin` activos.
- `POST /api/auth/forgot-password` — público. `{ email }` → respuesta **siempre genérica**.
- `POST /api/auth/reset-password` — público. `{ token, password }`.
- `PUT /api/auth/change-password` — autenticado. `{ currentPassword, newPassword }`, exige la
  clave actual (distinto de `reset-password`, que usa un token de correo sin sesión).
- `POST /api/auth/logout`
- `GET /api/auth/me` — usuario actual

### Usuarios (`/api/users`) — lectura para cualquier autenticado; escritura solo Administrador/Superadministrador
- `GET /api/users` · `POST /api/users` · `PUT /api/users/:id` · `PATCH /api/users/:id/active`
- `POST /api/users/:id/approve` — `{ roleId?, departmentId? }`, solo sobre usuarios `pending_approval`
- `POST /api/users/:id/reject` — borra al usuario `pending_approval` (se audita el email antes)

### Departamentos (`/api/departments`)
- `GET /api/departments` (árbol) · `POST /api/departments` · `PUT /api/departments/:id` · `DELETE /api/departments/:id`

### Proyectos (`/api/projects`)
- `GET /api/projects` (filtros: estado, responsable, prioridad) · `POST /api/projects`
- `GET /api/projects/:id` · `PUT /api/projects/:id`
- `POST /api/projects/:id/members` · `DELETE /api/projects/:id/members/:userId`

### Actividades (`/api/activities`)
- `GET /api/projects/:projectId/activities` · `POST /api/projects/:projectId/activities`
- `GET /api/activities/:id` · `PUT /api/activities/:id`
- `POST /api/activities/:id/dependencies` · `DELETE /api/activities/:id/dependencies/:dependsOnId`

### Subtareas (`/api/activities/:activityId/subtasks`)
- `GET` · `POST` · `PUT /api/subtasks/:id` · `PATCH /api/subtasks/:id/done` · `DELETE /api/subtasks/:id`

### Comentarios (`/api/comments`)
- `GET /api/comments?entityType=project&entityId=1` · `POST /api/comments`

### Adjuntos (`/api/attachments`)
- `GET /api/attachments?entityType=activity&entityId=1` · `POST /api/attachments` (multipart)
- `GET /api/attachments/:id/download` · `DELETE /api/attachments/:id`

### Notificaciones (`/api/notifications`)
- `GET /api/notifications` · `PATCH /api/notifications/:id/read` · `PATCH /api/notifications/read-all`

### Dashboard (`/api/dashboard`)
- `GET /api/dashboard/summary` — KPIs (activos, atrasados, pendientes/vencidas/hoy, avance promedio)
- `GET /api/dashboard/calendar?month=2026-09` — actividades por fecha límite
- `GET /api/projects/:id/gantt` — actividades con fechas/avance para el Gantt

### Catálogos (`/api/catalogs`) — lectura general, escritura solo Administrador
- `GET/POST/PUT/DELETE /api/catalogs/project-statuses`
- `GET/POST/PUT/DELETE /api/catalogs/activity-statuses`
- `GET/POST/PUT/DELETE /api/catalogs/priorities`
- `GET/POST/PUT/DELETE /api/catalogs/project-types`

### Auditoría (`/api/audit`) — solo Superadministrador / Administrador / Jefe de TI
- `GET /api/audit?entityType=project&entityId=1`

### Configuración SMTP (`/api/settings`) — solo Superadministrador
- `GET /api/settings/smtp` — `{ host, port, user, from, configured }` (nunca la clave)
- `PUT /api/settings/smtp` — `{ host, port, user, from, pass? }` (`pass` vacío = no cambiarla)
- `POST /api/settings/smtp/test` — `{ host, port, user, from, pass?, to }` (`pass` vacío = usa la
  guardada). Envía un correo real con los valores del formulario (aunque no se hayan guardado) y
  responde `{ sent: true }` o `400` con el error real del servidor SMTP. Rate-limited (10/15min).

## Errores esperados

- `400` validación
- `401` no autenticado / token inválido o expirado
- `403` sin permisos para la acción (según rol)
- `404` no encontrado (incluye cuando el recurso existe pero no pertenece al usuario/alcance)
- `500` error interno (sanitizado, sin detalle de stack en producción)