10 de dez. de 2025·8 min
Design de diretório de integrações que escala de 3 a 30 apps
Projete um diretório de integrações que escala de 3 para 30 integrações com um modelo de dados simples, status claros, permissões e UI de progresso de setup.
Projete um diretório de integrações que escala de 3 para 30 integrações com um modelo de dados simples, status claros, permissões e UI de progresso de setup.
As pessoas abrem um diretório de integrações por um motivo: conectar ferramentas e mantê-las funcionando sem pensar nisso todo dia. Se a tela faz o usuário adivinhar o que está conectado, o que quebrou ou o que clicar em seguida, a confiança cai rápido.
Com 3 integrações, uma grade simples de logos pode funcionar. Com 30, isso desanda: as pessoas param de escanear, os chamados de suporte aumentam e o botão “Connect” vira uma armadilha porque cada integração pode estar em um estado diferente.
Cada card (ou linha) de integração deve responder três perguntas à primeira vista:
A maior parte da confusão vem de casos de borda que acontecem o tempo todo em times reais. Alguém conecta o Google com uma conta pessoal em vez da conta da empresa. Um token do Stripe expira e a cobrança para de sincronizar. Um workspace do Slack está conectado, mas o escopo de canal exigido nunca foi concedido, então o setup fica “meio feito” apesar da UI parecer OK.
Uma boa tela torna essas situações óbvias. Em vez de apenas “Connected”, mostre algo como “Connected (needs permission)” ou “Connected to: [email protected]” e coloque o próximo passo direto no card. Isso evita chute e mantém a lista gerenciável conforme cresce.
A forma mais simples de escalar um diretório de integrações é separar:
Isso fica legível com 3 integrações e continua funcionando com 30.
Uma Integration é a entrada do catálogo. É global, não vinculada a nenhuma workspace.
Um Install representa uma workspace habilitando aquela Integration (por exemplo: “Slack está ligado para a Workspace A”).
Uma Connection representa uma conta externa real ou credencial (por exemplo: “workspace Slack X via OAuth” ou “conta Stripe Y via chave de API”). Um Install pode ter muitas Connections.
Um conjunto mínimo de campos que tende a escalar bem:
Guarde config visível ao usuário (canal selecionado, apelido de URL de webhook, eventos habilitados) no Install ou Connection como dados normais. Armazene segredos (refresh tokens OAuth, chaves de API, signing secrets) apenas em um cofre de segredos ou em um campo criptografado com controles de acesso rígidos.
Não coloque segredos, códigos de autorização completos ou payloads brutos de webhooks em logs. Se precisar registrar algo, registre referências (connection_id) junto com metadados seguros (status HTTP, código de erro).
Para manter flexibilidade entre OAuth, API keys e webhooks, mantenha campos específicos de autenticação dentro de Connection (metadados de token vs fingerprint da chave vs status de verificação do webhook). Mantenha o estado visível na UI (habilitado e progresso de setup) no Install.
As pessoas abrem um diretório de integrações para responder três coisas rápido: está funcionando, quão avançado está o setup e o que devo fazer em seguida. Se suas palavras de status forem vagas, os chamados sobem e a confiança cai.
Comece com um conjunto pequeno de status que você consiga manter por anos:
Prefira status derivados a status armazenados. Labels armazenados tendem a ficar desatualizados: alguém corrige um erro e o badge continua vermelho. Status derivados são calculados a partir dos fatos que você já rastreia, como validade de tokens, passos de setup concluídos e se um admin pausou a integração. Se for armazenar algo, grave os fatos subjacentes (última sincronização bem-sucedida, último código de erro), não o rótulo final.
O progresso de setup funciona melhor como uma checklist curta, com separação clara entre obrigatório e opcional. Modele isso como definições de passos (estáticas, por integração) mais resultados de passos (por install).
Exemplo: Slack pode exigir “Autorizar workspace” e “Selecionar canais”, com um passo opcional como “Ativar visualização de mensagens”. A UI pode mostrar “2 de 3 passos obrigatórios concluídos” enquanto mantém os itens opcionais descobríveis sem bloquear.
Múltiplas connections sob uma integração podem transformar o diretório numa bagunça se você não planejar. Mantenha um card por integração, mostre a contagem de connections e agregue o status honestamente. Se qualquer connection estiver quebrada, mostre “Needs attention” com um hint tipo “1 de 4 workspaces precisa re-autenticar”. A visão geral continua limpa, mas reflete a realidade.
Permissões de integrações ficam confusas quando tudo é tratado como um único interruptor. É mais claro separar:
Comece com uma checagem leve de roles que se aplica em todo lugar. Para muitos apps, três roles são suficientes: Admin, Manager e Member. Admins podem fazer qualquer coisa. Managers podem configurar a maioria das integrações para seu time. Members podem usar integrações já habilitadas, mas não podem mudar configurações.
Depois acrescente flags por integração apenas onde fizerem diferença. A maioria das integrações (calendário, chat) pode seguir as regras padrão de roles. As sensíveis (pagamentos, folha, exports) devem exigir uma checagem extra como “Payments admin” ou “Billing manager”. Mantenha isso como um booleano no install da integração, não como um sistema novo de roles.
Um mapeamento legível:
Auditoria não precisa ser pesada, mas deve existir. Rastreie o suficiente para responder a perguntas de suporte e segurança rapidamente: quem conectou, quando as credenciais mudaram e quem desabilitou. Um painel “Activity” na página de detalhes com 5 a 20 eventos recentes costuma ser suficiente.
Exemplo: Stripe pode ser visível para todos, mas só Admins (ou usuários marcados “Billing manager”) podem conectar, rotacionar chaves ou desabilitar pagamentos. Slack pode permitir Managers conectarem, enquanto Members ainda recebem notificações quando habilitado.
Com 3 integrações você pode mostrar tudo. Com 30, o diretório tem que responder uma pergunta rápido: “Quais estão funcionando e o que devo fazer em seguida?” A abordagem mais limpa é separar escaneamento de ação.
Mantenha a vista do diretório focada em decisões rápidas. Empurre controles pesados para uma página de detalhes atrás de um único botão “Manage”.
Na lista, mostre apenas o que suporta o próximo clique:
A anatomia do card importa porque cria memória muscular. A ação primária deve sempre significar “o próximo passo” baseado no estado: Connect para novo, Continue setup para parcial, Reconnect quando auth expirou, e Manage quando tudo está saudável. Evite dois botões igualmente chamativos em cada card — deixa a página barulhenta.
Exemplo:
Estados vazios devem guiar sem despejar um manual na tela:
Isso mantém a tela calma com 30 integrações porque cada card responde: o que é, está OK e o que faço agora?
A lista leva a pessoa à integração certa. A página de detalhes é onde se decide: configurar, consertar ou desligar. Mantenha a estrutura da página consistente entre integrações, mesmo quando o trabalho de backend for diferente.
Comece por um overview compacto: nome da integração, uma linha de descrição e labels de status claras (Connected, Needs attention, Disabled). Adicione uma linha pequena de “Setup progress” para que o usuário saiba se falta um passo ou se ainda está no começo.
Um assistente simples funciona bem: 3 a 6 passos, uma tela por vez, com “Voltar” sempre disponível. Nomeie passos em linguagem clara (Conectar conta, Escolher workspace, Selecionar dados para sincronizar, Confirmar). Se um passo tiver escolhas opcionais, rotule-as como opcionais.
Se o setup puder ser pausado, diga isso claramente: “Você pode terminar depois. Nós guardaremos suas escolhas.” Isso reduz o medo de sair no meio.
Mostre Connections como uma tabela pequena: nome da conta, conectado por (usuário), data de criação e última sincronização.
Para “próxima sincronização”, evite promessas que você não pode cumprir (horários exatos). Use termos que você possa garantir, como “Next sync: scheduled soon” ou “Next sync: within the next hour”, baseado no que seu sistema realmente pode assegurar.
Mantenha ações arriscadas fora do caminho principal. Coloque ações primárias no topo (Continue setup, Reconnect). Coloque Disable e Disconnect em uma seção separada “Danger zone” ao final com uma explicação curta do impacto. Se suportar roles, diga em uma frase (por exemplo, “Apenas admins podem desconectar”).
Adicione um pequeno log de atividade: eventos recentes (conectado, token refrescado, sync falhou), timestamps e uma mensagem de erro curta que o usuário possa copiar para um ticket de suporte.
Adicionar uma integração é mais fácil quando você a trata como um pequeno produto. Precisa de uma listagem, uma forma de conectar, um lugar para guardar a connection e resultados claros para sucesso ou falha.
Adicione a integração ao catálogo para que ela apareça no diretório antes de alguém conectá-la. Inclua um nome claro, descrição curta, ícone e uma ou duas categorias (Messaging, Payments). Escreva expectativas de setup em termos simples, como “Conectar uma conta” e “Escolher uma workspace.” É aqui também que você define o que a integração vai precisar depois (OAuth scopes, campos obrigatórios, funcionalidades suportadas).
Escolha a conexão mais simples que combine com o provedor:
Quando o usuário completa o fluxo, crie um registro Connection atrelado à workspace ou conta, não apenas ao usuário. Armazene credenciais com segurança (criptografe em repouso e evite mostrar o segredo completo de novo). Salve o básico que você vai precisar para suporte: ID da conta do provedor, hora de criação, quem conectou e quais permissões foram concedidas.
Faça um teste simples imediatamente (para Stripe: buscar detalhes da conta). Se passar, mostre Connected e marque o progresso como pronto. Se passar parcialmente (conectado mas falta permissão), marque como Needs attention e direcione para a correção exata.
Mostre uma mensagem clara, uma ação recomendada e um fallback seguro. Exemplo: “Não foi possível alcançar o Stripe. Verifique a chave de API ou tente novamente.” Mantenha o diretório utilizável mesmo quando uma integração estiver quebrada.
Se estiver construindo em Koder.ai (koder.ai), você pode rascunhar o catálogo, o fluxo de setup e as regras de status em Planning Mode primeiro, depois gerar a UI e o backend a partir desse plano.
Integrações falham por motivos simples. Se seu diretório não explicar essas razões claramente, os usuários culpam seu app e o suporte fica sem pistas.
Agrupe falhas em buckets que combinam com correções reais: login expirado, permissão ausente, provedor com outage ou limite de taxa. Mantenha códigos de erro internos detalhados, mas mostre ao usuário um rótulo curto que ele entenda.
Quando algo quebra, a mensagem deve responder três coisas: o que aconteceu, o que o usuário deve fazer e o que seu sistema fará em seguida. Exemplo: “Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect.” Isso é mais calmo e acionável do que um erro cru de API.
Retentativa automática só quando o usuário não pode consertar. Um conjunto simples de regras é suficiente:
Statuses envelhecem a menos que você os atualize. Adicione um job leve de health check que periodicamente confirme se tokens ainda funcionam, se a última sync rodou e se o badge do diretório bate com a realidade.
Mantenha um histórico pequeno de eventos por install. Você não precisa de logs completos, só migalhas suficientes: timestamp, evento (“token refreshed”, “sync failed”), razão curta e quem disparou (usuário ou sistema). Adicione um campo de notas interno para que o suporte registre o que mudou e por quê.
Um diretório se complica rápido depois que você passa de alguns apps. O objetivo é simples: ajudar as pessoas a encontrar o que precisam em segundos e a achar problemas sem abrir todo card.
Comece com busca básica sobre nome da integração e categoria. A maioria dos usuários digita o que já conhece (“Slack”, “Stripe”), então casar pelo nome importa mais do que rankeamento sofisticado. Busca por categoria ajuda quando só sabem a função (payments, messaging).
Filtros devem espelhar a intenção real. Esses três cobrem a maior parte dos casos:
Para organizar a lista, escolha um agrupamento primário e mantenha-o. Agrupar por categoria funciona bem em volumes maiores (CRM, Payments, Messaging). Popularidade pode ser útil também, mas só se refletir sua base de usuários, não o marketing. Um padrão prático: mostrar os mais usados primeiro e agrupar o resto por categoria.
Você também precisa de um plano claro para “nem todo mundo deve ver tudo”. Se uma integração está atrás de feature flag ou plano, ou a esconde para a maioria, ou mostra desabilitada com um motivo curto tipo “Business plan”. Evite uma página cheia de cards acinzentados — parece quebrado.
Mantenha a performance rápida tratando lista e detalhes como cargas separadas. Faça paginação ou virtualize a lista para não renderizar 30 cards pesados de uma vez, e carregue detalhes só quando o usuário abrir uma integração. O diretório pode mostrar campos resumidos (Slack: Connected, Google: Needs attention, Stripe: Not set up) enquanto a página de detalhes busca histórico completo de connections.
Imagine um app de workspace chamado Pinework. Ele tem duas roles: Admin e Member. Admins podem conectar ferramentas e mudar configurações. Members podem usar ferramentas conectadas mas não podem adicionar ou remover.
No diretório de integrações do Pinework, cada card mostra um label claro (Connected, Needs setup, Error), uma linha curta “o que faz” e progresso como “2 de 3 passos”. As pessoas conseguem ver o que funciona e o que falta sem clicar.
Slack é usado para notificações. Um Admin abre Slack e vê: Status: Connected, Setup: “3 de 3 passos.” Members também veem Slack, mas a ação principal está desabilitada e lê “Peça a um Admin para gerenciar.” Se Slack desconectar, Members ainda veem o que quebrou, mas não os controles de reconectar.
Google é usado para calendários. Pinework suporta duas equipes, então permite múltiplas connections. O card do Google mostra: Status: Connected (2 accounts). Abaixo, uma linha lista “Marketing Calendar” e “Support Calendar.” O setup pode estar completo, e a página de detalhes mostra duas connections separadas para que um Admin revogue apenas uma.
Stripe é usado para cobrança. Um setup parcial comum é: a conta está conectada, mas webhooks não foram finalizados. O card mostra: Status: Needs setup, Progresso: “2 de 3 passos”, com um aviso tipo “Payments podem não sincronizar.” A visão de detalhes deixa o passo restante explícito:
Isso evita o doloroso “parece conectado mas nada funciona”.
Um diretório costuma quebrar quando um app cresce de poucas integrações para dezenas. Os problemas raramente são “big tech”. São erros pequenos de rotulagem e modelagem que confundem as pessoas diariamente.
Um problema comum é misturar “installed” vs “connected”. Installed geralmente significa “disponível na sua workspace”. Connected significa credenciais reais existem e dados podem fluir. Quando isso se mistura, usuários clicam em uma integração que parece pronta e batem em um beco.
Outro erro é inventar muitos estados de status. Times começam com um badge simples, depois adicionam casos de borda: pending, verifying, partial, paused, degraded, blocked, expiring, e mais. Com o tempo, esses rótulos se desviam porque ninguém os mantém consistentes. Mantenha um conjunto pequeno ligado a checagens que você realmente pode rodar.
Permissões ocultas também causam problema. Alguém conecta uma conta e depois descobre que a integração tinha acesso maior que o esperado. Mostre os escopos antes do passo final de “Connect” e novamente na página de detalhes para que admins possam auditar.
Muitos apps precisam de múltiplas connections: dois workspaces Slack, várias contas Stripe ou uma conta Google compartilhada além de contas pessoais. Se você codificar “uma integração = uma connection”, vai acabar com soluções feias depois.
Planeje para:
Mantenha a vista de lista leve. Quando você enche com logs, mapeamentos de campos e descrições longas, a leitura fica lenta. Use a lista para nome, propósito curto e progresso. Ponha histórico e configurações avançadas na página de detalhes.
Um diretório de integrações escalável resume-se a um modelo simples e uma UI honesta. Se os usuários conseguem responder três perguntas rápido, o sistema parece previsível: o que está conectado, o que está quebrado e o que devo fazer em seguida?
Checklist antes de lançar:
Próximo passo: escolha três integrações que você já conhece bem e modele-as de ponta a ponta: uma ferramenta de chat (OAuth), uma conexão estilo Google (OAuth com scopes) e uma ferramenta de pagamentos (chave de API + webhooks). Se seu modelo conseguir expressar as três sem casos especiais, provavelmente escalará para 30.
Trate-o como um painel de controle, não como uma página de marketing. Cada card deve mostrar rapidamente para que serve a integração, se está funcionando agora e a única próxima ação que o usuário deve tomar. Se os usuários precisarem clicar só para descobrir “isso está conectado?”, o diretório vai parecer pouco confiável conforme cresce.
Uma regra simples: um card deve responder “o que é”, “está saudável” e “e agora?”. Normalmente isso significa nome + uma linha de propósito, um status com um timestamp recente (última sincronização ou verificação) e um botão primário que muda conforme o estado. Deixe o resto atrás de “Manage” para manter a leitura rápida.
Separe o que você oferece do que uma workspace ativou e das credenciais reais. Use um Integration global (entrada do catálogo), um Install (ativado na workspace) e um Connection (conta OAuth, chave de API ou webhook). Isso evita a confusão comum em que “instalado” e “conectado” se misturam e os usuários não sabem o que é real.
Equipes reais muitas vezes precisam de mais de uma conta externa para o mesmo provedor. Marketing e Suporte podem ter calendários Google diferentes, ou a empresa pode ter várias contas Stripe. Modelar múltiplas Connections sob um mesmo Install mantém o diretório limpo e permite que admins gerenciem contas individualmente na página de detalhes.
Use um conjunto pequeno de labels que você consiga manter consistente, como Not set up, In progress, Connected, Needs attention e Disabled. Depois, derive essas labels a partir de fatos verificáveis — validade do token, passos obrigatórios concluídos e última sincronização bem-sucedida. Isso evita badges desatualizados que continuam vermelhos depois que o problema foi resolvido.
Faça do progresso de configuração uma checklist curta de passos obrigatórios, mais passos opcionais que não bloqueiem a conclusão. Armazene a definição dos passos por integração e os resultados por install, assim a UI pode mostrar algo como “2 de 3 passos obrigatórios concluídos”. Mostre sempre o próximo passo obrigatório sem que o usuário precise procurar.
Comece com uma regra de roles simples que valha em todo lugar, e acrescente verificações extras apenas para integrações sensíveis. Em muitos produtos, Admins podem configurar, Managers configuram a maioria das ferramentas, e Members usam ferramentas já habilitadas sem poder conectar ou alterar. Para pagamentos ou folha, adicione uma flag única como “billing/payments admin” em vez de inventar um novo sistema de roles.
Mantenha as configurações visíveis como dados normais, mas armazene segredos (refresh tokens, chaves de API) em um cofre de segredos ou campos criptografados com controles estritos. Nunca registre segredos brutos, códigos de autorização ou payloads de webhooks; registre metadados seguros e referências como o connection_id. Isso reduz riscos e facilita conformidade e suporte.
Mostre uma mensagem de erro que diga o que aconteceu, o que o usuário deve fazer e o que seu sistema fará automaticamente. Retentativas automáticas devem ocorrer só para problemas que o usuário não pode consertar (queda do provedor, rede). Para auth expirado ou permissões faltantes, pare as tentativas e faça “Reconnect” ou “Fix permissions” a ação principal.
Mantenha a busca simples e focada: nome do provedor primeiro, depois categoria. Adicione filtros que reflitam intenção, como Connected, Needs attention e Not set up, para as pessoas localizarem problemas rapidamente. Se estiver usando Koder.ai, esboce campos do catálogo, regras de status e passos de configuração no Planning Mode primeiro para que a UI e o backend gerados permaneçam consistentes à medida que você adiciona integrações.