# Referral dei membri

> Ogni membro riceve un link di invito; chi entra da quel link conta come invitato, una volta, e il team vede chi ha portato chi. Attivare e disattivare, le regole su quando conta, i punti, i workflow e il report.

Il **referral dei membri** dà a ogni persona della community un proprio link per invitarne altre. Chi entra dal link viene registrato come **invitato** da lei: il team vede chi ha portato chi, la community può dare punti e badge per ogni invito e attivare workflow quando qualcuno invita.

## A cosa serve

| Community | Come lo usa |
|---|---|
| Community che cresce con il passaparola | Attiva il referral e segue chi porta più persone nuove |
| Community con gamification | Dà punti per l'azione **Invitare un membro** e un badge a chi invita 5 persone |
| Programma di ambassador | Un workflow con **Ha invitato qualcuno** manda un DM di ringraziamento e mette la persona nel gruppo *Ambassador* |

## Chi può

| Ruolo | Cosa fa |
|---|---|
| Proprietario e amministratore | Attivano e disattivano il referral; vedono il report e l'**Invitato da** di ogni membro |
| Moderatore | Vede il report e l'**Invitato da** |
| Finanza | Non vede il report né chi ha invitato chi (è un dato personale, fuori dall'area finanziaria) |
| Membro | Prende il proprio link e vede quante persone ha invitato |

## Dove si trova

| Chi | Dove |
|---|---|
| Proprietario e amministratore | **Impostazioni › Accesso e iscrizione**, scheda **Referral**: l'interruttore lo attiva e disattiva, e **Vedi il report degli inviti** apre il report |
| Proprietario, amministratore e moderatore | **Membri › Referral**: ogni persona che ha invitato, con **Membro**, **Inviti** e **Ultimo**, il **Periodo** (**30 giorni**, **90 giorni** o **Tutto**) e **Scarica CSV**. Nella pagina di un altro membro, la scheda **Invitato da** (*"Lo vede solo il team."*) |
| Membro | **Il mio account › Invita** e la propria pagina: la scheda **Consiglia la community**, con il link, **Copia** e quante persone sono entrate da lì. Appare solo con il referral attivo |

Chi apre il link e si iscrive dall'app conta come invitato: l'app conserva il codice per 30 giorni, e il trigger **Ha invitato qualcuno** è nell'editor dei [workflow](/notificacoes/workflows).

## Come funziona

### Attivare

Il referral nasce **disattivato**. Una volta attivo, ogni membro ha un proprio codice, creato la prima volta che chiede il link, e il link è l'indirizzo della community con `?ref=` e il codice (`https://tuacommunity.memberfy.net/?ref=ana7k2`). Disattivato, nessuno ha un link, e un codice ricevuto non conta.

### Quando l'invito conta

L'invito conta **una volta**, quando la persona invitata **diventa membro**, e solo se:

- il referral è attivo nella community in quel momento;
- il codice è di un membro attivo di **questa** community;
- chi entra non è la stessa persona che ha invitato (né per profilo, né per e-mail);
- chi entra **non ha mai avuto un profilo** in questa community;
- il link è stato aperto al massimo **30 giorni** prima.

Il codice **non blocca mai** una registrazione e non apre la community a chi non potrebbe entrare: la registrazione segue le regole di sempre (vedi [Registrazione e accesso](/membros/cadastro-e-entrada)). In una community con approvazione delle iscrizioni, il codice aspetta insieme alla richiesta e conta quando la richiesta viene approvata.

### Cosa succede con un invito

- La persona nuova ha come provenienza **Referral**, che compare nella scheda di crescita della [Dashboard](/membros/dashboard), tra le provenienze dei nuovi membri degli ultimi 7 giorni.
- Chi ha invitato compie l'azione **Invitare un membro** della [gamification](/membros/gamificacao): vale **0 punti** per impostazione predefinita (la community sceglie quanto) e conta per le regole dei badge e i requisiti di livello con quell'azione.
- Parte l'evento **Ha invitato qualcuno**, su chi ha invitato, con il nome di chi è entrato: trigger di [workflow](/notificacoes/workflows) (con la variabile `referred.name`) e [webhook](/api/eventos-de-webhook) `member.referred`.

### Il report

Per il proprietario, l'amministratore e il moderatore: ogni persona che ha invitato, con quanti inviti e la data dell'ultimo, e il totale, in un periodo. Esce anche in CSV. Chi è uscito dalla community resta nel report, segnato come rimosso.

## Esempio

La community attiva il referral e dà 50 punti per **Invitare un membro**. Anna prende il link e lo manda a Bruno, che apre il link, si registra il giorno dopo e diventa membro. Anna guadagna 50 punti, Bruno compare con la provenienza **Referral**, e il workflow con **Ha invitato qualcuno** manda ad Anna: *"Grazie per aver portato Bruno!"*.

## Errori comuni e come risolverli

| Situazione | Cosa fare |
|---|---|
| L'invito non è stato contato | Verifica che il referral fosse attivo, che la persona non abbia mai avuto un profilo nella community e che il link sia stato aperto meno di 30 giorni prima |
| La persona ha invitato se stessa con un'altra registrazione | Non conta: la stessa e-mail o lo stesso profilo viene rifiutato come invito |
| L'invito non ha dato punti | L'azione **Invitare un membro** vale 0 per impostazione predefinita; cambia il valore nelle regole dei punti della [gamification](/membros/gamificacao) |

## Domande frequenti

**La persona invitata sa chi l'ha invitata?**
Non da qui. Chi ha invitato compare solo al team (proprietario, amministratore e moderatore).

**Disattivare cancella gli inviti?**
No. Gli inviti già contati restano; smettono solo di contarne di nuovi.

**Si può invitare qualcuno in una community a pagamento?**
Sì. Il link porta alla community, e la persona entra con le regole di sempre, acquisto compreso. L'invito conta quando diventa membro.

## Nell'API

`GET` e `PUT /api/referrals/settings` (proprietario e amministratore; gli altri ruoli ricevono `403`) attivano e disattivano (`enabled`). `GET /api/referrals/me` (qualsiasi membro) restituisce `enabled`, `code`, `path` (`/?ref=<codice>`) e `count`. `GET /api/referrals/report` (proprietario, amministratore e moderatore; la finanza riceve `403`) porta, per persona, `memberId`, `name`, `avatarUrl`, `removed`, `count` e `lastReferredAt`, con `totals`, paginazione, `from`/`to` e `format=csv`.

Nella registrazione, `POST /api/auth/register` e `POST /api/auth/signup-request` accettano `referralCode` e `referralSeenAt` (quando è stato aperto il link; oltre 30 giorni, ignorato). `GET /api/members/{id}` porta `referredBy` (`memberId`, `name`, `avatarUrl`, `removed`, `referredAt`) nel profilo di un'altra persona, solo per proprietario, amministratore e moderatore, e `source` può essere `REFERRAL`. La scheda di crescita della Dashboard porta `extra.bySource`. Vedi [Referrals](/api/referencia/referrals) nel Riferimento API.

## Con l'assistente (MCP)

Chiedi all'assistente il tuo link (*"qual è il mio link di referral?"*, [`get_my_referral`](/mcp/ferramentas-membros#get-my-referral)), il report (*"chi ha portato più membri nuovi questo mese?"*, [`get_referral_report`](/mcp/ferramentas-membros#get-referral-report), per il proprietario, l'amministratore e il moderatore) o di attivare il referral ([`update_referral_settings`](/mcp/ferramentas-membros#update-referral-settings)). Chi ha invitato un membro compare in [`get_member`](/mcp/ferramentas-membros#get-member).

## Correlati

- [Invitare membri](/membros/convidar-membros)
- [Registrazione e accesso](/membros/cadastro-e-entrada)
- [Gamification](/membros/gamificacao)
- [Workflow](/notificacoes/workflows)
- [Eventi dei webhook](/api/eventos-de-webhook)