Invitaciones
¿Qué hace este módulo?
Permite a los administradores de una empresa invitar a nuevos miembros mediante un enlace/token enviado por email. El usuario invitado acepta la invitación y queda vinculado automáticamente a la empresa con el rol asignado.
Flujo completo
Admin Sistema Usuario invitado
│ │ │
├─ POST /companies/:id/ │ │
│ invitations │ │
│ { email, role } │ │
│ ├── Crea invitación │
│ ├── Genera token único │
│◄─ Devuelve token ────────────┤ │
│ │ │
├─ (envía enlace por email) ───────────────────────────────────────►│
│ │ │
│ │ GET /invitations/accept │
│ │◄────?token=<token> ───────────────┤
│ │ │
│ ├── Verifica token │
│ ├── Añade usuario a la empresa │
│ ├── Marca token como usado │
│ │ │
│ ├──────────── ✅ Acceso concedido ──►│El sistema genera el token, el email lo envía quien integra
El backend devuelve el token pero no envía el email directamente. Es responsabilidad de la aplicación cliente (o un worker) construir el enlace y enviárselo al usuario.
Reglas importantes
| Regla | Detalle |
|---|---|
| Expiración | Los tokens expiran a los 7 días (configurable con INVITATION_EXPIRY_DAYS) |
| Un solo uso | Una vez aceptado, el token ya no se puede volver a usar |
| El usuario debe existir | El email del invitado debe tener ya una cuenta creada en el sistema |
| Multi-empresa | Si multi_company = false, un usuario ya miembro de otra empresa no puede aceptar la invitación — 409 Conflict (mismo status que POST /companies / POST /companies/:id/users) |
Endpoints
| Método | Ruta | Quién puede usarlo | Descripción |
|---|---|---|---|
POST | /companies/:id/invitations | Owner, Admin | Crear invitación — devuelve el token |
GET | /invitations/accept?token= | Público | Aceptar invitación |
GET | /companies/:id/invitations | Owner, Admin | Listar invitaciones pendientes |
DELETE | /companies/:id/invitations/:invitationId | Owner, Admin | Revocar una invitación |
Jerarquía de roles al invitar
POST /companies/:id/invitations aplica la misma regla que POST /companies/:id/users (ver Empresas → Añadir un miembro):
ownerpuede invitar con cualquier rol (owner,admin,member,viewer).adminsolo puede invitar conmemberoviewer. Si unadminintenta invitar conowneroadmin, la petición devuelve 403 Forbidden.
Esto evita que un admin incorpore a alguien como owner/admin a través de una invitación, esquivando el mismo control que ya existe en el alta directa de miembros. Un super admin omite esta restricción, igual que en POST /companies/:id/users.
¿Qué pasa cuando alguien acepta?
- El sistema busca el token en la base de datos.
- Verifica que no haya expirado y que no haya sido aceptado ya.
- Busca al usuario cuyo email coincide con el de la invitación.
- Si la invitación otorga el rol
owneroadmin, se revalida el rol actual de quien la creó (no el del usuario que acepta, que no tiene sesión). Si quien la creó ya no tiene el rolowneren la empresa (por ejemplo, fue degradado después de crear la invitación) y no es super admin, la aceptación se rechaza con 403 Forbidden — ninguna membresía se crea. - Lo añade a la empresa con el rol indicado en la invitación.
- Marca la invitación como aceptada.
Tras la aceptación el usuario puede hacer login y acceder a la empresa.