# Area Membri e Contenuti a Pagamento (dfmembership) — Guida completa

> Presentazione Il modulo Area Membri e Contenuti a Pagamento (dfmembership) trasforma il tuo negozio in una piattaforma di abbonamento: vendi abbonamenti che sbloccano l'accesso a un'area membri e a contenuti…

- Pagina: <https://www.datafirefly.com/it/documentation/dfmembership/>
- Lingua: it
- Aggiornato il: 2026-06-25
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfmembership/index.md), [en](https://www.datafirefly.com/en/documentation/dfmembership/index.md), [es](https://www.datafirefly.com/es/documentation/dfmembership/index.md), [de](https://www.datafirefly.com/de/documentation/dfmembership/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfmembership/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfmembership/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfmembership/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## Presentazione

Il modulo **Area Membri e Contenuti a Pagamento** (`dfmembership`) trasforma il tuo negozio in una piattaforma di abbonamento: vendi **abbonamenti** che sbloccano l'accesso a un'**area membri** e a **contenuti riservati** (articoli, video, file, link), a prezzi di gruppo o a pagine CMS private. Ogni piano è collegato a un **gruppo clienti nativo** di PrestaShop, così il negozio gestisce nativamente la visibilità del catalogo e i prezzi per gruppo; il modulo aggiunge sopra la fatturazione, il paywall, la libreria, la scadenza automatica e la sincronizzazione dei gruppi.

Due modelli di business sono disponibili **fin dalla prima versione** e si scelgono piano per piano: un **accesso a durata limitata** (il cliente paga una volta per N giorni, l'accesso scade automaticamente) e un **abbonamento ricorrente reale** tramite Stripe Billing (rinnovo e disdetta gestiti dai webhook).

## Compatibilità

- PrestaShop dalla 8.0 alla 9.x
- PHP dalla 7.4 alla 8.3
- Mono-negozio e multi-negozio
- 5 lingue: FR, EN, ES, DE, IT
- Tema Classic e temi personalizzati
- Nessuna dipendenza: né Composer né SDK Stripe incorporato (chiamate API in cURL nativo)

## Concetti chiave

### Un piano equivale a un gruppo clienti

Un **piano** rappresenta una formula di abbonamento (ad esempio «Premium» o «Pro annuale»). Ogni piano è **mappato a un gruppo clienti** di PrestaShop: quando un cliente diventa membro, viene aggiunto a quel gruppo; quando il suo abbonamento scade o viene disdetto, ne viene rimosso. Erediti così tutta la meccanica nativa di PrestaShop: **prezzi specifici per gruppo**, **restrizioni dei corrieri**, **visibilità delle categorie** e altro, senza configurazione aggiuntiva nel modulo.

Crea prima i tuoi gruppi clienti in **Clienti > Gruppi**, poi associali ai tuoi piani. Uno stesso gruppo può fare da base sia per i prezzi di gruppo sia per la riserva dei contenuti.

### Le due modalità di fatturazione

- **Durata limitata**: il cliente paga una volta e ottiene l'accesso per la durata del piano (in giorni). Un'attività cron fa scadere gli accessi giunti a termine. Ideale per un pass occasionale, un accesso stagionale o un contenuto a tempo determinato. In caso di rinnovo anticipato, il tempo residuo si somma.
- **Abbonamento Stripe**: un vero abbonamento ricorrente gestito da Stripe Billing. Rinnovo, mancato pagamento e disdetta vengono ricevuti tramite **webhook** e riflessi automaticamente sull'accesso del cliente. Ideale per ricavi ricorrenti (MRR).

## Installazione

1. Nel back-office, apri **Moduli > Gestore dei moduli**.
2. Clicca su **Carica un modulo** e seleziona il file `dfmembership.zip`.
3. A installazione avvenuta, clicca su **Configura**.

All'installazione, il modulo crea le sue tabelle (piani, abbonamenti, contenuti), registra i suoi hook, genera un **token cron** casuale e aggiunge un menu **Membership** in **Vendere**, con tre sotto-schede: **Piani**, **Abbonamenti** e **Contenuti**. Nell'area cliente compare un link **La mia iscrizione**.

## Configurazione generale

La pagina di configurazione del modulo raccoglie le impostazioni globali e i due **URL di integrazione** (webhook Stripe e cron) da riportare nei tuoi strumenti esterni.

### Impostazioni Stripe

- **Chiave segreta Stripe**: la tua chiave `sk_live_…` (o `sk_test_…` in modalità test). Necessaria per la fatturazione ricorrente.
- **Chiave pubblicabile Stripe**: la tua chiave `pk_…`.
- **Segreto di firma dei webhook**: il valore `whsec_…` fornito da Stripe per l'endpoint. Serve a **verificare la firma** di ogni webhook in entrata.

### Contenuti e paywall

- **Pagine CMS protette**: l'elenco degli identificativi delle pagine CMS riservate ai membri, separati da virgole (ad esempio `4,7,9`). I non membri che tentano di accedervi vengono reindirizzati alla libreria.
- **Schema SEO del paywall**: inietta dati strutturati con `isAccessibleForFree` a false sul contenuto riservato, affinché resti indicizzabile da Google senza essere considerato cloaking.
- **Lunghezza del teaser (parole)**: numero di parole mostrate prima del paywall quando non è stato indicato un teaser esplicito su un contenuto.
- **Rigenera il token cron**: sostituisce il token dell'URL cron (utile se è trapelato).

La chiave segreta e il segreto del webhook sono sensibili. Usa le chiavi **di test** finché validi il flusso, poi passa alle chiavi **live** in produzione. Non condividere mai pubblicamente l'URL cron con il suo token.

## Creare un piano

In **Membership > Piani**, aggiungi una formula e compila:

- **Nome, slogan, descrizione** (multilingue): mostrati nella pagina di abbonamento e nel blocco home.
- **Modalità di fatturazione**: «Accesso a durata limitata (cron)» o «Abbonamento ricorrente (Stripe)».
- **Prezzo**: l'importo mostrato al cliente.
- **Durata (giorni)**: la durata dell'accesso in modalità durata limitata.
- **Prova (giorni)**: un periodo di prova opzionale (0 = nessuno). In modalità Stripe, la prova viene trasmessa all'abbonamento Stripe.
- **Stripe Price ID**: l'identificativo `price_…` del prezzo ricorrente creato in Stripe (solo modalità Stripe).
- **Gruppo clienti associato**: il gruppo in cui viene collocato il membro finché il suo accesso è attivo.
- **Posizione** e **Attivo**: ordine di visualizzazione e disponibilità del piano.

## Modalità durata limitata e cron

In modalità durata, l'abbonamento viene creato e poi attivato per la durata del piano; la sua data di fine è calcolata a partire dalla data di attivazione. I piani gratuiti (prezzo zero) sono attivati immediatamente, e un piano con prova apre prima una finestra di prova.

Per chiudere automaticamente gli accessi giunti a termine, pianifica l'**URL cron** mostrato nella configurazione (protetto da un token). Un'esecuzione giornaliera è sufficiente:

```
curl "https://tuo-negozio/index.php?fc=module&module=dfmembership&controller=cron&token=IL_TUO_TOKEN"
```

Il cron porta in stato «scaduto» ogni abbonamento a durata la cui data di fine è superata, poi **risincronizza i gruppi** del cliente interessato. Senza cron, gli accessi non scadono da soli: ricordati di pianificarlo.

## Modalità abbonamento Stripe

In modalità Stripe, il cliente viene reindirizzato a una pagina di pagamento **Stripe Checkout** in modalità abbonamento. Al termine del pagamento, Stripe notifica il tuo negozio tramite webhook e l'accesso viene attivato. L'intero ciclo di vita è poi gestito da Stripe.

### Configurazione

1. In Stripe, crea un **prodotto** e un **prezzo ricorrente** (mensile, annuale…) e copia il suo `price_…` nel piano corrispondente.
2. Inserisci le tue chiavi Stripe e il segreto del webhook nella configurazione del modulo.
3. In Stripe, aggiungi un **endpoint webhook** che punti all'URL mostrato nella configurazione e iscrivilo agli eventi: `checkout.session.completed`, `invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated` e `customer.subscription.deleted`.

### Cosa fanno i webhook

- **checkout.session.completed**: attiva l'abbonamento e memorizza l'identificativo dell'abbonamento Stripe.
- **invoice.paid**: rinnova l'accesso e sposta in avanti la data di fine periodo.
- **invoice.payment_failed**: mantiene l'accesso durante il periodo di sollecito (dunning) gestito da Stripe.
- **customer.subscription.updated**: riflette una disdetta programmata a fine periodo o un cambio di data.
- **customer.subscription.deleted**: chiude definitivamente l'accesso e rimuove il cliente dal suo gruppo.

Ogni webhook è verificato per firma tramite il segreto `whsec_…`. Se la firma non è valida o il segreto è vuoto, la richiesta viene rifiutata. Controlla prima questa impostazione se gli abbonamenti non si attivano.

## Libreria di contenuti e paywall

In **Membership > Contenuti**, crea gli elementi riservati. Ogni contenuto ha:

- **Tipo**: articolo, video, file o link.
- **Titolo, teaser, contenuto** (multilingue). Il **teaser** è l'anteprima pubblica mostrata prima del paywall; se lasciato vuoto, viene generato automaticamente dalle prime parole del contenuto (lunghezza regolabile).
- **URL del media**: l'incorporazione video, il file da scaricare o il link esterno.
- **Piano richiesto**: il piano che dà accesso al contenuto. Il valore «Qualsiasi membro attivo» apre il contenuto a qualsiasi abbonamento in corso.
- **Ritardo di drip (giorni)**: numero di giorni dopo l'inizio dell'abbonamento prima che il contenuto si sblocchi, per distribuire progressivamente una libreria (drip content).

Sul negozio, la **libreria** elenca i contenuti con il loro teaser. Un membro vede il contenuto completo; un visitatore o un non membro vede il teaser e poi un **paywall** che lo invita ad abbonarsi. Il controllo d'accesso combina il piano richiesto e il ritardo di drip.

### Indicizzazione del contenuto riservato

Quando l'opzione di schema SEO è attiva, il modulo aggiunge sul contenuto sbloccato dati strutturati che indicano che si tratta di contenuto a pagamento (campionamento flessibile di Google). Il blocco riservato è contrassegnato da una classe CSS dedicata, il che consente a Google di indicizzare la pagina senza penalizzare la differenza tra ciò che vedono il crawler e il membro.

## Pagine CMS riservate

Per riservare pagine CMS esistenti (una pagina di risorse, un'area privata…), indica i loro identificativi in **Pagine CMS protette**. Un non membro che apre una di queste pagine viene reindirizzato automaticamente alla libreria, dove può scoprire le formule. I membri vi accedono normalmente.

## Area membri

Da **Il mio account > La mia iscrizione**, il cliente ritrova i suoi abbonamenti in corso: piano, stato, modalità di fatturazione, data di rinnovo o di fine. Può **aprire la libreria** e, se necessario, **disdire** un abbonamento. La disdetta avviene **a fine periodo**: l'accesso resta aperto fino al termine già pagato, poi si chiude. In modalità Stripe, la richiesta viene trasmessa a Stripe; in modalità durata, l'accesso semplicemente non viene rinnovato.

## Gestire gli abbonamenti (back-office)

In **Membership > Abbonamenti**, visualizzi tutti gli abbonamenti (cliente, email, piano, stato, modalità, date) con ricerca ed esportazione. La vista di dettaglio permette di **forzare uno stato** (attivo, scaduto, disdetto) quando serve: un gesto commerciale, una regolarizzazione, una controversia. Ogni cambio di stato **risincronizza immediatamente** il gruppo del cliente.

I gruppi vengono risincronizzati anche all'accesso del cliente e alla convalida di un ordine, per garantire che l'accesso rifletta sempre gli abbonamenti realmente attivi.

## Andare oltre

L'architettura di fatturazione è **estensibile**: un nuovo fornitore (ad esempio PayPal ricorrente) si aggiunge implementando l'interfaccia `BillingManagerInterface` della cartella `src/Billing/` e registrandola nella fabbrica `BillingManagerFactory`, senza toccare il resto del modulo. Tra le evoluzioni possibili: teaser generati dall'IA, email di sollecito, abbonamenti regalo, cambio di formula con calcolo proporzionale o una dashboard MRR / tasso di abbandono.

## FAQ e risoluzione dei problemi

### Un cliente ha pagato ma non ha accesso

In modalità Stripe, controlla prima il **segreto del webhook** e che l'endpoint riceva effettivamente gli eventi nella dashboard di Stripe (scheda Webhook). L'attivazione dipende dall'evento `checkout.session.completed`. In modalità durata, verifica che l'abbonamento sia passato allo stato attivo; puoi forzarlo dalla vista di dettaglio.

### Gli accessi non scadono mai

La modalità durata si basa sul cron. Assicurati di aver **pianificato l'URL cron** (giornaliero) con il token corretto. Puoi richiamarlo manualmente per provare: la risposta JSON indica il numero di abbonamenti scaduti.

### Come collego il piano a prezzi ridotti?

Associa il piano a un **gruppo clienti**, poi definisci **prezzi specifici** per quel gruppo nelle tue schede prodotto (o tramite una regola di prezzo del catalogo). Finché il membro è attivo, appartiene al gruppo e beneficia automaticamente di quei prezzi.

### Il contenuto riservato è indicizzabile da Google?

Sì, se l'opzione di schema SEO è attiva: il contenuto a pagamento è segnalato come tale tramite dati strutturati, in linea con le raccomandazioni di Google sul campionamento flessibile. Mantieni l'indicizzazione senza nascondere la natura a pagamento.

### Posso offrire una prova gratuita?

Sì. Indica un numero di giorni di prova nel piano. In modalità durata si apre una finestra di prova; in modalità Stripe, la prova viene trasmessa all'abbonamento Stripe (`trial_period_days`).

### PayPal è supportato?

La versione 1 implementa le modalità durata e Stripe. PayPal ricorrente può essere aggiunto grazie all'interfaccia di fatturazione estensibile, senza riscrivere il modulo.

### È compatibile con PrestaShop 9?

Sì. Il modulo è compatibile con PrestaShop 8 e 9, in multi-negozio e multilingue (FR, EN, ES, DE, IT).