Integrazioni e API

In Integrazioni e API colleghi la community ad altri sistemi: "il tuo CRM, un'automazione o uno script chiamano l'API con una tua chiave." La chiave sostituisce il login nelle chiamate all'API, e fa solo ciò che selezioni.

Ci sono tre viste, nel selettore in alto (chi vede solo le chiavi non vede il selettore):

• Chiavi API: il tuo sistema chiama Memberfy. Il team sempre; i membri, se il proprietario lo consente.
• Webhook: Memberfy avvisa il tuo sistema quando qualcuno entra, acquista, si abbona, si iscrive a un evento o completa un corso. Proprietario e amministratore.
• Integrazioni: app pronte, fatte da Memberfy (Discord, Slack, Telegram, RD Station, HubSpot e le scorciatoie per Zapier, Make e n8n). Proprietario e amministratore.

#Dove si trova

Chiavi API per i membri. In Impostazioni › Integrazioni e API, il proprietario decide con I membri possono creare chiavi API, disattivato per impostazione predefinita in tutte le community, comprese quelle esistenti: chi non fa parte del team non vede più le proprie chiavi, e quelle che ha smettono di funzionare (non vengono eliminate). Riattivandolo, quelle chiavi tornano com'erano. L'admin vede l'opzione bloccata ("Solo l'owner della community può modificare questa opzione."), e il team (proprietario, admin, moderatore e finanza) può sempre creare le proprie chiavi. Con l'opzione disattivata, un membro che apre Chiavi API vede "Le chiavi API non sono disponibili per i membri".

Le chiavi non vanno mai oltre ciò che il tuo ruolo già consente, quindi consentirle ai membri non apre nulla di nuovo: un membro può, per esempio, portare le proprie prenotazioni nel suo calendario.

#Come funziona

#La chiave è tua

Ogni chiave appartiene a te, in questa community, e agisce a tuo nome: ciò che crea risulta creato da te. Il permesso di ogni chiamata è ciò che la chiave ha selezionato e, allo stesso tempo, ciò che il tuo ruolo consente oggi:

• Selezionare un modulo a cui non accedi non sblocca nulla ("La chiave non va mai oltre ciò che il tuo ruolo consente: selezionare un modulo non dà un accesso che non hai.").
• Se il tuo ruolo si riduce, la chiave si riduce con lui.
• Se esci o vieni rimosso dalla community, la chiave si ferma (Ferma).
• Puoi avere fino a 5 chiavi attive.

#Moduli e livelli

La matrice ha una riga per ciascuno dei 33 moduli della community e tre colonne, indipendenti:

Ogni colonna ha seleziona tutto. Senza nulla selezionato, la chiave non fa niente: il valore predefinito è zero, e ogni modulo va sbloccato di proposito. Le colonne non si sommano: una chiave con solo Eliminare e azioni distruttive in un modulo non legge né modifica in quel modulo.

I moduli: Community e spazi, Membri, Feed, Sondaggi, Contenuti, Eventi, Corsi, Certificati, Galleria, File caricati, Call4papers, Annunci, Download, Negozio e prodotti, Vendite e abbonamenti, Finanze (lettura), Report e log, Campagne, Questionari, Upvote, Canali, Gamification, Moderazione, Prenotazioni, Appuntamenti, Networking, Automazioni, Presenze, Visitatori, Pacchi, Assistenza, Aziende e Le mie preferenze.

Automazioni è solo in lettura con chiave: Leggere elenca e consulta i workflow, le versioni, lo storico delle esecuzioni e le consegne; creare, modificare, attivare, mettere in pausa, eseguire, testare, annullare, approvare e svuotare rifiutano la chiave (403 API_KEY_BLOCKED) e restano solo nell'app e nell'assistente IA.

#Cosa richiede "Eliminare e azioni distruttive"

Oltre a eliminare, queste azioni richiedono la terza colonna, anche se non sono un'eliminazione:

#Cosa non raggiunge nessuna chiave

Anche con tutto selezionato, la chiave riceve "Questa azione non accetta una chiave API." in:

• Denaro: rimborso, prelievo, dati di incasso, Informazioni commerciali e documenti (KYC), checkout e acquisto, carte salvate, acquisto di componenti aggiuntivi (da parte del membro o del team), cambio di piano, Paga ora e l'offerta di downsell.
• Account: login, password, recupero della password, e-mail e telefono.
• SuperAdmin: le schermate di gestione della piattaforma.
• L'assistente IA: la connessione MCP e la sua autorizzazione.
• Le chiavi stesse: una chiave non crea, modifica né revoca chiavi. Questo si fa solo dalla schermata, con l'accesso effettuato.
• Aree private: Messaggi, notifiche, le notifiche nel browser e sul cellulare (dispositivi e preferenze), Feedback, piani di sviluppo, Riconoscimento, timbrature e Migliora con l'IA.
• Segreti di automazioni e integrazioni: la cassaforte dei segreti di terzi, gli indirizzi di ingresso dei trigger webhook delle automazioni e gli hook dei workflow.
• Agire come un altro membro (l'intestazione X-MemberId).

Il resto segue le regole di sempre: ciò che il tuo ruolo non può fare sullo schermo, non può farlo nemmeno la chiave.

#Passo per passo: creare una chiave

Ruolo: qualsiasi.

1. Apri Integrazioni e API (vedi Dove si trova) e clicca su Nuova chiave.
2. Dai un Nome ("Es.: CRM, n8n, agenda").
3. Scadenza (facoltativa): una data in cui la chiave si ferma da sola. "Se vuoto, la chiave vale finché non viene revocata."
4. In Cosa può fare la chiave, seleziona solo i moduli e le colonne di cui l'integrazione ha bisogno.
5. IP consentiti (facoltativi): uno per riga, IPv4, IPv6 o intervallo CIDR, fino a 20. "Se vuoto, la chiave accetta chiamate da qualsiasi IP."
6. Clicca su Crea chiave.
7. Copia la chiave e conservala in un gestore di segreti. Clicca su L'ho copiata.

"È l'unica volta in cui la chiave viene mostrata. Non sarà mostrata di nuovo; se la perdi, revocala e creane un'altra." In seguito, l'elenco mostra solo l'inizio della chiave (mfk_7Hq2Lx9a…), che serve a riconoscerla.

La schermata mostra anche le intestazioni da inviare in ogni chiamata: X-Api-Key con la chiave e X-CommunityId con la community. Vedi Autenticazione › Chiave API.

#Gestire le chiavi

Clicca su una chiave dell'elenco per aprirne il dettaglio: Inizio della chiave, Proprietario, Creata il, Scadenza, Ultimo utilizzo e Cosa può fare la chiave.

• Nome e IP consentiti: il proprietario rinomina la chiave e cambia gli IP in qualsiasi momento, senza ricrearla. Il dettaglio mostra l'Ultimo IP rifiutato e quando.
• Moduli: non si modificano. "Per cambiarli, crea un'altra chiave e revoca questa."
• Utilizzo: le chiamate fatte con la chiave nel mese corrente e nei 6 precedenti.
• Revoca chiave: la chiave smette di funzionare alla prossima chiamata, e non si può annullare. Lo storico di utilizzo e le voci nei Log restano.

#Proprietario e admin: tutte le chiavi

Proprietario e admin passano da Le mie chiavi a Tutte della community. In Tutte della community compaiono le chiavi di tutti, con il proprietario, i moduli, l'ultimo utilizzo e lo stato (mai il segreto), e possono revocare qualsiasi chiave. Rinominare e cambiare gli IP resta solo al proprietario della chiave.

#Il blocco Utilizzo

Sotto le chiavi, proprietario e admin vedono Utilizzo: "Chiamate all'API fatte con chiave e webhook consegnati, per mese (UTC)." Sono il mese corrente e i 6 precedenti; apri un mese per vedere le chiamate per chiave e per proprietario.

Contano le chiamate fatte con una chiave valida. Non contano quelle rifiutate prima di arrivare alla rotta: chiave non valida, revocata o scaduta, azione che non accetta chiavi, IP fuori elenco e chiamata oltre il limite al minuto. Webhook consegnati conta ogni evento consegnato con successo a un webhook; il test (Invia test) non conta.

#Il tetto di Memberfy

Il team di Memberfy (SuperAdmin) vede l'utilizzo di ogni community nel suo dettaglio, nella scheda Integrazioni e API, e può salvare un Tetto di chiamate al mese, un Tetto di webhook al mese e il Modello previsto (pacchetto di richieste o canone mensile fisso). Per ora questo "viene solo salvato: nulla viene bloccato o addebitato, e la community non vede il tetto". Superare il tetto mostra solo l'avviso "Sopra il tetto questo mese." a Memberfy; la community continua a usare l'API normalmente.

#Webhook

Ruolo: proprietario e amministratore.

Un webhook avvisa un altro sistema nel momento in cui succede qualcosa nella community: "Avvisa un altro sistema nel momento in cui succede qualcosa nella community." Memberfy invia un POST firmato all'URL che registri, e il tuo CRM, Zapier, Make, n8n o uno script fanno il resto. Chi scrive il codice che lo riceve trova il formato, la firma e i nuovi tentativi in Webhook per chi integra.

#Gli eventi

Sono 97 eventi in 27 famiglie (i due di livelli e punti, member.level_changed e member.points_changed). Per argomento:

Seleziona l'intera famiglia per ricevere anche gli eventi che vi entreranno in seguito, oppure sceglili uno per uno. L'elenco completo è in Webhook per chi integra, e cosa porta ogni evento è in Eventi dei webhook. Anche un membro importato da un foglio di calcolo genera member.joined, con source: "import".

#Passo per passo: creare un webhook

1. In Integrazioni e API, scegli Webhook nel selettore in alto e clicca su Nuovo webhook.
2. URL di destinazione: "Solo https, su un indirizzo pubblico." Zapier, Make e n8n ti danno questo URL quando crei un trigger webhook.
3. Descrizione (facoltativa): "Es.: CRM, n8n, foglio di calcolo".
4. Eventi: seleziona le famiglie o gli eventi.
5. Invia da IP fissi (facoltativo): per destinazioni che accettano solo indirizzi noti. Le consegne partono da due IP, che l'opzione mostra; vedi IP fissi.
6. Leggi l'avviso: "Gli eventi portano alla destinazione dati personali dei membri, come nome, e-mail e telefono. Usa solo un indirizzo di cui ti fidi."
7. Clicca su Crea webhook, copia il segreto (whsec_…) e salvalo nel sistema di destinazione.

"È l'unica volta in cui il segreto viene mostrato. Copialo ora; se lo perdi, ruotalo per generarne un altro." Il segreto serve alla destinazione per verificare che la consegna arrivi davvero da Memberfy.

La community può avere fino a 10 webhook; l'elenco mostra quanti ne esistono già ("3 di 10 webhook della community."). Al limite, eliminane uno per crearne un altro.

#Gestire un webhook

L'elenco mostra ogni webhook con l'URL (mascherato al centro), gli eventi, lo stato e l'ultima consegna. Clicca su uno per aprire il dettaglio: URL, Eventi, IP fissi, data di creazione, Ultima consegna riuscita e, quando ci sono, Errori consecutivi.

Le azioni del dettaglio:

• Invia test: invia ora un evento di test (ping) e mostra la risposta della destinazione ("Test consegnato: HTTP 200 in 180 ms."). Non viene ritentato e non conta nell'utilizzo.
• Modifica: cambia l'URL, la descrizione, gli eventi e l'opzione Invia da IP fissi, senza cambiare il segreto (vedi Modificare un webhook).
• Ruota segreto: genera un nuovo segreto, mostrato una volta. "Il segreto attuale smette subito di valere": aggiorna subito la destinazione.
• Disattiva: le consegne si fermano subito e i tentativi in attesa vengono annullati. Ciò che succede mentre è disattivato non viene inviato dopo.
• Riattiva: "Riattivare invia prima un test: il webhook torna attivo solo se la destinazione risponde con successo."
• Elimina: il webhook smette di ricevere eventi, i tentativi in attesa vengono annullati e non si può annullare.

Ruotare, disattivare ed eliminare chiedono conferma.

#Modificare un webhook

Nel dettaglio, clicca su Modifica: "Cambia l'URL, la descrizione, gli eventi o gli IP fissi. Il segreto resta lo stesso." Regola e clicca su Salva modifiche.

• "Le consegne già in corso continuano verso la destinazione precedente; solo i nuovi eventi usano la nuova configurazione." Nuovi tentativi e reinvii di una consegna vecchia mantengono l'URL e l'opzione degli IP fissi con cui è stata creata.
• Cambiare l'URL azzera gli errori consecutivi, perché è un'altra destinazione. Il nuovo URL passa lo stesso controllo della creazione.
• Modificare non riattiva. Un webhook Disattivato o Disattivato per errori resta disattivato dopo il salvataggio ("Modifiche salvate. Modificare non riattiva un webhook disattivato."); usa Riattiva, che invia prima un test.
• La Cronologia delle modifiche registra ogni modifica con il prima e il dopo di ogni campo (URL mascherati).

#Consegne

La sezione Consegne del dettaglio elenca ogni invio: l'evento, lo stato (In attesa, Consegnata, Non riuscita, Annullata), il numero di tentativi e la risposta. Filtra per stato e per evento (Tutti gli eventi, oppure Test (ping)).

Apri una consegna per vedere l'identificativo (webhook-id), il Corpo inviato e ogni tentativo, con lo stato HTTP e il tempo ("HTTP 500 in 312 ms"), e quando sarà il prossimo. Reinvia invia di nuovo la consegna, con lo stesso identificativo, in una nuova serie di tentativi; una consegna ancora in corso non si può reinviare.

Quando la destinazione fallisce, Memberfy riprova dopo 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. Se la destinazione risponde 410, o resta 72 ore senza nessuna consegna riuscita, il webhook diventa Disattivato per errori, e proprietario e amministratori ricevono un'e-mail. Controlla la destinazione e clicca su Riattiva. I dettagli sono in Webhook › Nuovi tentativi.

Le consegne restano salvate per 30 giorni.

#Cronologia delle modifiche

Sotto l'elenco, la Cronologia delle modifiche mostra "Chi ha creato, modificato, testato, disattivato, riattivato, ruotato o eliminato un webhook o un'integrazione, e quando", compreso il Sistema quando Memberfy disattiva un webhook per errori ("Disattivato automaticamente per errori"). Il dettaglio di ogni webhook ha la scheda Modifiche, solo con le sue. La cronologia resta salvata per 30 giorni.

#Esempi

Zapier avvisa il team di ogni acquisto. Giulia, proprietaria, crea in Zapier un trigger Webhooks by Zapier, copia l'URL e crea in Memberfy il webhook Zapier vendite con la famiglia Acquisti. Clicca su Invia test, Zapier riceve il ping, e da lì ogni acquisto completato diventa un messaggio nel canale del team, con il nome e l'e-mail di chi ha acquistato.

Il CRM che rifiuta IP sconosciuti. Il firewall del CRM accetta solo indirizzi consentiti. Rafael crea il webhook con Invia da IP fissi, consente i due IP fissi nel CRM e invia un test. Quando il CRM resta giù per un fine settimana, le consegne tornano da sole con i nuovi tentativi; quelle che hanno esaurito i tentativi le reinvia dalla sezione Consegne.

Le prenotazioni del membro nel suo calendario. Carla, membro di un coworking, crea la chiave Agenda con Leggere in Prenotazioni e nient'altro. Il suo script legge le sue prenotazioni e costruisce il calendario. Se lo script prova ad annullare una prenotazione, l'API rifiuta: manca Eliminare e azioni distruttive in Prenotazioni.

Il CRM del team vendite. Rafael, admin, crea la chiave CRM con Leggere in Membri e in Vendite e abbonamenti, e gli IP del server del CRM. Il CRM scarica i nuovi abbonati ogni ora. Rimborsare dal CRM non funziona, nemmeno con tutto selezionato: il denaro si gestisce solo dalla schermata.

L'automazione che pubblica nel Feed. L'n8n della community usa una chiave con Creare e modificare in Feed. Quando la chiave finisce in uno screenshot, il proprietario apre Tutte della community, revoca la chiave e la chiamata successiva di n8n viene già rifiutata. Il proprietario della chiave ne crea un'altra.

#Domande frequenti

Perché la chiave riceve "non ha il permesso" in un modulo che ho selezionato? Due cause: la colonna selezionata non è quella dell'azione (annullare richiede Eliminare e azioni distruttive, non Creare e modificare), oppure il tuo ruolo non può farlo nemmeno sullo schermo. La chiave non va mai oltre il tuo ruolo.

Ho perso la chiave. Posso vederla di nuovo? No. Revocala e creane un'altra.

Quante chiamate posso fare? Fino a 120 al minuto, sommando tutte le tue chiavi in questa community. Oltre, l'API chiede di aspettare qualche secondo. Vedi Autenticazione › Limite di chiamate.

Posso creare o revocare una chiave dall'assistente IA? No. L'assistente elenca le chiavi (le tue e, per proprietario e admin, quelle della community), ma creare, modificare e revocare si fa solo dalla schermata. Vedi list_integrations.

Dove vedo cosa ha fatto una chiave? Ogni chiave creata, rinominata, con IP cambiati o revocata, e ogni scrittura fatta con una chiave, viene registrata "tramite la chiave {nome}". Vedi Log › Chiavi API.

Una chiave di una community funziona in un'altra? No. La chiave vale solo nella community in cui è stata creata.

Perché non vedo Webhook nel selettore? È solo del proprietario e degli amministratori. Gli altri ruoli vedono solo le proprie chiavi.

Il webhook è Disattivato per errori. Perdo gli eventi? Quelli avvenuti mentre era disattivato non vengono inviati. Riattivandolo, i successivi tornano ad arrivare. Se la destinazione ha risposto 410, ha chiesto lei di fermarsi: controlla l'URL prima di riattivarlo.

La destinazione ha ricevuto lo stesso evento due volte. Può succedere (una risposta persa, un reinvio). La destinazione deve ignorare il doppione tramite l'intestazione webhook-id. Vedi Webhook › Rispondere ed elaborare.

Integrazioni pronte (Discord, Slack, Telegram)? Disponibili, in Integrazioni: Discord, Slack, Telegram, RD Station e HubSpot, più le scorciatoie per Zapier, Make e n8n. Vedi Integrazioni pronte.

#Tramite l'assistente e l'API

• Tramite l'assistente IA: list_integrations ("Quali chiavi API ho?"; proprietario e amministratore vedono anche i webhook, "Qualche webhook sta fallendo?", e, con type: apps, le integrazioni pronte, sempre solo lettura), list_logs con type: apiKeys e list_activity_logs con source: apiKeys ("Cosa ha fatto la chiave di n8n questa settimana?").
• Webhook tramite l'API: vedi Webhook › Gestire tramite API; il formato, la firma e gli eventi in Webhook ed Eventi dei webhook.
• Tramite l'API: le rotte /api/integrations/api-keys (elencare, creare, vedere, rinominare e cambiare IP, revocare, utilizzo) funzionano solo con il login sullo schermo, mai con una chiave. Vedi Autenticazione › Chiave API e la reference.

#Correlati

• Integrazioni pronte
• Webhook per chi integra
• IP fissi
• Autenticazione
• Risposte ed errori
• Ruoli e permessi
• Log