Planes Light y Pro

Qué rutas responde cada plan, cómo leer el plan de una organización y qué hacer con un 403 PLAN_LIMIT.

Aquí verás qué alcanza cada plan por la API, cómo leer el plan de una organización antes de llamar y qué significa PLAN_LIMIT.

La regla

La API le da a cada organización lo que su plan le da en el panel. Un token de API funciona en el Plan Light y en el Plan Pro. En Light, las rutas de reportes responden 403 PLAN_LIMIT, igual que esos reportes están bloqueados en el panel.

El plan es de la organización, no del token. Si tu token llega a una organización Pro y a una Light, cada una responde según su plan.

Qué responde cada plan

Las rutas van bajo /v1/external/organizations/{organizationId}, salvo las de cuenta. La columna «Clave» es el campo de features que decide el grupo.

Grupo	Rutas	Clave	Light	Pro
Cuenta	`/me`, `/me/usage`, `/organizations`	—	Sí	Sí
Organización	la organización, `/access`, `/plan`, `/settings`, `/categories`	—	Sí	Sí
Planta	`/floor`, `/modules`, `/modules/{moduleId}`, `…/rest-times`, `…/stations`, `/stations`, `/stations/{stationId}`, `/operators`, `/operators/presence`, `/operators/{operatorId}`	—	Sí	Sí
Tablero en vivo	`/board`	—	Sí	Sí
Programa y catálogo	`/modules/{moduleId}/program`, `/references…`, `/catalogue…`, con sus escrituras	—	Sí	Sí
Actividad	`/activity`	—	Sí	Sí
Reportes generales	`/analytics/day-report`, `/analytics/leaderboard`, `/analytics/efficiency`, `/analytics/efficiency/modules`, `/analytics/month`, `/stations/{stationId}/days/{day}/report`	`reports`	Solo versión 1	Sí
Reportes por módulo	`/modules/{moduleId}/days/{day}/board`, `…/days/{day}/history`, `/modules/{moduleId}/analytics/efficiency`, `/analytics/production`, y escribir las metas del día (`PUT` y `DELETE …/goal`)	`moduleReports`	No	Sí
Reportes por operario	`/analytics/operators/{operatorId}`, `/operators/{operatorId}/analytics/efficiency`	`operatorReports`	No	Sí
Facturación	`/analytics/billing`, `/analytics/billing/modules`	`billingAnalytics`	No	Sí
Analítica	`/analytics/activity`, `/analytics/hourly`, `/analytics/operators`, `/analytics/consistency`, `/stations/{stationId}/analytics/events`	`analytics`	No	Sí
Pausas	`/analytics/pauses`	`pauses`	No	Sí

En Light:

Versión del plan. Un Light de versión 1 conserva los reportes generales; uno de versión 2 no tiene ninguno. planVersion lo dice, y nunca cambia.
Programa. El Programa de un módulo admite hasta 3 referencias: features.maxReferencesPerModule. En Pro es null, sin límite.
Límite de uso. Un token hace 60 solicitudes por minuto en una organización Light y 120 en una Pro: mira Límites de uso.

Lee el plan antes de llamar

GET …/plan responde en todos los planes:

curl https://api.fluenta.io/v1/external/organizations/42/plan \
  -H 'Authorization: Bearer fluenta_live_xxxxxxxxxxxxxxxx'

{
  "tier": "light",
  "planVersion": 2,
  "features": {
    "reports": false,
    "billingAnalytics": false,
    "moduleReports": false,
    "operatorReports": false,
    "analytics": false,
    "pace": false,
    "rework": false,
    "pauses": false,
    "operatorPicksReference": false,
    "referenceColor": false,
    "aiConnector": false,
    "maxReferencesPerModule": 3,
    "publicApi": true
  },
  "rateLimits": {
    "windowSeconds": 60,
    "organization": 60,
    "heavy": 20,
    "credential": 300,
    "account": 60
  }
}

Si la clave de un grupo es true, sus rutas responden. Si es false, responden 403 PLAN_LIMIT.

PLAN_LIMIT

{
  "statusCode": 403,
  "code": "PLAN_LIMIT",
  "feature": "reports",
  "message": "Tu plan no incluye esta función"
}

feature nombra la clave que falta. No es un error del token ni de tus permisos: reintentar no lo cambia. Omite esa cifra o lee una ruta que sí esté en el plan: /board trae la eficiencia del día en todos los planes.

Prueba y exenta

Prueba. Una organización en su mes de prueba responde como el plan que está probando: tier es ese plan. Una prueba de Pro alcanza todas las rutas.
Exenta. Una organización exenta no se factura. Por la API responde como Pro.
Suscripción pausada. Una organización bloqueada responde 402 ORG_BLOCKED en todas sus rutas.

«Conectar con IA» es aparte

«Conectar con IA» es una función del Plan Pro: permite que una aplicación de IA, como Claude o ChatGPT, llegue a la organización con una conexión. No tiene que ver con los tokens de API. En una organización Light, una conexión responde 403 PLAN_LIMIT con feature: "aiConnector" en todas las rutas; un token de API sigue funcionando. Mira IA y Autenticación.