# Permisos que puede pedir una aplicación

La lista cerrada de 26 permisos de la API que puede pedir una ficha del catálogo, lo que nunca se puede pedir y por qué, y qué necesita la persona responsable.

Una ficha del catálogo pide permisos de la API externa a cada empresa que la instala, y solo puede elegirlos de una **lista cerrada** de 26. Cada uno lleva su «para qué», una frase tuya de hasta 280 caracteres que la empresa lee antes de instalar, en el bloque **Qué podrá hacer**. Es lo primero que se revisa: pide solo lo que tu aplicación usa hoy.

La lista es de permisos admitidos, no de prohibidos: un permiso nuevo de la API no entra en el catálogo hasta que UTILIA lo decide a propósito.

## Los permisos que se pueden pedir

La columna «Persona responsable» dice qué permisos de UTILIA OS necesita la persona con la que actúa tu aplicación en la empresa. Lo que es solo de tu aplicación (sus usuarios, sus tickets y sus archivos) no le pide nada.

| Permiso | Aplicativo | Persona responsable |
| - | - | - |
| Leer contactos (`crm:contacts:read`) | CRM | Ver contactos |
| Dar de baja y reactivar el envío de correos a contactos (`crm:contacts:write`) | CRM | Ver contactos y Editar contactos |
| Correo secundario (`crm:contacts:read:secondary-email`) | CRM | Ver contactos |
| Leer clientes (`crm:clients:read`) | CRM | Ver clientes |
| Crear, editar y desactivar clientes (`crm:clients:write`) | CRM | Ver clientes y Editar clientes |
| Leer leads (`crm:leads:read`) | CRM, con «Leads» | Ver leads |
| Crear, editar, cualificar y descartar leads (`crm:leads:write`) | CRM, con «Leads» | Ver leads y Editar leads |
| Puntuación de leads (`crm:leads:read:scoring`) | CRM, con «Leads» | Ver leads |
| Leer comentarios de presupuesto (`crm:budgets:comments:read`) | CRM | Ver presupuestos y Ver comentarios de cliente en presupuestos |
| Crear comentarios de presupuesto (`crm:budgets:comments:write`) | CRM | Ver presupuestos y Escribir comentarios de cliente en presupuestos |
| Leer firmas de presupuesto (`crm:budgets:signatures:read`) | CRM | Ver presupuestos |
| Leer facturas (`crm:invoices:read`) | Finanzas | Ver facturas |
| Leer tickets de soporte (`support:tickets:read`) | Tickets de soporte, con «Tickets propios» | Nada |
| Gestionar tickets de soporte (`support:tickets:write`) | Tickets de soporte, con «Tickets propios» | Nada |
| Leer archivos (`fm:files:read`) | Gestor de archivos | Nada |
| Subir archivos (`fm:files:write`) | Gestor de archivos | Nada |
| Listar usuarios externos (`crm:users:read`) | Integraciones | Nada |
| Dar de alta y actualizar usuarios externos (`crm:users:write`) | Integraciones | Nada |
| Escribir mensajes (`chat:messages:send`) | Chat | Nada |
| Leer los mensajes del canal (`chat:messages:view`) | Chat | Nada |
| Ver los canales (`chat:channels:view`) | Chat | Nada |
| Crear canales (`chat:channels:create`) | Chat | Nada |
| Editar y archivar canales (`chat:channels:manage`) | Chat | Nada |
| Gestionar los miembros de los canales (`chat:members:manage`) | Chat | Nada |
| Recibir avisos de novedades del chat (`chat:events:subscribe`) | Chat | Nada |
| Ver los agentes de IA del canal (`chat:agents:view`) | Chat, con «Agentes de canal» | Nada |

Los permisos del chat no le piden nada a la persona responsable porque la puerta real está después: tu aplicación no entra en ningún canal hasta que una persona de la empresa se lo abre, canal a canal, con su propio permiso. Lo explica [Scopes y acceso por canal](https://os.utilia.ai/docs/developers/chat-platform/scopes-and-access).

El detalle de cada permiso, con las rutas que abre, está en el [catálogo de permisos de la API](https://os.utilia.ai/docs/developers/api/scopes-catalog).

## Lo que nunca se puede pedir

Una aplicación del catálogo la instalan muchas empresas con un consentimiento de pocos clics, y la puede publicar cualquier desarrollador. Por eso quedan fuera, sin excepción:

- **Todo lo que mueve dinero o corta un ingreso**: cobrar, devolver, métodos de pago, autorizaciones de cobro, suscripciones y cobros programados (`billing:*`).
- **Crear, emitir, enviar, anular o rectificar facturas** (`crm:invoices:write`, `issue`, `send`, `cancel` y `rectify`). Una factura emitida tiene efectos fiscales que no se deshacen.
- **Los datos fiscales** de clientes y de usuarios (`crm:clients:read:fiscal-data` y `crm:users:read:fiscal-data`).
- **Los datos personales más delicados**: las notas internas de contactos, leads y clientes, los contactos que se han opuesto a recibir correos, la conversión de leads, enviar los datos de los tickets a un proveedor de IA y verificar firmas.
- **Gobernar agentes de IA en los canales** (`chat:agents:manage:external`).
- **Lo que un tercero no necesita**: la jerarquía de grupos de empresas, la fecha de nacimiento de los contactos y la telemetría propia de la aplicación (`analytics:*`).

En la API, una parte de estos permisos solo los puede conceder un Super Administrador con un motivo escrito. Esa decisión no cabe en una instalación de un clic, así que el catálogo no los ofrece. Si tu producto los necesita, la empresa crea su propia aplicación en **Ajustes › Creadas por tu empresa** y le concede ella esos permisos, bajo su control.

Si la ficha pide uno que no está en la lista, el control «Solo pide permisos que el catálogo admite» queda pendiente y el envío se rechaza con `SCOPE_NOT_ALLOWED_IN_CATALOG`.

## Los permisos de tu propia aplicación

Lo de arriba es lo que tu aplicación pide a cada empresa. Aparte, la aplicación de tu cuenta de desarrollador, la que publica la ficha, tiene dos permisos propios sobre sus instalaciones, que ninguna empresa concede:

| Permiso | Para qué |
| - | - |
| Ver las instalaciones de esta aplicación (`apps:installations:read`) | Consultar las empresas que han instalado tus fichas, con su estado y los permisos que concedieron. |
| Recibir las credenciales de cada instalación (`apps:installations:exchange`) | Canjear el código de un solo uso de cada instalación por su clave de API y su clave de firma, solo desde tu servidor. |

Se le añaden solos al crear su ficha, y en el editor de permisos de la aplicación salen en el grupo «Instalaciones del catálogo». Solo existen en las cuentas de desarrollador: una aplicación creada por una empresa no puede tenerlos, y una ficha no puede pedírselos a quien la instala. Cómo se usan está en [La instalación y el canje del código](https://os.utilia.ai/docs/developers/apps-platform/installation-and-exchange) y en [la API de instalaciones](https://os.utilia.ai/docs/developers/apps-platform/installations-api).

## Qué aplicativos necesita tu aplicación

No los eliges tú: salen de los permisos que pides. La ficha los enseña a cada empresa como **Funciona con**, con los nombres del plan, e Integraciones va siempre. Si a una empresa le falta alguno:

- Si es vendible, la ficha lo dice («Acme necesita CRM, que no está en tu plan.») y la empresa no puede instalarla hasta tenerlo.
- Si está en «Próximamente», la ficha lo enseña con ese rótulo y tampoco se puede instalar.
- Si la empresa pierde un aplicativo después de instalarla, la instalación se detiene («Detenida: falta CRM en tu plan»), no se borra nada y vuelve a funcionar al recuperarlo. Mientras tanto, tus llamadas a ese aplicativo responden `403 MODULE_NOT_ENABLED`.

Cuantos menos aplicativos necesite tu aplicación, a más empresas le sirve.

## La persona responsable

Tu aplicación actúa en cada empresa con los permisos de una persona, la **persona responsable**, nunca con más. Quien instala la elige entre las personas activas que tienen todos los permisos de la tabla para lo que pide tu ficha y, si quien instala no es Super Administrador, que no ven más datos que él en ninguno de ellos.

Así, una misma llamada puede ver más o menos filas según la empresa: lo decide el alcance de su persona responsable (todo, su departamento, lo asignado o lo propio). Si la persona deja la empresa o se bloquea, la instalación se detiene y tus llamadas responden `403 APP_RESPONSIBLE_INACTIVE` hasta que la empresa elija a otra.

## Pedir más permisos o menos

Los permisos se cambian con una versión nueva de la ficha, que vuelve a revisión:

- **Si pides más**, al aprobarla cada empresa que la tiene instalada decide si los acepta. Mientras tanto, tu aplicación sigue funcionando con los que tenía y la instalación aparece como `ACCESS_PENDING`.
- **Si pides menos**, al aprobarla se quitan solos de todas las instalaciones.

En los dos casos recibes `APP_ACCESS_CHANGED` de cada instalación cuando cambian de verdad. Lo detalla [Versiones de la ficha y cambios de permisos](https://os.utilia.ai/docs/developers/apps-platform/publish-and-update).