Diseño de un directorio de integraciones que escala de 3 a 30 apps

Qué necesita hacer una pantalla de integraciones (en términos claros)

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:

• ¿Qué es esto? (Nombre más un propósito corto)
• ¿Está funcionando ahora mismo? (Estado claro más última comprobación o última sincronización)
• ¿Qué hago ahora? (Connect, continuar configuración, re-autenticar, gestionar)

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.

Un modelo de datos simple: catalog vs installs vs connections

La forma más simple de escalar un directorio de integraciones es separar:

• lo que ofreces (el catálogo)
• lo que cada workspace habilitó (installs)
• qué cuentas externas o credenciales están en uso (connections)

Esto sigue siendo legible con 3 integraciones y sigue funcionando con 30.

Los tres objetos principales

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:

• Integration: id, key ("slack"), display_name, category, auth_type (oauth/api_key/webhook), docs_hint (texto corto), created_at
• Install: id, workspace_id, integration_id, status (enabled/disabled), setup_state (not_started/in_progress/complete), created_by, created_at, updated_at
• Connection: id, install_id, label ("Marketing Slack"), connection_status (ok/expired/error), external_account_id (si se conoce), scopes/permissions_granted, last_success_at, created_at

Config vs secrets (y qué no debe filtrarse)

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.

Estado y progreso de configuración que los usuarios comprendan

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:

• Not set up
• In progress
• Connected
• Needs attention
• Disabled

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.

Permisos y roles sin complicarlo

Los permisos de integraciones se vuelven un lío cuando todo se trata como un solo interruptor. Es más claro separar:

• quién puede ver una integración
• quién puede configurarla
• quién puede usarla día a día

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:

• View: Admin, Manager, Member
• Configure: Admin, Manager (Members pueden verlo pero no conectar ni editar)
• Use: Cualquiera en el workspace una vez habilitado (a menos que esté restringido)
• Sensitive override: Solo usuarios con una flag específica pueden configurar o disparar acciones

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.

Diseño de UI que funcione con 30 integraciones

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:

• Ícono, nombre y una descripción de una línea (mantén la longitud consistente)
• Una pastilla de estado clara (Connected, Needs setup, Error, Disabled)
• Un botón de acción primario
• Un botón secundario “Manage” para todo lo demás

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:

• Si “Google” está Connected, la acción primaria puede ser Manage.
• Si “Slack” falló anoche, muestra Error y haz que la acción primaria sea Reconnect.
• Si “Stripe” está a medias, muestra Needs setup y Continue setup.

Los estados vacíos deben guiar sin soltar un manual en pantalla:

• No hay integraciones instaladas: sugiere 2 o 3 opciones populares y qué desbloquean
• No hay resultados en la búsqueda: ofrece un consejo simple como “prueba ‘CRM’ o ‘billing’”
• Primera configuración: una frase sobre permisos y qué datos se accederán

Así la página se mantiene calmada con 30 integraciones porque cada tarjeta responde: ¿qué es?, ¿está bien? y ¿qué hago ahora?

La página de detalles: flujo de configuración, connections y controles

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 flujo de configuración que dé confianza

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.

Connections y controles que los usuarios no lamentarán

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.

Paso a paso: añadir una nueva integración de extremo a extremo

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.

1) Empieza por la entrada del catálogo

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).

2) Construye el método de conexión

Elige la conexión más simple que coincida con el proveedor:

1. OAuth cuando los usuarios deben iniciar sesión y aprobar accesos (común para Google, Slack)
2. API key cuando un usuario puede pegar un token del proveedor
3. Webhooks cuando el proveedor envía eventos a tu app

3) Guarda credenciales y crea un registro Connection

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.

4) Ejecuta una comprobación inicial y ajusta estado + progreso

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.

5) Decide qué verán los usuarios cuando falle

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.

Errores, reintentos e historial útil para soporte

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.

Reglas de reintento que no molesten a la gente

Auto-reintenta solo cuando el usuario no pueda arreglarlo por sí mismo. Un conjunto simple de reglas es suficiente:

• Proveedor caído o error de red: auto-reintento con backoff, conserva la última hora de éxito
• Rate limited: pausar, reintentar más tarde y mostrar “Paused (rate limit)”
• Auth expirado: detener reintentos y pedir al usuario que reconecte
• Permisos faltantes: detener y mostrar exactamente qué permiso falta
• Configuración errónea: detener y señalar la configuración que hay que completar

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.

Historial que soporte pueda usar

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é.

Búsqueda, filtros y organización del directorio

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:

• Connected (funcionando ahora)
• Needs attention (errores, token expirado, permiso faltante)
• Not set up (disponible pero sin installs)

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.

Ejemplo: Slack, Google y Stripe en una app real

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:

• Connect Stripe account (hecho)
• Choose billing plan mapping (hecho)
• Add webhook endpoint (no hecho)

Eso evita la dolorosa situación “parece conectado pero nada funciona.”

Errores comunes que hacen que las integraciones sean difíciles de gestionar

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.

No asumas una sola connection por integración

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:

• Múltiples connections bajo una integración
• Una “connection por defecto” clara (si hace falta)
• Connections compartidas vs personales
• Un lugar para ver quién la conectó

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.

Lista rápida y siguientes pasos

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:

• Separa el modelo: Integration (catálogo) vs Install (habilitado en este workspace) vs Connection (OAuth token, API key o webhook). Añade Event solo si necesitas historial de auditoría y soporte.
• Deriva el estado: calcula etiquetas desde comprobaciones (token válido, scopes OK, webhook accesible) más pasos completados, para que las insignias sean precisas.
• Mantén la vista de lista escaneable: cada fila muestra nombre, una etiqueta de estado clara y una “siguiente acción” (Connect, Continue, Reconnect, Fix permissions).
• Haz que las acciones del ciclo de vida sean primarias: Connect, Continue setup, Reconnect, Disable y Disconnect deben ser fáciles de encontrar, con confirmaciones cortas.
• Haz visibles y auditables los permisos: muestra quién puede conectar o desconectar, y registra quién cambió qué y cuándo.

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.