Catálogo de permisos de la API

Los 61 permisos de la API externa, los 17 que solo concede un Super Administrador, su desglose por área y tipo, y cómo los marcan el plan y la web.

Actualizado el 22 de octubre de 2026. 7 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 61 permisos en quince áreas, y 17 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: 61
Solo los concede un Super Administrador: 17; Con un motivo de al menos veinte caracteres.
Áreas: 15
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, 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), 57 desde el 13 de octubre de 2026, con crm:invoices:rectify (emitir facturas rectificativas), 58 desde el 21 de octubre de 2026, con crm:users:read:fiscal-data (el NIF y la dirección de facturación de los usuarios). Ese mismo día billing:scheduled-charges:write pasó de escritura a crítico financiero, y los protegidos pasaron de 15 a 17. Desde el 22 de octubre de 2026 son 61, con analytics:errors:manage (gestionar los errores reportados) y los dos de la aplicación que publica una ficha en el catálogo de aplicaciones (apps:installations:read y apps:installations:exchange). 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 la lista de permisos de la ficha de cada aplicación y genera la lista de valores de la operación MCP que cambia permisos.

Cada permiso del catálogo lleva estos datos, los mismos con los que la ficha de la aplicación pinta la lista de permisos:

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.
publishableAllowedbooleanobligatorio: Si lo puede tener una aplicación cuya clave va en páginas web. Solo es true en los siete del navegador; con los demás, conceder o añadir dominios responde 400 SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINS.
conditionalRequirementsobjeto[]obligatorio: Lo que pide el plan para una ruta o una opción concreta del permiso, no para el permiso entero: appliesTo (la ruta o la opción), modules, capabilities y satisfied (si tu organización ya lo tiene). Vacío si no hay.

Por ejemplo, crm:clients:read lleva en conditionalRequirements la ruta GET /external/v1/clients/:id/group, que pide además la capacidad de grupos de empresas: el permiso sirve sin ella, pero esa ruta no.

Una clave publicada en páginas web solo admite siete: support:tickets:read, support:tickets:write, support:tickets:ai, fm:files:read, fm:files:write, crm:users:write y analytics:errors:write.

Los 61 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`, `crm:users:read:fiscal-data`	3
Facturación	`crm:invoices:read`, `crm:invoices:write`, `crm:invoices:send`, `crm:invoices:issue`, `crm:invoices:cancel`, `crm:invoices:rectify`	6
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`, `analytics:errors:manage`	4
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
Instalaciones del catálogo	`apps:installations:read`, `apps:installations:exchange`	2
Total		61

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 dos de las instalaciones del catálogo son de la aplicación que publica una ficha, sobre sus propias instalaciones: nunca se piden a una empresa que la instala. Ver Referencia de las instalaciones.

Los cinco tipos

Tipo	Cuántos	Qué significa
`basic`	20	Lecturas ordinarias.
`write`	20	Escrituras reversibles.
`sensitive`	5	Datos delicados o acciones de más alcance del que aparentan, sin llegar a críticos.
`rgpd-critical`	9	Datos personales críticos. Solo los concede un Super Administrador, con motivo.
`financial-critical`	7	Mueven dinero, cortan un ingreso o restan ingresos con un documento fiscal. 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 17 permisos que solo concede un Super Administrador

Son los 9 de datos personales críticos, los 7 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:users:read:fiscal-data`	NIF y dirección de facturación de los usuarios de la aplicación; en autónomos identifica a una persona.
`crm:invoices:cancel`	Anula facturas emitidas y dispara la anulación fiscal.
`crm:invoices:rectify`	Emite facturas rectificativas con importes negativos: restan ingresos y una vez emitidas no se pueden retirar.
`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.
`billing:scheduled-charges:write`	Programa cobros y adelanta reintentos, que cobran en el momento con la tarjeta del usuario.

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:charge no 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

En esta página