10 dic 2025·8 min
Progettare una directory di integrazioni scalabile da 3 a 30 app
Progetta una directory di integrazioni che scala da 3 a 30 integrazioni con un modello dati semplice, stati chiari, permessi e un'interfaccia di progresso setup.
Progetta una directory di integrazioni che scala da 3 a 30 integrazioni con un modello dati semplice, stati chiari, permessi e un'interfaccia di progresso setup.
Le persone aprono una directory di integrazioni per un motivo: collegare strumenti e farli funzionare senza pensarci ogni giorno. Se la schermata costringe gli utenti a indovinare cosa è connesso, cosa è rotto o cosa cliccare dopo, la fiducia cala in fretta.
Con 3 integrazioni, una semplice griglia di loghi può funzionare. Con 30, non più: le persone smettono di scorrere, i ticket di supporto aumentano e il pulsante “Connect” diventa una trappola perché ogni integrazione può essere in uno stato diverso.
Ogni scheda integrazione (o riga) dovrebbe rispondere a tre domande a colpo d’occhio:
La maggior parte della confusione nasce da casi limite che accadono continuamente nei team reali. Qualcuno collega Google con un account personale invece che quello aziendale. Un token Stripe scade e la fatturazione smette di sincronizzarsi. Uno workspace Slack è connesso, ma lo scope del canale richiesto non è mai stato concesso, quindi la configurazione è “a metà” anche se l’interfaccia sembra a posto.
Una buona schermata rende quelle situazioni ovvie. Invece di mostrare solo “Connected”, mostra qualcosa come “Connected (serve permesso)” o “Connected a: [email protected]”, e metti il prossimo passo direttamente sulla scheda. Così le persone evitano di indovinare e la lista resta gestibile man mano che cresce.
Il modo più semplice per scalare una directory di integrazioni è separare:
Questo rimane leggibile a 3 integrazioni e funziona anche a 30.
Un Integrazione è la voce del catalogo. È globale, non legata a nessuna workspace.
Un Install rappresenta una workspace che ha abilitato quell’Integrazione (per esempio: “Slack è attivato per Workspace A”).
Una Connessione rappresenta un vero account esterno o credenziale (per esempio: “workspace Slack X via OAuth” o “account Stripe Y via API key”). Una Install può avere molte Connessioni.
Un set minimo di campi che tende a scalare bene:
slack), display_name, category, auth_type (oauth/api_key/webhook), docs_hint (testo breve), created_atMarketing Slack), connection_status (ok/expired/error), external_account_id (se noto), scopes/permissions_granted, last_success_at, created_atConserva la config visibile all’utente (canale selezionato, nickname URL webhook, eventi abilitati) su Install o Connection come dati normali. Conserva i segreti (refresh token OAuth, API key, signing secret) solo in uno store di segreti o in un campo cifrato con controlli di accesso rigorosi.
Non mettere segreti, codici di autorizzazione completi o payload webhook grezzi nei log. Se devi loggare qualcosa, registra riferimenti (connection_id) più metadati sicuri (stato HTTP, codice errore).
Per restare flessibili tra OAuth, API key e webhook, tieni i campi specifici di autenticazione dentro Connection (metadata del token vs fingerprint della chiave vs stato verifica webhook). Mantieni lo stato mostrabile in UI (enabled e progresso setup) su Install.
Le persone aprono una directory di integrazioni per rispondere a tre cose rapidamente: funziona, quanto è avanzato il setup e cosa devo fare. Se le parole di stato sono vaghe, i ticket di supporto aumentano e la fiducia cala.
Inizia con un piccolo insieme di stati che puoi mantenere per anni:
Preferisci uno stato derivato piuttosto che un’etichetta memorizzata. Le etichette salvate si deteriorano: qualcuno risolve un errore ma il badge resta rosso. Lo stato derivato si calcola da fatti che già registri, come se i token sono validi, se i passi richiesti sono completi e se un admin ha messo in pausa l’integrazione. Se memorizzi qualcosa, memorizza i fatti sottostanti (ultimo sync riuscito, ultimo codice errore), non l’etichetta finale.
Il progresso di setup funziona meglio come una breve checklist, con una divisione chiara tra obbligatorio e opzionale. Modellalo come definizioni di passi (statiche, per integrazione) più risultati dei passi (per install).
Esempio: Slack potrebbe richiedere “Authorize workspace” e “Select channels”, con un passo opzionale come “Enable message previews”. L’interfaccia può mostrare “2 di 3 passi obbligatori completati” mantenendo gli elementi opzionali scoperti senza bloccare.
Più connessioni sotto un’unica integrazione possono trasformare la directory in un caos se non lo pianifichi. Mantieni una scheda per integrazione, mostra il conteggio connessioni e aggrega lo stato onestamente. Se una connessione è rotta, mostra “Needs attention” con un suggerimento tipo “1 di 4 workspace necessita di ri-auth”. L’overview resta pulita ma riflette la realtà.
I permessi per le integrazioni diventano complicati quando tutto è trattato come un singolo interruttore. È più chiaro separare:
Inizia con un controllo di ruolo leggero che vale ovunque. Per molte app, tre ruoli bastano: Admin, Manager e Member. Gli Admin possono fare tutto. I Manager possono configurare la maggior parte delle integrazioni per il loro team. I Member possono usare integrazioni già attivate, ma non possono cambiare le impostazioni.
Poi aggiungi flag di permesso per integrazione solo dove servono. La maggior parte (calendar, chat) può seguire le regole di ruolo di default. Quelle sensibili (pagamenti, payroll, esportazioni) dovrebbero richiedere un controllo extra come “Payments admin” o “Billing manager”. Mantieni questo come un semplice booleano sull’install dell’integrazione, non un intero nuovo sistema di ruoli.
Una mappatura leggibile:
L’audit non deve essere pesante, ma deve esistere. Traccia abbastanza per rispondere a domande di support e sicurezza: chi l’ha connessa, quando le credenziali sono cambiate e chi l’ha disabilitata. Un pannello “Activity” nella pagina dettagli con 5–20 eventi recenti è di solito sufficiente.
Esempio: Stripe può essere visibile a tutti, ma solo gli Admin (o gli utenti marcati “Billing manager”) possono connetterla, ruotare chiavi o disabilitare i pagamenti. Slack può permettere ai Manager di connettere, mentre i Member continuano a ricevere notifiche Slack una volta abilitata.
Con 3 integrazioni puoi mostrare tutto. Con 30, la directory deve rispondere a una domanda in fretta: “Quali funzionano e cosa devo fare dopo?” L’approccio più pulito è separare la scansione dall’azione.
Mantieni la vista directory focalizzata su decisioni rapide. Sposta i controlli più pesanti in una pagina dettagli dietro un singolo pulsante “Manage”.
Nella lista, mostra solo ciò che supporta il prossimo clic:
L’anatomia della scheda è importante perché costruisce la memoria muscolare. L’azione primaria dovrebbe sempre significare “il passo successivo” basato sullo stato: Connect per nuovo, Continue setup per parziale, Reconnect quando l’autenticazione è scaduta, e Manage quando tutto è sano. Evita due pulsanti ugualmente evidenti su ogni scheda: rendono la pagina rumorosa.
Esempio:
Gli stati vuoti dovrebbero guidare senza scaricare un manuale:
Questo mantiene la pagina calma a 30 integrazioni perché ogni scheda risponde: cos’è, va bene, e cosa faccio ora?
La lista porta le persone all’integrazione giusta. La pagina dettagli è dove decidono: configurare, risolvere o disattivare. Mantieni la struttura della pagina coerente per ogni integrazione, anche se il lavoro backend è diverso.
Inizia con un overview compatto: nome integrazione, una breve descrizione e etichette stato chiare (Connected, Needs attention, Disabled). Aggiungi una piccola linea “Setup progress” così l’utente sa se è a un passo dal finire o ancora all’inizio.
Un semplice wizard funziona bene: 3–6 passi, una schermata alla volta, con “Indietro” sempre disponibile. Nomina i passi in linguaggio semplice (Connetti account, Scegli workspace, Scegli dati da sincronizzare, Conferma). Se un passo ha scelte opzionali, etichettale come opzionali invece di nasconderle.
Se il setup può essere messo in pausa, dillo chiaramente: “Puoi finire più tardi. Terremo le tue scelte.” Questo riduce la paura di abbandonare.
Mostra le Connessioni come una piccola tabella: nome account, connesso da (utente), data creazione e ultimo sync.
Per “prossimo sync”, evita promesse che non puoi mantenere (orari esatti). Usa formulazioni sostenibili come “Next sync: pianificato a breve” o “Next sync: entro un’ora”, basate su quello che il sistema può garantire.
Tieni le azioni rischiose lontane dal percorso principale. Metti azioni primarie in alto (Continue setup, Reconnect). Metti Disable e Disconnect in una sezione “Danger zone” separata in fondo con una breve spiegazione dell’impatto. Se supporti i ruoli, dichiaralo in una frase (per esempio, “Solo gli admin possono disconnettere”).
Aggiungi un piccolo log attività: eventi recenti (connected, token refreshed, sync failed), timestamp e un breve messaggio di errore che l’utente può copiare nel ticket di supporto.
Aggiungere un’integrazione è più semplice se la tratti come un piccolo prodotto. Serve un listing, un modo per connettere, un luogo per salvare la connessione e risultati chiari per successo o fallimento.
Aggiungi l’integrazione al catalogo così appare nella directory anche prima che qualcuno la connetta. Includi nome chiaro, descrizione breve, icona e una o due categorie (Messaging, Payments). Scrivi le aspettative di setup in parole semplici, tipo “Connetti un account” e “Scegli workspace”. Qui definisci anche cosa servirà dopo (OAuth scopes, campi obbligatori, funzionalità supportate).
Scegli il metodo più semplice che si adatta al provider:
Quando l’utente completa il flusso, crea una Connection legata alla workspace o account, non solo all’utente. Salva le credenziali in modo sicuro (cifra a riposo e evita di mostrare il segreto completo di nuovo). Conserva le info base utili al support: provider account ID, data creazione, chi ha connesso e quali permessi sono stati concessi.
Esegui un test semplice subito (per Stripe: recupera i dettagli account). Se passa, mostra Connected e marca il progresso come pronto. Se passa solo parzialmente (connesso ma mancano permessi), marca Needs attention e indica la correzione esatta.
Mostra un messaggio chiaro, un’azione raccomandata e un fallback sicuro. Per esempio: “Non siamo riusciti a raggiungere Stripe. Controlla la API key o riprova.” Mantieni la directory usabile anche quando un’integrazione è rotta.
Se stai costruendo su Koder.ai (koder.ai), puoi prima redigere il catalogo, il flusso di setup e le regole di stato in Planning Mode, poi generare UI e backend da quel piano.
Le integrazioni falliscono per ragioni banali. Se la tua directory non sa spiegare quei motivi chiaramente, gli utenti incolperanno la tua app e il support non avrà cosa usare.
Raggruppa i fallimenti in categorie che corrispondono a fix reali: login scaduto, permesso mancante, outage provider o rate limit. Mantieni i codici errore interni dettagliati, ma mostra agli utenti una breve etichetta comprensibile.
Quando qualcosa si rompe, il messaggio dovrebbe rispondere a tre cose: cosa è successo, cosa dovrebbe fare l’utente e cosa farà il tuo sistema. Esempio: “Connessione Slack scaduta. Riconnetti per continuare la sincronizzazione. Riproveremo automaticamente dopo la riconnessione.” È più calmo e utile di un errore API grezzo.
Retry automatici solo quando l’utente non può risolvere da sé. Una semplice regola è sufficiente:
Gli stati diventano obsoleti a meno che non li aggiorni. Aggiungi un job leggero di health check che confermi periodicamente che i token funzionano ancora, l’ultimo sync è avvenuto e il badge della directory corrisponde alla realtà.
Conserva una piccola cronologia di eventi per install. Non servono log completi, solo briciole: timestamp, evento (“token refreshed”, “sync failed”), breve motivo e chi l’ha innescato (utente o sistema). Aggiungi un campo note interno così il support può registrare cosa ha cambiato e perché.
La directory si complica rapidamente oltre qualche app. L’obiettivo è semplice: aiutare le persone a trovare ciò che serve in pochi secondi e far notare i problemi senza aprire ogni scheda.
Parti con una ricerca base sul nome integrazione e sulla categoria. La maggior parte degli utenti digita ciò che già conosce (“Slack”, “Stripe”), quindi il matching per nome conta più di complesse rilevanze. La ricerca per categoria aiuta quando conoscono solo il ruolo (payments, messaging).
I filtri dovrebbero rispecchiare l’intento reale. Questi tre coprono la maggior parte dei casi:
Per organizzare la lista, scegli un raggruppamento primario e mantienilo. Il raggruppamento per categoria funziona bene con molti elementi (CRM, Payments, Messaging). La popolarità può essere utile solo se riflette la base utenti, non il marketing. Default pratico: mostra prima le più usate, poi raggruppa il resto per categoria.
Hai anche bisogno di un piano chiaro per “non tutti dovrebbero vedere tutto”. Se un’integrazione è dietro feature flag o piano, o la nascondi o la mostri disabilitata con una breve ragione come “Business plan”. Evita una pagina piena di schede grigie che sembra rotta.
Mantieni le performance reattive trattando lista e dettagli come caricamenti separati. Paginazione o virtualizzazione aiutano a non renderizzare 30 schede pesanti insieme, e carica i dettagli solo quando l’utente apre un’integrazione. La directory può mostrare campi di riepilogo mentre la pagina dettagli preleva la cronologia completa.
Immagina un’app di workspace chiamata Pinework. Ha due ruoli: Admin e Member. Gli Admin possono connettere strumenti e cambiare impostazioni. I Member possono usare strumenti connessi ma non aggiungerli o rimuoverli.
Nella directory di Pinework, ogni scheda mostra un’etichetta chiara (Connected, Needs setup, Error), una breve riga “a cosa serve” e progresso setup come “2 di 3 passi”. Le persone capiscono cosa funziona e cosa è in sospeso senza click inutili.
Slack è usato per notifiche. Un Admin apre Slack e vede: Stato: Connected, Setup: “3 di 3 passi.” I Member vedono comunque Slack, ma l’azione principale è disabilitata e mostra “Chiedi a un Admin di gestire.” Se Slack si disconnette, i Member possono vedere cosa è rotto ma non i controlli di reconnessione.
Google è usato per calendari. Pinework supporta due dipartimenti, quindi permette connessioni multiple. La scheda Google mostra: Stato: Connected (2 account). Sotto, una riga elenca “Marketing Calendar” e “Support Calendar.” Il setup può essere completo e la pagina dettagli mostra due Connessioni separate così un Admin può revocare solo una.
Stripe è usato per la fatturazione. Un setup parziale comune è: account connesso ma i webhook non sono completati. La scheda mostra: Stato: Needs setup, Progresso: “2 di 3 passi,” con un avviso “I pagamenti potrebbero non sincronizzarsi.” La vista dettagli rende esplicito il passo mancante:
Questo evita la dolorosa situazione “sembra connesso ma niente funziona”.
Una directory di integrazioni di solito si rompe quando un’app cresce da poche integrazioni a dozzine. I problemi raramente sono “grandi problemi tecnici.” Sono piccoli errori di etichettatura e modellazione che confondono le persone ogni giorno.
Un problema comune è mescolare “installed” e “connected.” Installed di solito significa “disponibile nella tua workspace.” Connected significa che esistono credenziali reali e i dati possono fluire. Quando si confondono, gli utenti cliccano su un’integrazione che sembra pronta e trovano un vicolo cieco.
Un altro errore è inventare troppi stati. Si parte da un badge semplice, poi si aggiungono casi limite: pending, verifying, partial, paused, degraded, blocked, expiring e altro. Col tempo quelle etichette si discostano dalla realtà perché nessuno le mantiene coerenti. Mantieni un piccolo set legato a controlli che puoi davvero eseguire.
Permessi nascosti causano problemi. Qualcuno connette un account e poi scopre che l’integrazione aveva accessi più ampi del previsto. Rendi gli scope evidenti prima del passo finale “Connect” e mostrali di nuovo nella pagina dettagli così gli admin possono auditarli.
Molte app necessitano di connessioni multiple: due workspace Slack, diversi account Stripe o un account Google condiviso più account personali. Se vincoli “una integrazione = una connessione”, finirai con brutte scorciatoie.
Pianifica per:
Mantieni la vista lista leggera. Se la riempi di log, mappature di campi e descrizioni lunghe, la scansione rallenta. Usa la lista per nome, breve scopo e progresso setup. Metti storia e impostazioni avanzate nella pagina dettagli.
Una directory di integrazioni scalabile si riduce a un modello semplice e a un’interfaccia onesta. Se gli utenti possono rispondere a tre domande rapidamente, il sistema sembra prevedibile: cosa è connesso, cosa è rotto e cosa devo fare dopo?
Checklist prima del rilascio:
Passo successivo: scegli tre integrazioni che conosci bene e modellale end to end: uno strumento di chat (OAuth), una connessione tipo Google (OAuth con scopes) e uno strumento di pagamenti (API key più webhook). Se il tuo modello esprime tutti e tre senza eccezioni, di solito scalerà a 30.
Trattala come un pannello di controllo, non una pagina marketing. Ogni scheda deve mostrare rapidamente a cosa serve l’integrazione, se sta funzionando ora e quale singola azione successiva dovrebbe compiere l’utente. Se gli utenti devono cliccare solo per capire “è connessa?”, la directory sembrerà inaffidabile man mano che cresce.
Una regola semplice: una scheda deve rispondere “cos’è”, “è sana” e “cosa fare adesso”. Di solito significa nome e una riga descrittiva, uno stato con un ultimo timestamp (ultimo sync o controllo) e un pulsante primario che cambia in base allo stato. Tieni tutto il resto dietro “Manage” per mantenere la scansione veloce.
Per separare ciò che offri da ciò che una workspace ha abilitato e quali credenziali esistono. Usa un'Integrazione globale (voce catalogo), un'Installazione (abilitata in una workspace) e una Connessione (vero account OAuth, API key o webhook). Questo evita il caos comune in cui “installato” e “connesso” si confondono e gli utenti non capiscono cosa è reale.
Molte squadre hanno bisogno di più account esterni per lo stesso provider: calendari diversi, più account Stripe, o più workspace Slack. Modellare più Connessioni sotto una stessa Installazione mantiene la directory pulita e permette agli amministratori di gestire singoli account nella pagina dettagli.
Usa un piccolo insieme di etichette che puoi mantenere coerenti, ad esempio Not set up, In progress, Connected, Needs attention e Disabled. Poi deriva quelle etichette da fatti che puoi controllare: validità token, passi di setup richiesti completati e ultimo sync riuscito. Eviti così badge obsoleti che restano rossi anche dopo la risoluzione.
Fai del progresso una breve checklist di passi obbligatori e passi opzionali che non bloccano il completamento. Memorizza le definizioni dei passi per integrazione e i risultati dei passi per installazione, così l’interfaccia può mostrare per esempio “2 di 3 passi obbligatori completati”. L’utente deve sempre vedere il prossimo passo obbligatorio mancante senza cercare.
Parti da una regola di ruoli semplice valida ovunque, poi aggiungi controlli extra solo per integrazioni sensibili. Per molti prodotti: Admins possono configurare, Managers possono configurare la maggior parte degli strumenti, e Members possono usare gli strumenti abilitati ma non connettere o modificare. Per pagamenti o payroll, aggiungi una singola flag “billing/payments admin” invece di inventare nuovi ruoli.
Conserva la configurazione visibile all’utente come normali dati, ma salva segreti come refresh token e API key in uno store di segreti o campi cifrati con accesso ristretto. Non mettere nei log segreti grezzi, codici di autorizzazione o payload webhook; registra invece riferimenti sicuri come connection_id e metadati utili. Questo riduce il rischio e facilita compliance e support.
Mostra un messaggio che spiega cosa è successo, cosa l’utente dovrebbe fare e cosa farà il sistema automaticamente. I retry dovrebbero essere silenziosi e limitati a problemi che l’utente non può risolvere (outage temporanei, limitazioni). Per auth scaduta o permessi mancanti, interrompi i retry e rendi “Reconnect” o “Fix permissions” l’azione principale.
Mantieni la ricerca semplice: nome del provider prima, poi categoria. Aggiungi filtri che riflettano l’intento reale, come Connected, Needs attention e Not set up, così le persone trovano i problemi rapidamente. Se usi Koder.ai, definisci prima i campi del catalogo, le regole di stato e i passi di setup in Planning Mode così l’interfaccia generata resta coerente man mano che aggiungi integrazioni.