Catálogo de permisos de la API
Los 56 permisos de la API externa, los 14 que solo concede un Super Administrador, su desglose por área y tipo, y cómo los marca el plan.
Actualizado el . 5 min de lectura
Incluido en todos los planes. Ver precios
Esta página fija y desglosa el catálogo de permisos de la API externa
(scopes): la lista de permisos que una aplicación puede tener
concedidos cuando llama a la API con su X-Api-Key. El catálogo tiene
56 permisos en catorce áreas, y 14 solo puede concederlos un Super
Administrador, con un motivo de al menos veinte caracteres. Cómo se
conceden está en Permisos de la API.
El catálogo en cifras
- Permisos en total
- 56
- Solo los concede un Super Administrador
- 14
- Con un motivo de al menos veinte caracteres.
- Áreas
- 14
- Tipos
- 5
- basic, write, sensitive, rgpd-critical y financial-critical.
La cifra ha ido creciendo: 15 al principio, 35 tras el 25 de mayo de 2026, 36 con los grupos de empresas, 45 con el chat y 56 desde el 5 de septiembre de 2026, con la facturación de aplicaciones externas (enviar facturas, dar de alta usuarios, devolver dinero, suscripciones, autorizaciones de cobro y cobros programados). Cualquier otra cifra que encuentres para el catálogo completo está desactualizada.
De dónde sale la cifra
El recuento no se escribe a mano: sale de la lista maestra del servidor.
Esa misma lista valida los cambios de permisos (un valor que no esté en
ella responde 400 INVALID_SCOPE), alimenta el endpoint del catálogo y
genera la lista de valores de la operación MCP que cambia permisos.
/api/integrations/apps/scopes/catalogCatálogo de permisos que una aplicación externa puede tener, con etiqueta, descripción, tipo, marcas de protección y los aplicativos y capacidades del plan que exige cada uno. Permiso: EXTERNAL_APPS_VIEW.
Cada entrada tiene esta forma:
- valuestringobligatorio
- Nombre técnico del permiso, el que se guarda en la aplicación. Por ejemplo, crm:contacts:read.
- labelstringobligatorio
- Etiqueta corta para el panel.
- descriptionstringobligatorio
- Qué da el permiso y cuándo conviene concederlo.
- categoryenumobligatorio
- basic, write, sensitive, rgpd-critical o financial-critical. Decide cómo se muestra y qué aviso acompaña a la concesión.
- rgpdSensitivebooleanobligatorio
- Si el permiso expone datos personales en sentido amplio.
- rgpdCriticalbooleanobligatorio
- Si se considera crítico en materia de datos personales.
- requiresSuperAdminbooleanobligatorio
- Si concederlo exige ser Super Administrador y dar un motivo. Retirarlo nunca lo exige.
- requiredModulesstring[]obligatorio
- Aplicativos del plan que necesita para funcionar.
- requiredCapabilitiesstring[]obligatorio
- Capacidades del plan que además hacen falta.
- outOfPlanboolean
- Indica que el plan de tu organización no lo cubre: se muestra con candado y no se puede conceder.
Para comprobar la cifra desde código, cuenta los elementos de la respuesta:
curl -s -H "Authorization: Bearer $ADMIN_JWT" \
"https://os.utilia.ai/api/integrations/apps/scopes/catalog" \
| jq 'length'
# 56curl -s -H "Authorization: Bearer $ADMIN_JWT" \
"https://os.utilia.ai/api/integrations/apps/scopes/catalog" \
| jq '[.[] | select(.requiresSuperAdmin == true)] | length'
# 14Los 56 permisos por área
| Área | Permisos | Total |
|---|---|---|
| Contactos | crm:contacts:read, crm:contacts:write, crm:contacts:read:secondary-email, crm:contacts:read:birthday, crm:contacts:read:notes, crm:contacts:read:opted-out | 6 |
| Leads | crm:leads:read, crm:leads:read:scoring, crm:leads:write, crm:leads:convert, crm:leads:read:notes | 5 |
| Clientes | crm:clients:read, crm:clients:write, crm:clients:write:hierarchy, crm:clients:read:fiscal-data, crm:clients:read:notes | 5 |
| Usuarios externos | crm:users:read, crm:users:write | 2 |
| Facturación | crm:invoices:read, crm:invoices:write, crm:invoices:send, crm:invoices:issue, crm:invoices:cancel | 5 |
| Cobros con tarjeta | billing:payment-methods:read, billing:payment-methods:write, billing:charge, billing:refund | 4 |
| Suscripciones | billing:subscriptions:read, billing:subscriptions:write, billing:subscriptions:cancel | 3 |
| Autorizaciones de cobro | billing:payment-authorizations:read, billing:payment-authorizations:write, billing:payment-authorizations:revoke | 3 |
| Cobros programados | billing:scheduled-charges:read, billing:scheduled-charges:write | 2 |
| Soporte | support:tickets:read, support:tickets:write, support:tickets:ai | 3 |
| Archivos | fm:files:read, fm:files:write | 2 |
| Presupuestos | crm:budgets:comments:read, crm:budgets:comments:write, crm:budgets:signatures:read, crm:budgets:signatures:verify | 4 |
| Analítica y errores | analytics:ai:read, analytics:errors:read, analytics:errors:write | 3 |
| Chat | chat:messages:send, chat:messages:view, chat:channels:view, chat:channels:create, chat:channels:manage, chat:members:manage, chat:events:subscribe, chat:agents:view, chat:agents:manage:external | 9 |
| Total | 56 |
crm:clients:read sirve tanto para el bloque de cliente que viaja en los contactos como para el listado de clientes, pero cuenta una sola vez: el catálogo no tiene repetidos.
Los cinco tipos
| Tipo | Cuántos | Qué significa |
|---|---|---|
basic | 19 | Lecturas ordinarias. |
write | 19 | Escrituras reversibles. |
sensitive | 5 | Datos delicados o acciones de más alcance del que aparentan, sin llegar a críticos. |
rgpd-critical | 8 | Datos personales críticos. Solo los concede un Super Administrador, con motivo. |
financial-critical | 5 | Mueven dinero o cortan un ingreso. Mismas exigencias que el anterior. |
El tipo de crítico financiero existe para que quien revisa una solicitud sepa por qué está protegido: no es lo mismo «esta aplicación leerá notas sobre personas» que «esta aplicación podrá cobrar y devolver dinero a tus clientes».
Los 14 permisos que solo concede un Super Administrador
Son los 8 de datos personales críticos, los 5 críticos financieros y chat:agents:manage:external, que es de tipo escritura. Retirarlos no exige nada especial; añadirlos exige un motivo, que queda en el registro de auditoría.
| Permiso | Por qué está blindado |
|---|---|
crm:contacts:read:notes | Notas internas del equipo sobre el contacto. |
crm:contacts:read:opted-out | Contactos que ejercieron su derecho de oposición. |
crm:leads:read:notes | Notas internas del equipo sobre el lead. |
crm:leads:convert | Conversión que no se puede deshacer: crea un contacto y, si se pide, una oportunidad. |
crm:clients:read:fiscal-data | NIF y dirección fiscal; en autónomos identifica a una persona. |
crm:clients:read:notes | Notas internas del equipo sobre el cliente. |
crm:invoices:cancel | Anula facturas emitidas y dispara la anulación fiscal. |
support:tickets:ai | Envía texto, audio e imágenes del usuario final a proveedores de IA externos. |
crm:budgets:signatures:verify | Comprueba la integridad de las firmas: en malas manos, ayudaría a probar manipulaciones. |
chat:agents:manage:external | Crea agentes de IA de canal que actúan con los permisos prestados de una persona. No entra en ningún paquete. |
billing:charge | Mueve dinero real desde la tarjeta guardada del cliente. |
billing:refund | Devuelve dinero ya cobrado. |
billing:subscriptions:cancel | Corta un ingreso recurrente y no se deshace. |
billing:payment-authorizations:write | Crea la prueba legal que habilita cobros futuros sin el usuario delante. |
Cómo influye el plan
Cada permiso declara qué aplicativos y capacidades del plan necesita.
Con eso, el catálogo marca con outOfPlan: true los que tu plan no
cubre (el panel los muestra con candado) y conceder uno de ellos
responde 400 SCOPE_OUT_OF_PLAN. Dos matices:
- Un cambio de plan no borra permisos. Lo ya concedido se conserva y deja de funcionar hasta que el aplicativo vuelva al plan. Retirar un permiso siempre es posible.
billing:chargeno declara la capacidad de cobro automático, a propósito: también sirve para cobrar con el usuario delante, que funciona sin ella. La puerta del cobro automático está en el endpoint que la necesita.
Si el catálogo cambia en el servidor, esta página es la primera que se actualiza. La forma fiable de saber la cifra real es contar la respuesta del endpoint.
Siguiente paso
- Permisos de la APICatálogo por área, reglas de concesión, bloqueo optimista y auditoría.
- Panel de aplicaciones externasCrear y configurar una aplicación, sus claves, sus permisos y sus avisos.
- Versiones del SDKQué versión del SDK cubre cada parte del catálogo.
- Facturar y cobrar desde tu aplicaciónQué permiso hace falta en cada paso del cobro.