Skip to content

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 ​

ReglaDetalle
ExpiraciónLos tokens expiran a los 7 días (configurable con INVITATION_EXPIRY_DAYS)
Un solo usoUna vez aceptado, el token ya no se puede volver a usar
El usuario debe existirEl email del invitado debe tener ya una cuenta creada en el sistema
Multi-empresaSi 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étodoRutaQuién puede usarloDescripción
POST/companies/:id/invitationsOwner, AdminCrear invitación — devuelve el token
GET/invitations/accept?token=PúblicoAceptar invitación
GET/companies/:id/invitationsOwner, AdminListar invitaciones pendientes
DELETE/companies/:id/invitations/:invitationIdOwner, AdminRevocar 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):

  • owner puede invitar con cualquier rol (owner, admin, member, viewer).
  • admin solo puede invitar con member o viewer. Si un admin intenta invitar con owner o admin, 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? ​

  1. El sistema busca el token en la base de datos.
  2. Verifica que no haya expirado y que no haya sido aceptado ya.
  3. Busca al usuario cuyo email coincide con el de la invitación.
  4. Si la invitación otorga el rol owner o admin, 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 rol owner en 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.
  5. Lo añade a la empresa con el rol indicado en la invitación.
  6. Marca la invitación como aceptada.

Tras la aceptación el usuario puede hacer login y acceder a la empresa.