Preguntas frecuentes del Marketplace de Flowlu
Autenticación y autorización
¿Qué métodos de autenticación son compatibles con las aplicaciones del Marketplace?
La autenticación identifica al usuario actual de la cuenta y funciona únicamente a través de un token de acceso (access token) obtenido mediante OAuth 2.0.
¿En nombre de quién se ejecuta una solicitud de API?
Una solicitud se ejecuta en nombre del usuario cuyo token de acceso se pase en el encabezado (header).
Si tu aplicación está integrada en la interfaz y utiliza el JS SDK para realizar solicitudes, dichas solicitudes siempre se ejecutan con el token de acceso del usuario actualmente autorizado. Tu aplicación también puede realizar solicitudes con el token de cualquier usuario desde su backend, según su propia lógica.
¿Cuándo debo usar OAuth 2.0 en lugar de una clave de API?
Una clave de API se emite por cuenta. Instalar una aplicación pública en muchas cuentas significaría emitir una nueva clave para cada cuenta, y tu aplicación tendría que rastrear qué clave pertenece a qué cuenta. Además, una clave de API no está vinculada a un usuario, por lo que no puedes autenticar a un usuario específico con ella.
OAuth 2.0 evita todo esto: los tokens de acceso no están vinculados a una cuenta, sino al usuario y a la aplicación.
¿Puedo realizar solicitudes de API desde el código frontend o las operaciones sensibles deben pasar por el backend?
Puedes llamar a la API tanto desde el backend como desde el frontend, pero desde el frontend, utiliza siempre el token del usuario actual. Los datos de la solicitud, incluido el token, son visibles en el navegador a través de las herramientas de desarrollador, por lo que un usuario podría leer el token de otro usuario y reutilizarlo libremente.
Cuando tu aplicación utiliza el JS SDK, siempre se utiliza el token del usuario actualmente autorizado y las solicitudes del frontend se ejecutan en su nombre.
¿Cómo se corresponden los permisos del manifiesto de la aplicación con el acceso a la API?
El manifiesto de la aplicación declara una lista de alcances (scopes). Cada alcance representa un conjunto de modelos (entidades) dentro de un módulo, además de un nivel de acceso a ellos. Hay dos niveles de acceso: solo lectura (read) y acceso total (full). Cada alcance tiene un código.
Los alcances controlan:
- los webhooks que tu aplicación puede registrar,
- la configuración de la aplicación vinculada a los modelos del módulo (usuarios, cuentas de CRM, facturas, etc.),
- las solicitudes de API que tu aplicación está autorizada a realizar contra los modelos del módulo.
Alcances disponibles:
| Alcance | Qué otorga |
users | El modelo de Usuario |
user.me | El modelo de Usuario, restringido al usuario actualmente autorizado |
crm | Todos los modelos en el módulo CRM |
crm.accounts | crm.account, crm.company, crm.contact, crm.phone, crm.email |
crm.deals | crm.leads, crm.leadsitems |
products | Todos los modelos en el módulo de productos |
fin | Todos los modelos en el módulo fin |
fin.invoices | fin.invoices, fin.items, fin.itemsrelation |
st | Todos los modelos en el módulo st |
task | Todos los modelos en el módulo de tareas |
agile | Todos los modelos en el módulo agile |
calendar | Todos los modelos en el módulo de calendario |
timetracker | Todos los modelos en el módulo de control de tiempo |
knowledgebase | Todos los modelos en el módulo de base de conocimiento |
workspace | Todos los modelos en el módulo de espacio de trabajo |
orgchart | Todos los modelos en el módulo de organigrama |
customlists | Todos los modelos en el módulo de listas personalizadas |
Precedencia de alcances Dos reglas deciden qué se aplica cuando los alcances se superponen:
- Mismo alcance, diferentes niveles. Si declaras un alcance con read y full a la vez, solo se utiliza el nivel más alto (full).
- General y específico juntos. Si declaras tanto un alcance de módulo como uno más estrecho del mismo módulo (por ejemplo, crm y crm.accounts), solo se utiliza el alcance general (crm) y el específico se ignora.
Apps privadas y públicas
¿Se requiere moderación para las apps privadas?
No. Las apps privadas no requieren moderación.
¿Se requiere una nueva moderación para cada actualización de una app pública?
Los cambios en la descripción, información de soporte, banners y logotipos no requieren una nueva moderación.
Cada nueva versión de la aplicación sí la requiere. Revisamos la funcionalidad declarada, si la aplicación funciona como se describe, la seguridad y si los alcances solicitados son suficientes y están justificados.
Ciclo de vida de la aplicación
¿Qué acciones del ciclo de vida están disponibles?
En la Consola de desarrollador, puedes:
- crear una aplicación,
- editar una aplicación,
- desactivar o activar una aplicación,
- publicar u ocultar una aplicación en el catálogo del Marketplace,
- eliminar una aplicación,
- crear una nueva versión,
- editar una versión,
- enviar una versión para moderación,
- publicar u ocultar una versión cambiando su estado,
- instalar una versión en otra cuenta a través de un enlace,
- instalar una versión en la cuenta actual.
Para una aplicación ya instalada en una cuenta, un administrador puede:
- desinstalarla,
- configurar el acceso para roles y grupos de usuarios,
- cambiar la configuración a nivel de aplicación,
- cambiar la configuración a nivel de usuario.
La aplicación instalada se integra en varias partes de la interfaz y puede utilizar el JS SDK.
¿Qué datos recibe la aplicación durante la instalación, actualización o eliminación?
El framework genérico de miniapps no entrega eventos de instalación, actualización o eliminación a la aplicación en sí. Los tipos de integración específicos, como la telefonía o los canales de comunicación, definen sus propios hooks de ciclo de vida, cubiertos en sus respectivas guías.
Una vez que la aplicación se está ejecutando en una cuenta en la interfaz de un usuario, el endpoint de la aplicación en la ubicación de integración recibe:
- el protocolo (http/https),
- el dominio de la cuenta (por ejemplo, micompania.flowlu.com),
- el código de idioma de la interfaz (en/pt/es),
- la ubicación de integración y su id único (del manifiesto de la aplicación),
- el código único de la aplicación (por ejemplo, da58bcec-8e2f-11f0-9f3e-eac2b61c1667),
- el número de versión (por ejemplo, 1.0.0).
Usando el JS SDK, la aplicación también puede:
- obtener los tokens de acceso y de actualización del usuario actual,
- obtener la configuración de la aplicación,
- obtener la configuración del usuario,
- realizar solicitudes de API dentro de los alcances y permisos declarados en el manifiesto de la aplicación, para el usuario actual,
- mostrar elementos de la interfaz (notificaciones, alertas, ventanas modales, paneles laterales, navegación, etc.).
¿Qué sucede con la configuración y los datos de una aplicación cuando se elimina?
Cuando se desinstala una aplicación de una cuenta, Flowlu elimina:
- los valores de configuración de la aplicación y del usuario,
- los archivos de la configuración de la aplicación,
- los webhooks que la aplicación registró,
- la configuración de roles y grupos de usuarios para la aplicación.
La aplicación deja de estar integrada en la interfaz.
Cuando se elimina una aplicación de la Consola de desarrollador, todo lo anterior sucede para cada cuenta donde está instalada, una cuenta a la vez. Los tokens de acceso y actualización de la aplicación para todos los usuarios también se eliminan.
¿Qué sucede en una actualización de la aplicación?
Flowlu compara los manifiestos de la versión instalada y la nueva versión, luego envía una actualización de los webhooks registrados para que coincidan con el nuevo manifiesto de la aplicación: se eliminan los webhooks del manifiesto antiguo y se registran los nuevos especificados.
La configuración de la aplicación, los roles y los archivos se conservan durante la actualización. La aplicación deja de estar integrada en cualquier ubicación que se haya eliminado del nuevo manifiesto de la aplicación y comienza a integrarse en cualquier ubicación que el nuevo manifiesto añada.
