Planes de reventa del owner (Owner Plans)
Este módulo permite que un owner de empresa defina su propio catálogo de planes para revendérselo a sus propios clientes finales — por ejemplo, una agencia que usa Nimobase para gestionar empresas de clientes y quiere ofrecerles niveles "Básico"/"Pro" propios.
Es un concepto distinto y separado del catálogo global de planes de la plataforma (ver Billing y suscripciones): ese catálogo (/billing/plans) es lo que Nimobase le vende a sus tenants, y solo lo gestiona un super admin de la plataforma. Este módulo (/companies/:id/owner-plans) es lo que cada tenant le vende a sus propios clientes, y lo gestiona el propio owner/admin de esa empresa.
Ver la decisión de diseño completa en la documentación de arquitectura del proyecto; este módulo implementa solo el alcance parcial descrito allí (crear/editar el catálogo propio); no implementa que los clientes finales del owner se suscriban a esos planes ni cobro alguno (ver "Qué queda fuera" más abajo).
Cómo funciona
| Concepto | Qué es |
|---|---|
| Plan del owner | Un plan que un owner define para su propio negocio, con nombre, funcionalidades (features) y límites (limits) — misma estructura que los planes globales de la plataforma |
| Suscripción de cuenta | La suscripción del propio owner a la plataforma (AccountSubscriptionEntity), que determina si puede o no crear planes de reventa |
Requisito para crear planes: suscripción con reventa habilitada
No cualquier owner puede crear planes de reventa. Se requiere que la suscripción de cuenta del owner (a nivel de usuario, no de empresa concreta) esté activa y que el plan de plataforma al que está suscrito incluya la funcionalidad reseller_enabled — igual que cualquier otra funcionalidad controlada por features/limits en el catálogo de planes de la plataforma.
Si el owner no tiene ninguna suscripción de cuenta activa, o su plan no incluye esa funcionalidad, la creación de un nuevo plan devuelve 403 Forbidden. Este requisito solo aplica a la creación de un plan nuevo — actualizar un plan ya creado (por ejemplo, para desactivarlo) no vuelve a comprobar la suscripción.
Endpoints
Todos requieren Authorization: Bearer <token> y rol OWNER o ADMIN de la empresa indicada en la URL.
Listar el catálogo propio
GET /companies/:id/owner-plans
Authorization: Bearer <token>Devuelve únicamente los planes creados por esa empresa.
Pack de partida Base/Pro/Max automático: si la suscripción de cuenta del owner tiene reseller_enabled y su catálogo de reventa está todavía vacío, esta misma llamada instancia automáticamente 3 planes de partida — Base, Pro y Max — con las mismas características de sistema que un cliente final ve (max_users, max_companies, api_access, priority_support, custom_domain), sin reseller_enabled en ninguno de los tres (la reventa es de un solo nivel: plataforma → reseller → cliente final, nunca reseller → reseller). No hace falta crear estos planes a mano ni pasar por ningún flujo especial: basta con que el owner abra la pantalla de "Planes de reventa" (o cualquier llamador consulte este endpoint) con el catálogo vacío. Si el catálogo ya tiene cualquier plan (aunque no se llame Base/Pro/Max), esta instanciación automática no se ejecuta — no añade ni pisa planes existentes. Los 3 planes instanciados son filas normales, totalmente editables después (renombrar, ajustar features/límites, desactivar) igual que cualquier plan creado a mano.
Crear un plan de reventa
POST /companies/:id/owner-plans
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Plan Básico Cliente",
"description": "Nivel de entrada para mis clientes",
"features": ["priority_support"],
"limits": { "max_users": 5 }
}Responde 403 si la suscripción de cuenta del creador no habilita reventa (ver arriba).
Validación de catálogo (H-2): features y limits deben usar solo claves del catálogo de sistema más las personalizadas de esta empresa no archivadas (ver sección siguiente). Una clave desconocida, del tipo incorrecto (flag vs limit), reseller_enabled u otra opción solo de plataforma, o un límite negativo / no numérico, se rechazan con 400. Los límites aceptan un número ≥ 0 o null (ilimitado). Esta regla evita burlar la bolsa del reseller inventando claves o límites negativos.
Actualizar un plan
PATCH /companies/:id/owner-plans/:planId
Authorization: Bearer <token>
Content-Type: application/json
{ "isActive": false }Si el body incluye features y/o limits, se aplica la misma validación de catálogo que en la creación. Una personalizada ya concedida en el plan puede permanecer aunque después se archive; no se puede añadir una clave archivada nueva.
Catálogo de personalizadas propio de la empresa
Igual que la plataforma (ver Billing y suscripciones), cada empresa reseller puede añadir sus propias características/límites personalizados, reutilizables entre sus planes de reventa, además de las opciones de sistema (max_users, max_companies, api_access, priority_support, custom_domain).
GET /companies/:id/catalog/custom-options[?includeArchived=true]
POST /companies/:id/catalog/custom-options
POST /companies/:id/catalog/custom-options/:optionId/archive
POST /companies/:id/catalog/custom-options/:optionId/unarchiveRequiere rol OWNER o ADMIN de la empresa :id. Archivar una personalizada (igual que en plataforma) es una marca "soft" — nunca borra la fila, así que los planes que ya la usaban conservan su valor; solo deja de ofrecerse al añadir opciones a un plan nuevo.
Asignar un plan a una empresa cliente
Un reseller puede vincular una de sus empresas cliente a uno de sus propios planes de reventa — solo el vínculo, sin cobro ni periodo de facturación (eso queda para una entrega posterior).
POST /companies/:id/owner-plans/:planId/assign
Authorization: Bearer <token>
Content-Type: application/json
{ "clientCompanyId": "..." }Requiere rol OWNER o ADMIN de la empresa reseller (:id).
Alcance: en la primera asignación, la empresa destino debe ser ya cliente del reseller: su creador (ownerId) tiene que ser miembro de la empresa reseller. Si no lo es (empresa ajena, huérfana/sistema o solo conocida por UUID), la llamada se rechaza con 403 y el mensaje This company is not a client of this reseller. Un UUID sin vínculo previo no basta para reclamar la empresa.
Si la empresa cliente ya tenía otro plan de este mismo reseller asignado, esta llamada lo cambia (mismo endpoint sirve para asignar y para cambiar) y no vuelve a comprobar la membresía del creador — el vínculo ya existe. Si la empresa cliente ya está vinculada a un reseller distinto, la llamada se rechaza con 403 — cada empresa cliente solo puede pertenecer al "alcance" de un reseller a la vez.
GET /companies/:id/owner-plan-assignmentsLista, para el reseller :id, todas sus empresas cliente con plan asignado (rol OWNER/ADMIN).
GET /companies/:id/owner-plan-assignmentDesde el lado de la empresa cliente :id: devuelve su plan asignado, o null si ninguno (sin plan asignado, no se aplica ningún límite/feature de reventa a esa empresa). Cualquier miembro autenticado de la empresa puede consultarlo.
Bolsa compartida del reseller
El reseller no puede repartir más capacidad de la que su propio plan de plataforma le da. Cada vez que se asigna o cambia un plan a una empresa cliente, el sistema suma los límites de sistema (max_users, max_companies) comprometidos en todos los planes ya asignados a sus empresas cliente — incluyendo el nuevo/cambiado — y lo compara contra los límites del propio plan de plataforma del reseller. Si la suma se pasaría del cupo, la asignación se rechaza con 409 e indica el cupo restante.
Ejemplo (de la spec): un reseller con plan de plataforma Max (150 usuarios) no puede tener cuatro empresas cliente en un plan de reventa Max de 45 usuarios cada una (180 > 150) — la cuarta asignación se rechaza.
Si el reseller todavía no tiene ningún plan de plataforma con esos límites (por ejemplo, en un entorno sin facturación configurada), esta comprobación simplemente no se aplica — no bloquea flujos que no dependen de facturación.
Enforcement en tiempo real sobre la empresa cliente
Una vez asignado, el plan de reventa gobierna en tiempo real las operaciones de esa empresa cliente concreta — no solo se comprueba en el momento de la asignación. OwnerPlansService expone dos métodos que consumen CompaniesService/ApiKeysService (backend-api/src/api/companies/, backend-api/src/api/api-keys/):
getEffectiveEntitlement(clientCompanyId, feature)— resuelve sifeatureestá concedida para esa empresa cliente ahora mismo:{ assigned: false }si no hay plan de reventa asignado (cae al plan de plataforma de siempre);{ assigned: true, has: false }si hay plan asignado pero no declarafeature(omitirla es un "no concedido" deliberado, igual que en plataforma);{ assigned: true, has: true, limit }si la concede (limitnumérico para claves de límite,nullpara flags booleanos comoapi_access).assertResellerPoolNotExceeded(clientCompanyId, feature)—: además del límite propio del plan asignado, un alta también debe respetar la bolsa actual del reseller (que puede haberse encogido tras la asignación si el reseller cambió/canceló su propio plan de plataforma).
CompaniesService.assertUnderPlanUserLimit() (altas de miembro) y ApiKeysService.assertApiAccessEnabled() (creación de API keys) consultan getEffectiveEntitlement() primero; solo si no hay plan de reventa asignado caen al chequeo de plan de plataforma preexistente.
Qué queda fuera de este módulo
Por diseño, este módulo no implementa:
- Que los clientes finales del owner se suscriban con cobro a estos planes — el vínculo plan↔empresa (arriba) existe, pero sin periodo de facturación ni pago.
- Ninguna integración de cobro para el flujo owner → cliente final (Stripe Connect u otro).
El enforcement en tiempo real de los límites/features del plan asignado sobre las operaciones de la empresa cliente sí está implementado — ver la sección de arriba.
Esa pieza de cobro queda como trabajo futuro.