Referencia — Instancia y plano de control¶
Lo que opera la instalación entera, no un aula: la lista de organizaciones, la credencial de provisioning, los accesos de soporte, la puerta de suscripción, la licencia y los ajustes de instancia. Es la superficie que usa un plano de control externo —Didacta Cloud, o un script tuyo si autoalojas— y un super_admin desde el panel. Todas las rutas cuelgan de /api/v1.
Leyenda de Auth: super_admin = sesión de super_admin · super_admin o provisioning = además acepta la credencial de provisioning (Authorization: Provisioning didprov_…). Las marcadas Cloud solo existen cuando el operador enciende la función (el modo plataforma de cobros o la subida de vídeo); sin ella, la ruta responde 404.
La lista blanca de la credencial
La credencial de provisioning solo abre las rutas marcadas «provisioning» de esta página (más GET /admin/system/health-detail). Cualquier otra ruta responde 403 AUTH_PROVISIONING_ROUTE_NOT_ALLOWED, aunque la credencial sea válida. Renombrar una organización, ver la capacidad de la licencia o tocar la licencia exigen un super_admin con sesión.
Organizaciones — /admin/tenants¶
| Método | Ruta | Auth | Qué hace |
|---|---|---|---|
| GET | /admin/tenants |
super_admin o provisioning | Lista todas las organizaciones (con nº de usuarios, cursos y dominios). |
| GET | /admin/tenants/capacity |
super_admin | Nº de organizaciones y si la licencia permite crear más: sin feat:multi_tenant.real el límite es 1. |
| GET | /admin/tenants/usage?asOf= |
super_admin o provisioning | Miembros activos por organización a una fecha de corte (asOf, ISO-8601, por defecto ahora; una fecha futura da 400). Es la definición contractual del consumo —la misma de la página de precios de Didacta Cloud—. Cuenta: usuarios con acceso, activos y no borrados (formadores, auditores y gestores de empresa sí cuentan). No cuenta: tenant_admin/super_admin, invitaciones sin aceptar (PENDING), suspendidos, bajas y borrados. Devuelve [{ tenantId, slug, activeMembers, asOf }]. |
| GET | /admin/tenants/:id |
super_admin o provisioning | Detalle de una organización. |
| POST | /admin/tenants |
super_admin o provisioning | Crea organización + primer tenant_admin + dominio primario y envía el correo de bienvenida (el enlace apunta al dominio de esa aula). 402 al superar el límite Community sin feat:multi_tenant.real. Ver cuerpo abajo. |
| PATCH | /admin/tenants/:id/status |
super_admin o provisioning | { status: ACTIVE \| SUSPENDED \| ARCHIVED }. SUSPENDED y ARCHIVED invalidan las sesiones de todos sus usuarios. |
| PATCH | /admin/tenants/:id |
super_admin | Renombra ({ name }); afecta a la firma de los correos («Equipo {name}»). No invalida sesiones. |
| PATCH | /admin/tenants/:id/signups |
super_admin o provisioning | Congela o descongela las altas nuevas: { frozen, reason } (reason de 5 a 280 caracteres; se le enseña al visitante que se queda fuera). Con las altas congeladas, la invitación individual, el alta masiva, el registro público y el checkout de alumno nuevo dan 409 TENANT_SIGNUPS_FROZEN. Es un interruptor explícito: el núcleo no cuenta miembros ni lo enciende solo. |
| PUT | /admin/tenants/:id/subscription-gate |
super_admin o provisioning | Abre, pone en prueba o cierra la puerta de suscripción. |
| POST | /admin/tenants/:id/domains |
super_admin o provisioning | Añade un dominio ({ hostname }). |
| DELETE | /admin/tenants/:id/domains/:hostname |
super_admin o provisioning | Quita un dominio; el primario no se puede quitar. |
Cuerpo de POST /admin/tenants: slug (≤64), name (≤120), adminEmail, adminName?, primaryHostname, y opcionales retrocompatibles simpleMode (sin él, nace encendido si crea el plano de control y apagado si crea un super_admin), locale (es, en, pt o un tag como pt-BR, que se guarda reducido; un idioma sin catálogo da 400; también fija el idioma de la primera administradora) y payoutsCountry (país del banco declarado en el alta, ISO alfa-2 u OTHER; solo se usa para preseleccionar en la tarjeta de cobros).
curl -X POST https://tu-instancia/api/v1/admin/tenants \
-H "Authorization: Provisioning didprov_..." \
-H "Content-Type: application/json" \
-d '{
"slug": "demo",
"name": "Academia Demo",
"adminEmail": "admin@example.com",
"primaryHostname": "demo.example.com",
"locale": "es"
}'
Puerta de suscripción¶
Una dimensión aparte del estado de la organización. ACTIVE dice que el aula existe y se sirve; la puerta dice si, además, su contenido está abierto, en prueba o en pausa. Un aula con la prueba terminada sigue ACTIVE a propósito: su administrador tiene que poder entrar, ver que está en pausa y pagar. El núcleo no es una política: no cuenta días ni mira planes; quien mueve la puerta es el plano de control o un super_admin. Una instalación autoalojada que nunca recibe esta llamada se queda en OPEN.
PUT /admin/tenants/:id/subscription-gate con { state, trialEndsAt?, actionUrl? }:
state |
Qué pasa | Campos |
|---|---|---|
OPEN |
Todo como siempre. Borra trialEndsAt y actionUrl. |
— |
TRIAL |
El aula funciona y sus administradores ven una franja con los días que quedan y el botón «Elegir plan» → actionUrl. |
trialEndsAt (ISO-8601 con zona) y actionUrl (https) obligatorios. |
LOCKED |
Pantalla de pausa para todos y 402 SUBSCRIPTION_LOCKED en la API, salvo acceso, /me/profile, /me/modules, marca, sondas, webhooks entrantes y rutas de organizaciones. |
actionUrl (https) obligatorio. |
Un TRIAL con trialEndsAt ya pasado se comporta como LOCKED aunque la llamada no se repita. La llamada es idempotente: repetirla no cambia updatedAt ni deja otra fila en el audit log. GET /auth/tenant-context enseña al visitante solo si el aula está en pausa (subscriptionGate.state: LOCKED); la franja de prueba la ven solo los administradores, en /me/modules.
Acceso de soporte¶
Una ventana temporal para que el equipo de soporte entre en el aula de un cliente sin hacerse pasar por nadie.
| Método | Ruta | Auth | Qué hace |
|---|---|---|---|
| POST | /admin/tenants/:id/support-access |
super_admin o provisioning | Abre la ventana. Cuerpo { reason, ttlSeconds? }: reason obligatorio (10–280 caracteres) —es lo que el cliente lee en su audit log—; ttlSeconds puede pedir menos de 15 minutos, nunca más (mínimo 60 s). Devuelve un token de un solo uso y el enlace para canjearlo. |
| DELETE | /admin/tenants/:id/support-access/:grantId |
super_admin o provisioning | Corta la ventana antes de que caduque y cierra su sesión. Idempotente: la segunda vez devuelve revoked: false. |
- El canje (
POST /auth/support-access/redeem, ver Núcleo) abre sesión como un usuario de soporte propio del aula, visible en su lista de miembros; nunca como una persona real. La sesión no tiene refresh token y caduca con la concesión. - Quedan dos filas en el audit log del aula: la concesión (con el motivo y quién la abrió) y el canje. El cliente las lee sin pedir permiso.
- Mientras la sesión vive, el aula muestra un aviso permanente que no se puede cerrar. Una sesión de soporte no puede exportar datos personales (
/admin/sales/exportda 403SALES_SUPPORT_SESSION_FORBIDDEN).
Credencial de provisioning — /admin/provisioning-credential (super_admin)¶
| Método | Ruta | Qué hace |
|---|---|---|
| POST | /admin/provisioning-credential |
Emite la credencial de la instancia. Devuelve { id, token, preview, createdAt }; el token didprov_… solo se ve esta vez. Emitir otra revoca la anterior (hay como mucho una viva). |
| DELETE | /admin/provisioning-credential |
Revoca la credencial viva (idempotente): { revoked, id }. |
Cómo se usa y qué cubre: Autenticación.
Cobros de plataforma — rutas del pool (Cloud)¶
Solo existen con el modo plataforma encendido (PAYMENTS_PLATFORM_STRIPE_SECRET_KEY en el entorno de la API); en cualquier otra instalación responden 404. Las usa el plano de control para saber cuánto se cobra y fijar la comisión. Lo que ve cada creador está en Pagos, aula e IA.
| Método | Ruta | Auth | Qué hace |
|---|---|---|---|
| GET | /admin/tenants/payouts/volume?from=&to= |
super_admin o provisioning | Volumen cobrado por la plataforma, por aula, día (UTC del cobro) y divisa de liquidación, entre from y to (ambos incluidos, YYYY-MM-DD, máx. 366 días). Una venta cuenta cuando su reparto se conoce: conviene volver a pedir los últimos días. Nunca suma divisas distintas. |
| GET | /admin/tenants/payouts/countries |
super_admin o provisioning | Países (ISO alfa-2) donde la plataforma puede pagar a creadores: PAYMENTS_PLATFORM_SUPPORTED_COUNTRIES o la lista por defecto. Una sola fuente para Cloud y para el alta del creador. |
| PUT | /admin/tenants/:id/payouts-settings |
super_admin o provisioning | Fija la comisión del operador de un aula: { feeBps } en puntos básicos, de 0 a 3000 (500 = 5 %). Idempotente; queda en el audit log. |
| GET | /admin/tenants/:id/payouts |
super_admin o provisioning | Modo de cobro del aula, estado de la cuenta conectada, comisión y deuda abierta. |
Vídeo — rutas del pool (Cloud)¶
Solo existen con la subida de vídeo configurada (BUNNY_STREAM_API_KEY). El lado del creador está en Aprendizaje → Vídeo.
| Método | Ruta | Auth | Qué hace |
|---|---|---|---|
| GET | /admin/tenants/:id/video |
super_admin o provisioning | Cuota de horas, última actividad, avisos de inactividad enviados, purga y copias de seguridad (nº y bytes) del vídeo subido de un aula. |
| POST | /admin/tenants/:id/video-backups/purge |
super_admin o provisioning | Supresión (RGPD): borra ya, de forma definitiva, todas las copias en Google Drive de los vídeos del aula. Idempotente. Devuelve { deleted, failed }. |
Licencia — /admin/license (super_admin)¶
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /admin/license |
Estado actual de la licencia de la instalación. |
| PUT | /admin/license |
Activa una licencia: { key }. Valida la firma antes de guardar y rechaza si no es válida. |
| DELETE | /admin/license |
Quita la licencia guardada en el panel (vuelve a Community, o a la del entorno si hay). |
| POST | /admin/license/refresh |
Re-evalúa el estado (expiración, gracia) sin cambiar la clave. |
El estado público —sin secretos— está en GET /api/license. Qué desbloquea cada capability: Enterprise → Capabilities.
Ajustes de instancia — /admin/instance-settings (super_admin)¶
Parejas scope/key globales de la instalación (no de un aula). Los secretos se cifran en reposo y nunca devuelven su valor, solo hasValue.
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /admin/instance-settings · /:scope |
Lista todos los ajustes de instancia (metadatos, sin valores secretos) · los de un scope. |
| GET | /admin/instance-settings/:scope/:key |
Lee un ajuste. |
| PUT | /admin/instance-settings/:scope/:key |
Crea o actualiza ({ value, isSecret }). |
| DELETE | /admin/instance-settings/:scope/:key |
Elimina el ajuste. |
Estado y registro de la instalación¶
| Método | Ruta | Auth | Qué hace |
|---|---|---|---|
| GET | /admin/system/health-detail |
super_admin, tenant_admin o provisioning | Estado consolidado de BD, Redis, S3, SMTP, las dos colas y la versión desplegada (diagnóstico on-call). |
| GET | /admin/registry/status |
super_admin | Estado del registro opt-in de la instalación con el equipo de Didacta: si está registrada, fecha de opt-in, último envío de telemetría y si hay conexión. |
| POST | /admin/registry/opt-in |
super_admin | Registra la instalación y activa el envío de telemetría agregada (sin datos personales). acceptTerms: true obligatorio. |
| DELETE | /admin/registry/opt-in |
super_admin | Opt-out (RGPD): marca el registro como cancelado y solicita el borrado remoto (best-effort si el servicio no responde). |
El registro es una decisión de instancia, no de aula. Ver Telemetría.
Módulos de marketplace¶
La instalación, desinstalación e inspección de paquetes ZIP firmados (/admin/modules/install, /admin/modules/installed…) son operaciones de super_admin sobre la instancia y están en Administración → Módulos. Una vez instalado, un módulo de terceros atiende todo lo que cuelga de /modules/<slug>/… a través de un despachador genérico (ALL /modules/*): la autenticación es opcional en el despachador y cada ruta del módulo decide si exige sesión. El bundle de interfaz de cada módulo se sirve sin autenticación en GET /modules/:slug/ui/:surface.js.