Empresas
¿Qué hace este módulo?
Gestiona las empresas (tenants) del sistema y sus miembros. Cada empresa es un espacio de trabajo independiente: sus datos, usuarios y configuración están separados de los de otras empresas.
Conceptos clave
- Una empresa tiene nombre, slug único, estado activo/inactivo y, opcionalmente, identidad fiscal del emisor: razón social (
fiscalName), identificador fiscal (taxId), dirección fiscal (fiscalAddress) y país/jurisdicción (fiscalCountryCode, ISO 3166-1 alpha-2). Esos campos son la fuente de verdad para facturar y para cuando Nimobase factura al tenant (receptor = datos fiscales de la empresa). La respuesta incluyefiscalEmissionReadyymissingFiscalFields: sin ellos completos no se podrá emitir un documento fiscal (sí guardar la empresa o borradores). - Cada empresa tiene miembros — usuarios con un rol asignado dentro de esa empresa.
- Los roles determinan qué puede hacer cada miembro. → Ver Roles y permisos
Gestión de empresas
Crear una empresa
POST /companies
{
"name": "Acme Corporation",
"slug": "acme", ← solo letras minúsculas, números y guiones
"isActive": true,
"fiscalName": "Acme Corporation S.L.", ← opcional
"taxId": "B12345678",
"fiscalAddress": "Calle Mayor 1, 28013 Madrid",
"fiscalCountryCode": "ES"
}Requiere rol owner o admin. Los campos fiscales son opcionales al crear; si faltan, fiscalEmissionReady será false hasta completarlos con PATCH.
Quien crea la empresa queda automáticamente como su OWNER. Si multi_company=false (modo empresa única) y quien crea ya pertenece a otra empresa, la creación se rechaza con 409 Conflict — no se guarda ninguna empresa huérfana. Para permitir que un mismo usuario cree/pertenezca a varias empresas, activa multi_company=true primero.
Además, si el owner ya tiene contratado un plan de facturación con un límite max_companies (ver Facturación) y ya alcanzó ese límite, la creación también se rechaza con 409 Conflict — con un mensaje distinto que menciona el plan actual y sugiere hacer upgrade, para que se pueda distinguir de la regla de multi_company anterior. Este límite se resuelve a partir de la empresa (o empresas) que el owner ya posee con una suscripción activa; la primera empresa de un owner nunca se bloquea por esta regla, y si el owner no tiene ningún plan contratado tampoco se aplica.
Listar, ver y actualizar
GET /companies ← empresas activas visibles para el caller (ver abajo)
GET /companies/:id ← una empresa concreta (assertOwnership)
PATCH /companies/:id ← actualizar nombre, slug o estado
DELETE /companies/:id ← eliminar (devuelve 204)GET /companies/:id exige una membresía UserCompany activa en esa empresa (assertOwnership): 403 si el caller no tiene la membresía; 404 si la empresa no existe (tras pasar ownership). El flag Super Admin no permite leer empresas ajenas.
GET /companies está acotado por membresías activas y credenciales:
- Super Admin → solo empresas donde tiene membresía
UserCompanyactiva; sin membresía no recibe el directorio global ni puede gestionar vínculos app-client con esa empresa - JWT humano sin empresa seleccionada (hay
userId, no es API key) → solo las empresas donde tiene membresía activa; si no tiene ninguna, página vacía. Nunca recibe el directorio de plataforma. - Cuentas de servicio / tooling (sin tenant y sin
userIdhumano) → todas las empresas activas solo cuando su contrato de credencial de máquina lo autoriza; este acceso separado no se obtiene mediante el rol Super Admin de un usuario. - OWNER → empresas donde tiene membresía activa y rol OWNER, no solo la empresa seleccionada actualmente como tenant.
CompanyEntity.ownerIdpor sí solo no sustituye membresía. Esto habilita el caso de un owner con varias empresas (ver Usuarios → Registro como owner de una empresa nueva y el plan multi-empresa, todavía no implementado). Si por alguna razón el token no traeuserId(caso de cuentas de servicio con rol owner, poco común), se aplica el fallback de solo la empresa actual (o el path de service account si tampoco hay tenant). - Cualquier otro rol (ADMIN, MEMBER, VIEWER) → solo empresas con membresía activa en su alcance. No obtienen visibilidad sobre empresas a las que no pertenecen, ni siquiera si el propietario de esas empresas es la misma persona que las administra.
El rol Super Admin no concede el directorio de empresas. Los usuarios humanos solo ven empresas con membresía activa; los principals de tooling sin identidad humana siguen contratos de máquina explícitos y separados.
Paginación — GET /companies acepta ?page (default 1) y ?limit (default 20, máximo 100). La respuesta es un envelope, no un array plano:
{
"data": [/* empresas de esta página */],
"total": 12,
"page": 1,
"limit": 20
}Una página fuera de rango no es un error: devuelve data: [] con total reflejando el conteo real.
PATCH /companies/:id requiere owner o admin y acepta campos parciales; isActive también es opcional. Puede actualizar nombre, slug, estado e identidad fiscal (fiscalName, taxId, fiscalAddress, fiscalCountryCode). DELETE /companies/:id requiere solo owner — un admin puede editar la empresa pero no eliminarla. Ambos exigen además que el caller pertenezca a esa empresa (assertOwnership()); el rol global Super Admin no sustituye la membresía activa ni el rol de empresa.
Gestión de miembros
Ver quién pertenece a una empresa
GET /companies/:id/usersDevuelve la lista de miembros ya "aplanada" — id es el id del usuario (no el id de la fila de membresía), junto con su nombre, email y rol:
[
{
"id": "uuid-del-usuario",
"name": "Ana García",
"email": "ana@empresa.com",
"role": "member"
}
]Añadir un miembro
POST /companies/:id/users
{
"userId": "uuid-del-usuario",
"role": "member" ← owner | admin | member | viewer
}Responde con el mismo formato aplanado ({ id, name, email, role }, con id = id del usuario) para que la UI pueda pintar el nuevo miembro sin recargar la lista.
Jerarquía de roles al asignar un rol
Tanto owner como admin pueden llamar a este endpoint, pero no pueden otorgar los mismos roles:
ownerpuede asignar cualquier rol (owner,admin,member,viewer).adminsolo puede asignarmemberoviewer. Si unadminintenta asignarowneroadmin, la petición devuelve 403 Forbidden — aunque su propio rol sí supera el guard de ruta (OWNER, ADMIN), el rol que intenta otorgar no está permitido para él. Esto evita que unadminse auto-promueva (o promueva a otro) aowner/admin.
Un super admin (rol de plataforma, ver Usuarios → Super admin) omite esta restricción por completo, igual que hace con assertOwnership() — puede asignar cualquier rol aunque su token no tenga un rol de empresa asignado.
Si esa empresa tiene contratado un plan de facturación con un límite max_users (ver Facturación) y ya alcanzó ese límite, añadir un miembro adicional se rechaza con 409 Conflict, con un mensaje que menciona el plan actual y sugiere hacer upgrade. A diferencia de max_companies (que se resuelve a nivel owner, agregando todas sus empresas), max_users se resuelve directamente sobre esta empresa: el conteo es el número actual de miembros de la empresa contra el max_users de su propia suscripción activa. Una empresa sin ningún plan contratado no se ve afectada.
Si la empresa tiene un plan de reventa asignado por su reseller (ver Planes de reventa,), ese plan gobierna en su lugar: manda el max_users del plan de reventa (un plan que no declara max_users en absoluto bloquea el alta, no la deja ilimitada), y además se comprueba que la bolsa compartida del reseller siga teniendo cupo. Sin plan de reventa asignado, se aplica el chequeo de plan de plataforma descrito arriba sin cambios.
Modo empresa única
Si el sistema está configurado en modo empresa única (multi_company = false), un usuario solo puede pertenecer a una empresa. Intentar añadirlo a una segunda empresa devuelve 409 Conflict — el mismo código que usa la creación de empresas para esta misma regla de negocio — con un mensaje que indica activar multi_company=true para permitirlo.
Eliminar un miembro
DELETE /companies/:id/users/:userIdElimina al usuario de la empresa. El usuario sigue existiendo en el sistema, solo pierde el acceso a esta empresa.
Jerarquía de roles y último OWNER
La baja aplica la misma jerarquía que el alta (assertCanAssignRole). Un admin solo puede quitar miembros con rol member o viewer (quitar a un owner o admin → 403 Forbidden). Un owner con membresía activa puede quitar cualquier rol, salvo que sea el último owner de la empresa → 409 Conflict (Cannot remove the last OWNER from a company).
Flujo habitual para añadir miembros
Hay dos formas de incorporar a alguien a una empresa:
- Directamente — un admin añade al usuario si ya tiene cuenta (
POST /companies/:id/users). - Por invitación — se envía un token por email y el usuario lo acepta. → Ver Invitaciones