Planes y Cuotas

Qué es esto

Cada proyecto de ComStack tiene un conjunto de capacidades: qué funciones están activas, cuántas páginas puede contener, cuántos idiomas admite o si puede realizar llamadas telefónicas. Esta página describe el sistema que controla todo esto: módulos, planes, niveles y plantillas.

Cómo funciona

El sistema de derechos tiene cuatro capas:

Término	Qué significa
Módulo	Una capacidad funcional: `voice_web`, `voice_phone`, `whatsapp`, `knowledge_base`, `custom_pages`, `website`, `github_sync`, `chrome_ingest`, `api_keys`. Cada uno puede activarse o desactivarse de forma independiente.
Plan	El documento de derechos materializado (`settings/plan`) que define lo que un proyecto puede hacer en este momento. Contiene límites por módulo y restricciones generales del proyecto.
Nivel	El nivel comercial: `trial` o `standard`. Determina qué límites del plan se aplican.
Plantilla	Una plantilla de proyecto que define el esquema estructural: qué módulos están disponibles, qué límites se aplican por nivel y la duración de la prueba.
Cuota	Un límite numérico dentro de un plan: `max_pages`, `max_locales`, `max_members`, `max_numbers`, `max_keys`, `max_sessions_per_day`.

Principio clave: El código de cumplimiento lee UN solo documento: settings/plan. Nunca necesita saber nada sobre plantillas, cupones o suscripciones. Esto hace que la capa de cumplimiento sea extremadamente sencilla y la capa comercial infinitamente flexible.

Cuándo utilizarlo

Consulta esta página cuando necesites entender por qué una operación de proyecto devuelve un error de cuota, qué límites se aplican a un nivel determinado o cómo se materializan los límites del plan a partir de las plantillas de proyecto.

Parámetros / campos / entradas

Módulos

La configuración de los módulos reside en el documento raíz del proyecto en modules.*.

Módulo	Propósito	Campos clave de configuración
`voice_web`	Agente de voz en vivo basado en navegador	`enabled`, `voice`, `greeting`, `instructions`
`voice_phone`	Llamadas telefónicas PSTN vía Twilio	`enabled`, `numbers[]`
`whatsapp`	Voz de WhatsApp Business vía Twilio	`enabled`, `numbers[]`
`knowledge_base`	Páginas de documentación optimizadas para agentes	`enabled`, `access`, `locales[]`
`custom_pages`	Páginas de contenido enriquecido para usuarios	`enabled`, `access`, `locales[]`
`website`	Sitio de documentación Starlight publicado	`enabled`
`github_sync`	Sincronizar contenido desde un repositorio GitHub	`enabled`
`chrome_ingest`	Ingerir páginas web vía extensión de Chrome	`enabled`
`api_keys`	Autenticación de clave API MCP/HTTP	`enabled`

access ahora es solo una semilla predeterminada. El control de acceso por página se trasladó al campo audience a nivel de documento (public · agents · members · internal). El valor access del módulo inicializa el audience de las nuevas páginas de ese tipo y, por lo demás, es inerte.

Esquema del plan

{
  "tier": "trial",
  "status": "active",
  "modules": {
    "website":        { "enabled": true,  "max_pages": 10 },
    "voice_web":      { "enabled": true,  "max_sessions_per_day": 5 },
    "voice_phone":    { "enabled": false },
    "whatsapp":       { "enabled": false },
    "knowledge_base": { "enabled": true,  "max_pages": 20, "max_locales": 2 },
    "custom_pages":   { "enabled": true,  "max_pages": 10, "max_locales": 2 },
    "github_sync":    { "enabled": false },
    "chrome_ingest":  { "enabled": true },
    "api_keys":       { "enabled": true,  "max_keys": 1 }
  },
  "max_members": 2,
  "expires_at": "2026-05-24T14:00:00Z",
  "source": "trial",
  "coupon_code": null
}

Campo	Tipo	Descripción
`tier`	`string`	`"trial"` o `"standard"`. Informativo: el cumplimiento utiliza los límites, no el nombre del nivel.
`status`	`string`	`"active"` o `"suspended"`. Un plan suspendido bloquea todas las operaciones del proyecto.
`modules`	`map`	Derechos por módulo. Cada clave coincide con el nombre de un módulo.
`max_members`	`number`	Máximo de miembros del proyecto en todos los roles.
`expires_at`	`Timestamp \| null`	Cuándo expira el plan. `null` = sin expiración (planes de pago).
`source`	`string`	Cómo se creó este plan: `"trial"`, `"coupon"`, `"migration"`, `"admin"` o `"stripe"`.
`coupon_code`	`string \| null`	El código de cupón canjeado para activar este plan. `null` para pruebas.

Niveles

Prueba (Trial)

No todas las plantillas permiten pruebas: verifica trial.allowed en la plantilla.
La duración es configurable por plantilla (predeterminado: 14 días), almacenada en expires_at.
Límites: restrictivos (menos páginas, menos idiomas, sin teléfono/WhatsApp, miembros limitados).
Cuando expires_at vence, todos los endpoints autenticados devuelven 403 Trial expired. Los datos del proyecto se conservan: actualizar el plan restaura el acceso.

Estándar

Activado mediante cupón, anulación de administrador o pago.
Sin expiración (expires_at: null).
Límites: generosos (más de 200 páginas, 20 idiomas, teléfono/WhatsApp habilitado, 50 miembros).

Cumplimiento

Todo el cumplimiento lee settings/plan. Los fallos de cumplimiento devuelven 403.

Verificación	Campo del plan
¿Módulo habilitado?	`modules.{type}.enabled`
Límite de páginas	`modules.knowledge_base.max_pages` o `modules.custom_pages.max_pages`
Límite de idiomas	`modules.knowledge_base.max_locales`
Límite de miembros	`max_members`
Límite de claves API	`modules.api_keys.max_keys`
Límite de números de teléfono	`modules.voice_phone.max_numbers`
Sesiones en vivo/día	`modules.voice_web.max_sessions_per_day`
¿Prueba expirada?	`expires_at`

La cuota de sesiones en vivo se aplica de forma atómica antes de que se cree un token de Gemini Live: una transacción de Firestore lee el contador por (proyecto, usuario, día UTC) y rechaza con 429 si se alcanza el límite, evitando ráfagas concurrentes que superen el límite.

Materialización de Plantilla → Plan

Cuando se crea un proyecto:

Se lee la plantilla del proyecto.
Se determina el nivel: trial si no hay cupón y trial.allowed es verdadero; standard si se proporciona un cupón.
Para cada módulo en la plantilla: si available: false, se omite; de lo contrario, se lee la configuración específica del nivel y se escribe en settings/plan.
Se establece max_members desde la raíz del nivel.
Se establece expires_at desde trial.duration_days (o null para estándar).

La actualización del plan modifica settings/plan directamente; no se requieren cambios en el código de cumplimiento.

Plantillas de proyecto

Actualmente hay dos plantillas disponibles:

Plantilla	Ideal para
`real-estate-eu`	Agencias inmobiliarias en UE/España: voz, multilingüe, listados de propiedades
`generic-business`	Cualquier negocio sin un sector dedicado: mucha documentación/FAQ, multilingüe, voz

La incorporación selecciona la plantilla según la industria extraída (industrias real-estate → real-estate-eu; todo lo demás → generic-business). La selección siempre se muestra al usuario y se puede anular.

Ciclo de vida del estado del proyecto

Independientemente del plan, cada proyecto tiene un campo status:

Estado	¿Sitio accesible?	¿Puede publicar?	¿Puede configurar?
`setup`	El hosting existe pero no hay nada desplegado	Sí (vista previa)	Sí
`live`	Público en `site_url`	Sí	Sí
`paused`	Muestra página de mantenimiento	No	Sí
`archived`	Sitio eliminado	No	No

Para pasar a live se requiere: al menos una página, un título de sitio configurado y una solicitud explícita para establecer status: "live".

Ejemplo

Comprobación de por qué falla la creación de una página con un error de cuota:

Llama a get-project-state: la respuesta incluye detalles del plan y estado del módulo.
Compara modules.knowledge_base.max_pages con el recuento actual de páginas activas.
Si se alcanza el límite, necesitas una actualización del plan (contacta a soporte) o eliminar primero las páginas archivadas.

Un 403 con "error": "Quota exceeded: knowledge_base.max_pages (20)" significa que el proyecto está en su límite del plan. Un 403 con "error": "Trial expired" significa que expires_at ha pasado.

Errores comunes

Error	Causa	Solución
`403 Quota exceeded: knowledge_base.max_pages`	Se alcanzó el límite de páginas del plan actual	Actualiza el plan o elimina páginas archivadas
`403 Trial expired`	`expires_at` ha pasado	Contacta a soporte para actualizar
`403 Module not enabled`	El módulo está desactivado en `settings/plan`	Habilita el módulo vía API de configuración de módulos
`429` en creación de sesión en vivo	Se alcanzó `max_sessions_per_day`	Espera al reinicio a medianoche UTC o actualiza para un límite mayor

Relacionado

Resumen del servidor MCP: las herramientas MCP que muestran el estado del plan y del módulo
Permisos: matriz de roles y capacidades