Diseña un directorio de integraciones que escale de 3 a 30 integraciones con un modelo de datos simple, estados claros, permisos y una UI de progreso de configuración.
La gente abre un directorio de integraciones por una razón: conectar herramientas y hacer que sigan funcionando sin tener que pensarlas a diario. Si la pantalla obliga a los usuarios a adivinar qué está conectado, qué está roto o qué hacer a continuación, la confianza cae rápido.
Con 3 integraciones, una cuadrícula simple de logotipos puede funcionar. Con 30, se viene abajo: la gente deja de escanear, los tickets de soporte aumentan y el botón “Connect” se vuelve una trampa porque cada integración puede estar en un estado distinto.
Cada tarjeta (o fila) de integración debería responder tres preguntas de un vistazo:
La mayor parte de la confusión viene de casos límite que ocurren constantemente en equipos reales. Alguien conecta Google con una cuenta personal en lugar de la de la empresa. Un token de Stripe expira y la facturación deja de sincronizar. Se conecta un workspace de Slack, pero nunca se concedió el scope de canal requerido, así que la configuración está “a medias” aunque la UI parezca bien.
Una buena pantalla hace esas situaciones obvias. En lugar de solo “Connected”, muestra algo como “Connected (needs permission)” o “Connected to: [email protected]”, y coloca el siguiente paso directamente en la tarjeta. Eso evita conjeturas y mantiene la lista manejable a medida que crece.
La forma más simple de escalar un directorio de integraciones es separar:
Esto sigue siendo legible con 3 integraciones y sigue funcionando con 30.
Una Integration es la entrada del catálogo. Es global, no ligada a ningún workspace.
Un Install representa que un workspace habilitó esa Integration (por ejemplo: “Slack está activado para Workspace A”).
Una Connection representa una cuenta externa real o credencial (por ejemplo: “Slack workspace X vía OAuth” o “Stripe account Y vía API key”). Un Install puede tener muchas Connections.
Un conjunto mínimo de campos que suele escalar bien:
Almacena la configuración visible al usuario (canal seleccionado, apodo de URL de webhook, eventos habilitados) en el Install o en la Connection como datos normales. Guarda los secretos (refresh tokens OAuth, API keys, signing secrets) solo en un almacén de secretos o en un campo encriptado con controles de acceso estrictos.
No pongas secretos, códigos de autorización completos ni payloads brutos de webhooks en los logs. Si necesitas registrar algo, registra referencias (connection_id) más metadatos seguros (estado HTTP, código de error).
Para mantener flexibilidad entre OAuth, API keys y webhooks, guarda los campos específicos de autenticación dentro de Connection (metadatos del token vs huella de la key vs estado de verificación del webhook). Mantén el estado orientado a UI (enabled y progreso de configuración) en Install.
La gente abre un directorio de integraciones para responder tres cosas rápido: ¿funciona?, ¿qué tan avanzada está la configuración? y ¿qué debo hacer ahora? Si tus palabras de estado son vagas, aumentan los tickets de soporte y baja la confianza.
Empieza con un conjunto pequeño de estados que puedas mantener años:
Prefiere estado derivado en vez de estado almacenado. Las etiquetas guardadas se desactualizan: alguien arregla un error y la insignia queda roja. El estado derivado se calcula a partir de hechos que ya rastreas, como si los tokens son válidos, si los pasos requeridos están hechos y si un admin pausó la integración. Si almacenas algo, guarda los hechos subyacentes (última sincronización exitosa, último código de error), no la etiqueta final.
El progreso de configuración funciona mejor como una lista corta de verificación, con una separación clara entre lo requerido y lo opcional. Modelalo como definiciones de pasos (estáticas, por integración) más resultados de pasos (por install).
Ejemplo: Slack podría requerir “Autorizar workspace” y “Seleccionar canales”, con un paso opcional como “Habilitar vistas previas de mensajes”. La UI puede mostrar “2 de 3 pasos requeridos completos” y mantener los opcionales visibles sin bloquear.
Varias connections bajo una misma integración pueden convertir un directorio en un desastre si no lo planificas. Mantén una tarjeta por integración, muestra el conteo de connections y resume el estado honestamente. Si alguna connection está rota, muestra “Needs attention” con una pista como “1 de 4 workspaces necesita re-auth.” La vista general sigue limpia pero refleja la realidad.
Los permisos de integraciones se vuelven un lío cuando todo se trata como un solo interruptor. Es más claro separar:
Empieza con una comprobación ligera de roles que se aplique en todas partes. Para muchas apps, tres roles son suficientes: Admin, Manager y Member. Los Admins pueden hacer cualquier cosa. Los Managers pueden configurar la mayoría de integraciones para su equipo. Los Members pueden usar integraciones ya habilitadas, pero no pueden cambiar ajustes.
Luego añade flags de permiso por integración solo donde importen. La mayoría de integraciones (calendario, chat) pueden seguir las reglas de rol por defecto. Las sensibles (pagos, nómina, exportaciones) deberían requerir una comprobación extra como “Payments admin” o “Billing manager.” Mantén esto como un booleano simple en el install de la integración, no como un sistema de roles nuevo.
Un mapeo legible:
El audit no necesita ser pesado, pero debe existir. Registra lo suficiente para responder preguntas de soporte y seguridad con rapidez: quién lo conectó, cuándo cambiaron credenciales y quién lo deshabilitó. Un panel de “Activity” en la página de detalles con 5 a 20 eventos recientes suele ser suficiente.
Ejemplo: Stripe puede ser visible para todos, pero solo Admins (o usuarios marcados “Billing manager”) pueden conectarlo, rotar keys o deshabilitar pagos. Slack puede permitir que Managers conecten, mientras que Members continúan recibiendo notificaciones una vez habilitado.
Con 3 integraciones, puedes mostrar todo. Con 30, el directorio debe responder rápido a una pregunta: “¿Cuáles funcionan y qué debo hacer ahora?” El enfoque más claro es separar escaneo de acción.
Mantén la vista del directorio enfocada en decisiones rápidas. Empuja controles más pesados a una página de detalles detrás de un único botón “Manage”.
En la lista, muestra solo lo que apoya el siguiente clic:
La anatomía de la tarjeta importa porque crea memoria muscular. La acción primaria siempre debe significar “el siguiente paso” según el estado: Connect para nuevo, Continue setup para parcial, Reconnect cuando la auth expiró y Manage cuando todo está sano. Evita dos botones igualmente llamativos en cada tarjeta. Hace que la página se sienta ruidosa.
Ejemplo:
Los estados vacíos deben guiar sin soltar un manual en pantalla:
Así la página se mantiene calmada con 30 integraciones porque cada tarjeta responde: ¿qué es?, ¿está bien? y ¿qué hago ahora?
La lista del directorio lleva a la integración correcta. La página de detalles es donde deciden: configurarla, arreglarla o apagarla. Mantén la estructura de la página consistente en todas las integraciones, incluso si el trabajo de backend difiere.
Empieza con un resumen compacto: nombre de la integración, una descripción de una línea y etiquetas de estado claras (Connected, Needs attention, Disabled). Añade una pequeña línea de “Setup progress” para que los usuarios sepan si están a un paso de terminar o aún al inicio.
Un asistente sencillo funciona bien: 3 a 6 pasos, una pantalla a la vez, con “Back” siempre disponible. Nombra los pasos en lenguaje claro (Conectar cuenta, Elegir workspace, Seleccionar datos a sincronizar, Confirmar). Si un paso tiene opciones opcionales, márcalas como opcionales en lugar de ocultarlas.
Si la configuración se puede pausar, dilo claramente: “Puedes terminar después. Guardaremos tus elecciones.” Eso reduce el miedo a salirse a mitad.
Muestra las Connections como una tabla pequeña: nombre de la cuenta, conectado por (usuario), fecha de creación y última sincronización.
Para “next sync”, evita promesas que no puedas cumplir (como tiempos exactos). Usa redacción que puedas respaldar, por ejemplo “Next sync: scheduled soon” o “Next sync: within the next hour”, según lo que realmente pueda garantizar tu sistema.
Mantén las acciones de riesgo fuera del camino principal. Coloca las acciones primarias arriba (Continue setup, Reconnect). Pon Disable y Disconnect en una sección separada de “Danger zone” al final con una breve explicación del impacto. Si soportas roles, indícalo en una frase (por ejemplo, “Solo los admins pueden desconectar”).
Añade un pequeño activity log: eventos recientes (connected, token refreshed, sync failed), timestamps y un breve mensaje de error que los usuarios puedan copiar en un ticket de soporte.
Agregar una integración es más fácil si la tratas como un pequeño producto. Necesita una entrada en el catálogo, una forma de conectar, un lugar para almacenar la connection y resultados claros para éxito o fallo.
Añade la integración al catálogo para que aparezca en el directorio incluso antes de que alguien la conecte. Incluye un nombre claro, descripción corta, ícono y una o dos categorías (Messaging, Payments). Escribe expectativas de configuración en palabras simples, como “Conectar una cuenta” y “Elegir workspace.” Aquí también defines lo que la integración necesitará luego (OAuth scopes, campos requeridos, features soportadas).
Elige la conexión más simple que coincida con el proveedor:
Cuando el usuario completa el flujo, crea un registro Connection ligado al workspace o cuenta, no solo al usuario. Guarda las credenciales de forma segura (encripta en reposo y evita mostrar el secreto completo otra vez). Guarda lo básico que necesitarás para soporte: provider account ID, hora de creación, quién lo conectó y qué permisos se concedieron.
Ejecuta una prueba simple de inmediato (para Stripe: obtener detalles de la cuenta). Si pasa, muestra Connected y marca el progreso como listo. Si pasa parcialmente (conectado pero falta permiso), marca Needs attention y apunta al arreglo exacto.
Muestra un mensaje claro, una acción recomendada y una alternativa segura. Por ejemplo: “No pudimos contactar a Stripe. Revisa la API key o intenta de nuevo.” Mantén el directorio usable incluso cuando una integración falle.
Si construyes sobre Koder.ai (koder.ai), puedes redactar el catálogo, el flujo de configuración y las reglas de estado en Planning Mode primero, y luego generar la UI y el backend desde ese plan.
Las integraciones fallan por razones mundanas. Si tu directorio no puede explicar esas razones con claridad, los usuarios culpan a tu app y el soporte no tiene con qué trabajar.
Agrupa fallos en cubos que coincidan con arreglos reales: login expirado, permiso faltante, caída del proveedor o límite de tasa. Mantén códigos de error internos detallados, pero muestra a los usuarios una etiqueta corta y entendible.
Cuando algo falla, el mensaje debería responder tres cosas: qué pasó, qué debe hacer el usuario y qué hará tu sistema después. Ejemplo: “Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect.” Es más calmado y accionable que un error de API crudo.
Auto-reintenta solo cuando el usuario no pueda arreglarlo por sí mismo. Un conjunto simple de reglas es suficiente:
Los estados se vuelven obsoletos a menos que los refresques. Añade un trabajo ligero de health check que confirme periódicamente que los tokens siguen funcionando, que la última sincronización corrió y que la insignia del directorio coincide con la realidad.
Guarda un pequeño historial de eventos por install. No necesitas logs completos, solo migas de pan: timestamp, evento (“token refreshed”, “sync failed”), motivo breve y quién lo disparó (usuario o sistema). Añade un campo de notas interno para que soporte registre qué cambiaron y por qué.
Un directorio se desordena rápido al pasar unas pocas apps. El objetivo es simple: ayudar a la gente a encontrar lo que necesita en segundos y detectar problemas sin abrir cada tarjeta.
Empieza con búsqueda básica por nombre de integración y categoría. La mayoría de usuarios escriben lo que ya conocen (“Slack”, “Stripe”), así que la coincidencia por nombre importa más que rankeos complejos. La búsqueda por categoría ayuda cuando solo saben la función (payments, messaging).
Los filtros deben reflejar intención real. Estos tres cubren la mayoría de casos:
Para organizar la lista, elige una agrupación primaria y mantente con ella. Agrupar por categoría funciona bien a mayores cantidades (CRM, Payments, Messaging). La popularidad puede ser útil también, pero solo si refleja a tu base de usuarios, no marketing. Un default práctico: mostrar primero las más usadas, luego agrupar el resto por categoría.
También necesitas un plan claro para “no todos deberían ver todo”. Si una integración está detrás de un feature flag o de un plan, o la ocultas para la mayoría o la muestras deshabilitada con una razón corta como “Business plan.” Evita llenar la página de tarjetas en gris; hace que la pantalla parezca rota.
Mantén el rendimiento ágil tratando lista y detalles como cargas separadas. Pagina o virtualiza la lista para no renderizar 30 tarjetas pesadas a la vez, y carga en diferido los detalles solo cuando el usuario abre una integración. El directorio puede mostrar campos resumidos (Slack: Connected, Google: Needs attention, Stripe: Not set up) mientras la página de detalles obtiene el historial completo de connections.
Imagina una app de workspace llamada Pinework. Tiene dos roles: Admin y Member. Los Admins pueden conectar herramientas y cambiar ajustes. Los Members pueden usar las herramientas conectadas pero no pueden añadir ni quitar integraciones.
En el directorio de integraciones de Pinework, cada tarjeta muestra una etiqueta clara (Connected, Needs setup, Error), una línea corta de “qué hace” y progreso de configuración como “2 de 3 pasos.” La gente puede saber qué funciona y qué está pendiente sin hacer clic.
Slack se usa para notificaciones. Un Admin abre Slack y ve: Estado: Connected, Progreso: “3 de 3 pasos.” Los Members también ven Slack, pero la acción principal está deshabilitada y muestra “Ask an Admin to manage.” Si Slack se desconecta, los Members pueden ver qué falló, pero no los controles de reconexión.
Google se usa para calendarios. Pinework soporta dos departamentos, así que permite múltiples connections. La tarjeta de Google muestra: Estado: Connected (2 accounts). Debajo aparece una línea corta con “Marketing Calendar” y “Support Calendar.” La configuración puede estar completa y la página de detalles muestra dos connections separadas para que un Admin pueda revocar solo una.
Stripe se usa para facturación. Una configuración parcial común es: la cuenta está conectada, pero los webhooks no están terminados. La tarjeta muestra: Estado: Needs setup, Progreso: “2 de 3 pasos,” con una advertencia como “Payments may not sync.” La vista de detalles hace explícito el paso faltante:
Eso evita la dolorosa situación “parece conectado pero nada funciona.”
Un directorio de integraciones suele romperse cuando una app pasa de pocas integraciones a docenas. Los problemas rara vez son “gran tecnología.” Son pequeños errores de etiquetado y modelado que confunden a la gente cada día.
Un problema común es mezclar “installed” vs “connected.” Installed suele significar “disponible en tu workspace.” Connected significa que existen credenciales reales y los datos pueden fluir. Cuando se mezclan, los usuarios hacen clic en una integración que parece lista y se topan con un callejón sin salida.
Otro error es inventar demasiados estados. Los equipos empiezan con una insignia simple y luego añaden casos límite: pending, verifying, partial, paused, degraded, blocked, expiring, y más. Con el tiempo, esas etiquetas se desalinean porque nadie las mantiene consistentes. Mantén un conjunto pequeño atado a comprobaciones que realmente puedas ejecutar, como Not connected, Connected, Needs attention.
Los permisos ocultos también causan problemas. Alguien conecta una cuenta y luego descubre que la integración tenía más acceso del esperado. Haz el scope obvio antes del paso final “Connect” y muéstralo de nuevo en la página de detalles para que los admins puedan auditarlo.
Muchas apps necesitan múltiples connections: dos Slack workspaces, varias cuentas Stripe o una cuenta Google compartida más cuentas personales. Si codificas “una integración = una connection”, terminarás con parches feos después.
Planifica para:
Mantén la vista de lista ligera. Cuando la llenas de logs, mapeos de campos y descripciones largas, el escaneo se vuelve lento. Usa la lista para nombre, propósito corto y progreso. Pon historial y ajustes avanzados en la página de detalles.
Un directorio de integraciones escalable se reduce a un modelo simple y una UI honesta. Si los usuarios pueden responder tres preguntas rápido, el sistema se siente predecible: qué está conectado, qué está roto y qué debo hacer ahora.
Checklist antes de lanzar:
Siguiente paso: elige tres integraciones que ya conozcas bien y modelalas de extremo a extremo: una herramienta de chat (OAuth), una conexión tipo Google (OAuth con scopes) y una herramienta de pagos (API key más webhooks). Si tu modelo puede expresar las tres sin casos especiales, normalmente escalará a 30.
Trátalo como un panel de control, no como una página de marketing. Cada tarjeta debe mostrar rápidamente para qué sirve la integración, si está funcionando ahora mismo y la única acción siguiente que debería tomar el usuario. Si los usuarios tienen que hacer clic solo para saber “¿está esto conectado?”, el directorio se sentirá poco fiable a medida que crece.
Una regla simple: cada tarjeta debe responder “qué es”, “está sano” y “qué ahora”. Eso suele significar un nombre y una línea corta de propósito, un estado con una marca temporal reciente (última sincronización o última comprobación) y un botón primario que cambia según el estado. Mantén el resto detrás de “Manage” para que el escaneo sea rápido.
Separa lo que ofreces de lo que un workspace habilitó y de las credenciales que existen. Usa una Integration global (entrada del catálogo), un Install (habilitado en un workspace) y una Connection (cuenta OAuth real, API key o webhook). Esto evita el lío común donde “instalado” y “conectado” se mezclan y los usuarios no pueden distinguir qué es real.
Los equipos reales a menudo necesitan más de una cuenta externa para el mismo proveedor. Marketing y Soporte pueden conectar distintos calendarios de Google, o una empresa puede tener varias cuentas de Stripe. Modelar múltiples Connections bajo un mismo Install mantiene el directorio limpio y permite a los admins gestionar cuentas individualmente en la página de detalles.
Usa un conjunto pequeño de etiquetas que puedas mantener consistentes, por ejemplo: Not set up, In progress, Connected, Needs attention y Disabled. Luego deriva esas etiquetas de hechos que puedas comprobar (validez del token, pasos de configuración obligatorios completados, última sincronización exitosa). Así evitas insignias caducadas que siguen en rojo después de que el problema ya esté resuelto.
Haz el progreso de configuración como una lista corta de pasos requeridos más pasos opcionales que no bloqueen la finalización. Guarda las definiciones de pasos por integración y los resultados de pasos por install, de modo que la UI pueda decir algo como “2 de 3 pasos requeridos completos.” Los usuarios siempre deben ver el siguiente paso requerido sin buscar.
Empieza con una regla de roles simple que se aplique en todas partes y añade comprobaciones extra solo para integraciones sensibles. En muchos productos, los Admins pueden configurar, los Managers pueden configurar la mayoría de las herramientas y los Members pueden usar las herramientas habilitadas pero no conectar ni cambiar ajustes. Para pagos o nómina, añade una sola bandera “billing/payments admin” en lugar de inventar un sistema de roles nuevo.
Guarda la configuración visible al usuario como datos normales, pero almacena secretos (refresh tokens, API keys) en un almacén de secretos o campos encriptados con controles de acceso estrictos. No registres secretos en bruto, códigos de autorización ni payloads completos de webhooks; registra metadatos seguros y referencias como connection_id. Esto reduce riesgos y facilita el cumplimiento y soporte.
Muestra un mensaje de error que explique qué ocurrió, qué debe hacer el usuario y qué hará tu sistema automáticamente. Los reintentos deben ser silenciosos y limitados a cosas que el usuario no pueda arreglar (por ejemplo, caídas temporales). Para auth expirado o permisos faltantes, detén los reintentos y convierte “Reconnect” o “Fix permissions” en la acción principal.
Mantén la búsqueda simple y centrada en cómo piensan los usuarios: nombre del proveedor primero, luego categoría. Añade filtros que reflejen la intención, como Connected, Needs attention y Not set up, para que la gente encuentre problemas rápidamente. Si usas Koder.ai, primero redacta los campos del catálogo, las reglas de estado y los pasos de configuración en Planning Mode para que la UI y el backend generados sean coherentes a medida que añades integraciones.
