Progettare una directory di integrazioni scalabile da 3 a 30 app

Cosa deve fare una schermata integrazioni (in termini chiari)

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:

• Cos’è? (Nome più breve descrizione)
• Sta funzionando adesso? (Stato chiaro più ultimo controllo o ultimo sync)
• Cosa devo fare dopo? (Connect, continua setup, ri-autentica, gestisci)

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.

Un modello dati semplice: catalog vs installazioni vs connessioni

Il modo più semplice per scalare una directory di integrazioni è separare:

• ciò che offri (il catalogo)
• ciò che ogni workspace ha abilitato (installazioni)
• quali account esterni o credenziali sono in uso (connessioni)

Questo rimane leggibile a 3 integrazioni e funziona anche a 30.

I tre oggetti principali

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:

• Integration: id, key (slack), display_name, category, auth_type (oauth/api_key/webhook), docs_hint (testo breve), 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 (se noto), scopes/permissions_granted, last_success_at, created_at

Config vs segreti (e cosa non deve trapelare)

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

Stati e progresso di setup che gli utenti capiscono

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:

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

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

Permessi e ruoli senza complicare tutto

I permessi per le integrazioni diventano complicati quando tutto è trattato come un singolo interruttore. È più chiaro separare:

• chi può vedere un’integrazione
• chi può configurarla
• chi può usarla giorno per giorno

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:

• View: Admin, Manager, Member
• Configure: Admin, Manager (i Member possono vederla ma non connettere o modificare)
• Use: Chiunque nello workspace una volta abilitata (se non è ristretto)
• Sensitive override: Solo utenti con una specifica flag possono configurare o attivare azioni

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.

Layout UI che funziona anche con 30 integrazioni

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:

• Icona, nome e una descrizione in una riga (mantieni lunghezza consistente)
• Un pillo stato chiaro (Connected, Needs setup, Error, Disabled)
• Un pulsante azione primario
• Un pulsante secondario “Manage” per tutto il resto

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:

• Se “Google” è Connected, l’azione primaria può essere Manage.
• Se “Slack” ha fallito la notte scorsa, mostra Error e rendi Reconnect l’azione primaria.
• Se “Stripe” è a metà, mostra Needs setup e Continue setup.

Gli stati vuoti dovrebbero guidare senza scaricare un manuale:

• Nessuna integrazione installata: suggerisci 2–3 scelte popolari e cosa sbloccano
• Nessun risultato nella ricerca: offri un semplice suggerimento come “prova ‘CRM’ o ‘billing’”
• Primo setup: una frase su permessi e quali dati saranno accessibili

Questo mantiene la pagina calma a 30 integrazioni perché ogni scheda risponde: cos’è, va bene, e cosa faccio ora?

La pagina dettagli: flusso di setup, connessioni e controlli

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 flusso di setup che sembra sicuro

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.

Connessioni e controlli di cui gli utenti non si pentiranno

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.

Passo dopo passo: aggiungere una nuova integrazione end to end

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.

1) Parti dall’entry del catalogo

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

2) Costruisci il metodo di connessione

Scegli il metodo più semplice che si adatta al provider:

1. OAuth quando l’utente deve fare login e approvare accessi (comune per Google, Slack)
2. API key quando l’utente può incollare un token dal provider
3. Webhook quando il provider invia eventi alla tua app

3) Salva le credenziali e crea una record Connection

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.

4) Esegui un controllo iniziale e imposta stato + progresso

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.

5) Cosa mostrare quando fallisce

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.

Errori, retry e una cronologia utile per il support

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.

Regole di retry che non infastidiscono

Retry automatici solo quando l’utente non può risolvere da sé. Una semplice regola è sufficiente:

• Provider down o errore di rete: retry automatico con backoff, conserva ultimo tempo di successo
• Rate limited: pausa, riprova più tardi e mostra “Paused (rate limit)”
• Auth scaduta: interrompi i retry e chiedi all’utente di riconnettere
• Permessi mancanti: interrompi e mostra esattamente quale permesso serve
• Config errata: interrompi e indica l’impostazione da correggere

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

Cronologia che il support può usare

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

Ricerca, filtri e organizzazione della directory

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:

• Connected (funzionante ora)
• Needs attention (errori, token scaduto, permesso mancante)
• Not set up (disponibile ma nessuna install)

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.

Esempio: Slack, Google e Stripe in un’app reale

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:

• Connetti account Stripe (fatto)
• Mappa piani di billing (fatto)
• Aggiungi endpoint webhook (non fatto)

Questo evita la dolorosa situazione “sembra connesso ma niente funziona”.

Errori comuni che rendono le integrazioni difficili da gestire

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.

Non presumere una sola connessione per integrazione

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:

• Connessioni multiple sotto la stessa integrazione
• Una chiara connessione “di default” (se serve)
• Connessioni condivise vs personali
• Un luogo per vedere chi l’ha connessa

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.

Checklist rapida e passi successivi

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:

• Separa il modello: Integration (catalogo) vs Install (abilitato in questa workspace) vs Connection (OAuth token, API key o webhook). Aggiungi Event solo se ti serve cronologia audit/support.
• Deriva lo stato: calcola etichette da controlli (token valido, scopes OK, webhook raggiungibile) e passi di setup completati, così i badge restano accurati.
• Mantieni la vista lista scansionabile: ogni riga mostra nome, un’etichetta chiara e una “prossima azione” (Connect, Continue, Reconnect, Fix permissions).
• Rendi le azioni di ciclo di vita primarie: Connect, Continue setup, Reconnect, Disable e Disconnect devono essere facili da trovare, con conferme brevi.
• Rendi i permessi visibili e auditabili: mostra chi può connettere o disconnettere e registra chi ha cambiato cosa e quando.

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.