fase 3.5: licenciamiento por plan (clave firmada, planes basico/profesional/enterprise/custom, modulos incluidos y limites de usuarios/sucursales/citas/almacenamiento, modo aviso o bloqueo, panel de licencia) + API keys gestionables con alcances y revocacion (arregla la API publica que estaba rota) + webhooks salientes firmados con outbox, reintentos y bitacora; herramientas de vendedor y docs

docs/producto/api-terceros.md

@@ -0,0 +1,69 @@
+# API de terceros gestionable (claves de API)
+
+La API pública `/skeen/api/v1/*` (consumida por Hermes) se autentica con el
+método `auth='api_key'`, implementado en
+`skeen_plataforma/models/ir_http.py`. Acepta dos tipos de credencial:
+
+1. **Clave legacy de Hermes** — `ir.config_parameter 'skeen.api.legacy_key'`,
+   sembrada con el valor histórico `skeen_api_key_2026`. Tiene todos los
+   alcances (compatibilidad total).
+2. **Claves del modelo `skeen.api.key`** — con alcances (*scopes*), vencimiento
+   y revocación.
+
+## Formato de autenticación
+
+```
+Authorization: Bearer <clave>
+X-API-Key: <clave>
+?api_key=<clave>            (query/form)
+```
+
+## Modelo `skeen.api.key`
+
+| Campo | Descripción |
+| --- | --- |
+| `name` | Nombre de la clave |
+| `prefijo` | Prefijo visible (los primeros 14 caracteres) |
+| `hash` | SHA-256 de la clave (nunca se guarda en claro) |
+| `activo` | Habilitada |
+| `scopes` | Lista JSON de alcances; vacío = todos |
+| `vence` | Fecha de vencimiento (opcional) |
+| `ultimo_uso`, `usos` | Uso registrado en cada autenticación |
+| `notas`, `creado_por_login` | Metadatos |
+| `revocada_at`, `revocada_por` | Revocación |
+
+La clave **se muestra una sola vez** al crearla (solo se guarda el hash; la
+comparación es en tiempo constante).
+
+## Alcances por endpoint
+
+| Endpoint | Alcance |
+| --- | --- |
+| `POST /skeen/api/v1/available_slots` | `citas.read` |
+| `POST /skeen/api/v1/create_appointment` | `citas.write` |
+| `POST /skeen/api/v1/cancel_appointment` | `citas.write` |
+| `POST /skeen/api/v1/patient_balance` | `pacientes.read` |
+| `POST /skeen/api/v1/wallet_redeem` | `monedero.write` |
+| `GET/POST /skeen/api/v1/services` | `servicios.read` |
+
+Una clave sin el alcance recibe **HTTP 403** con mensaje claro. La clave legacy
+no tiene restricción de alcance.
+
+Las respuestas son **JSON plano** (no JSON-RPC): códigos 200 correctos,
+`401/403` para clave ausente/inválida o sin alcance.
+
+## Endpoints de gestión
+
+| Método | Ruta | Acceso |
+| --- | --- | --- |
+| GET | `/skeen/frontend/v1/api_keys` | permiso `api.claves` (admin) |
+| POST | `/skeen/frontend/v1/api_keys` | permiso `api.claves` (admin) |
+| PUT | `/skeen/frontend/v1/api_keys/<id>` | permiso `api.claves` (admin) |
+| POST | `/skeen/frontend/v1/api_keys/<id>/revocar` | permiso `api.claves` (admin) |
+
+## UI
+
+Configuración → pestaña **API** (admin): lista de claves (nombre, prefijo,
+alcances, último uso, usos, estado), botón "nueva clave" con modal que muestra
+la clave una vez y botón de copiar, editar y revocar; y documentación breve de
+los endpoints y del formato de autenticación.