# Chiavi di licenza e prodotti digitali: documentazione DataFirefly License Keys

> Installazione Installa il modulo da Moduli > Gestione moduli > Carica un modulo con il file ZIP, oppure copia la cartella dflicensekeys nella directory /modules/ del negozio e clicca su…

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

## Installazione

Installa il modulo da **Moduli > Gestione moduli > Carica un modulo** con il file ZIP, oppure copia la cartella `dflicensekeys` nella directory `/modules/` del negozio e clicca su Installa. È richiesta l'estensione PHP `openssl`.

All'installazione il modulo crea le sue tabelle, registra i suoi hook e aggiunge il menu **Catalogo > Chiavi di licenza**. Genera inoltre un segreto di cifratura proprio del negozio.

Le chiavi sono cifrate con una chiave che combina la chiave cookie di PrestaShop (file `app/config/parameters.php`) e questo segreto. Quando migri o copi il negozio, conserva questo file dei parametri: senza di esso le chiavi diventano illeggibili. Un banner rosso ti avvisa se succede.

La disinstallazione conserva chiavi, consegne e segreto, così un reset del modulo non svuota le tue scorte. Attiva **Elimina tutte le chiavi, consegne e file alla disinstallazione** solo se vuoi cancellare tutto.

## Impostazioni del modulo

### Consegna

- **Consegna quando l'ordine passa a**: gli stati contrassegnati come pagati (Pagamento accettato, Pagamento remoto accettato, Spedito, Consegnato…) sono selezionati all'installazione. Il passaggio a uno di essi avvia la consegna. L'elaborazione è idempotente: ripassare per uno di questi stati non invia nuove chiavi.
- **Mostra l'avviso di consegna immediata nelle pagine prodotto**: piccolo riquadro sotto il prezzo dei prodotti digitali.
- **Invia una copia delle e-mail di consegna all'indirizzo di avviso**: copia nascosta al primo indirizzo di avviso.

### Annullamenti e rimborsi

Con la revoca automatica attiva, un ordine che passa ad Annullato o Rimborsato (stati predefiniti) vede le sue chiavi revocate e i download bloccati. Le chiavi revocate non tornano mai da sole in magazzino.

### Scorte di chiavi

- **Sincronizza la quantità del prodotto con le chiavi disponibili**: la quantità PrestaShop diventa il numero di chiavi davvero libere, cioè le disponibili meno quelle riservate da ordini non ancora consegnati (un bonifico in attesa, ad esempio) e meno le chiavi mancanti degli ordini in attesa. Con più chiavi per unità, la quantità viene divisa di conseguenza.
- **Soglia di avviso scorte basse** (5 predefinito) e **Indirizzo/i e-mail di avviso**: un avviso parte quando le chiavi disponibili scendono a questa soglia o un ordine attende chiavi, al massimo una volta al giorno per prodotto.

### Valori predefiniti dei nuovi prodotti digitali

**Limite di download** (5 predefinito, 0 = illimitato) e **Validità del link** in giorni (0 = nessuna scadenza), applicati all'attivazione di un prodotto.

### API delle licenze e attivazioni

Vedi la sezione API più sotto. L'opzione **Consenti ai clienti di liberare attivazioni dal loro account** è attiva per impostazione predefinita.

## Configurare un prodotto digitale

Apri la pagina prodotto, scheda **Moduli**, blocco **Consegna digitale e chiavi di licenza**. Il blocco si salva con il suo pulsante **Salva le impostazioni digitali**, indipendente dal modulo prodotto. Finché non clicchi viene mostrato «Modifiche non salvate».

Imposta il prodotto come **Prodotto virtuale** per non chiedere la spedizione al pagamento. Il blocco te lo ricorda se non è così.

### Chiavi di licenza

- **Origine delle chiavi**: solo scorte importate; scorte importate, poi generazione automatica quando sono esaurite; sempre generate automaticamente.
- **Modello di chiave**: usato dal generatore. `X` = lettera o cifra, `A` = lettera, `9` = cifra, gli altri caratteri restano invariati. Almeno 8 caratteri casuali, massimo 128. I caratteri ambigui (0, O, 1, I) non vengono mai estratti.
- **Validità della licenza (giorni)**: 0 = licenza a vita. La data di fine viene calcolata alla consegna di ogni chiave.
- **Attivazioni massime per chiave**: 0 = illimitato. Controllato dall'API delle licenze.
- **Chiavi per unità ordinata**: 5 per un pacchetto da 5 licenze, ad esempio.
- **Soglia di avviso scorte basse**: lascia vuoto per usare l'impostazione globale.
- **Gestisci scorte di chiavi separate per ogni combinazione**: utile per «1 anno» e «3 anni», o «Windows» e «Mac».

Con la generazione automatica le scorte non si esauriscono mai: la quantità del prodotto non viene più sincronizzata. Imposta una quantità elevata o consenti gli ordini senza scorte.

### File scaricabile

Carica il file (installer, PDF, archivio). Viene salvato nella cartella `/download/` di PrestaShop con un nome casuale e non è mai raggiungibile direttamente. Imposta il **limite di download per riga d'ordine** e la **validità del link**. Sostituire il file vale anche per i clienti già serviti.

### Istruzioni di attivazione

Testo facoltativo per lingua, mostrato con le chiavi nell'e-mail e nell'account cliente. Un punto verde indica le lingue compilate.

## Importare e generare chiavi

Dalla pagina prodotto (blocco **Aggiungi chiavi alle scorte**) oppure da **Catalogo > Chiavi di licenza > Importa chiavi**:

- Incolla le chiavi, una per riga, oppure scegli un file TXT (una chiave per riga) o CSV (chiavi nella prima colonna, separatore `;`, `,` o tabulazione). Spunta **La prima riga del file è un'intestazione** se serve.
- Per un prodotto gestito per combinazione, scegli la combinazione.
- Il **nome del lotto** (fattura del fornitore, ad esempio) permette di ritrovare o esportare queste chiavi in seguito.

I duplicati, già in magazzino per questo prodotto o ripetuti nell'elenco, vengono ignorati. Le chiavi oltre 1000 caratteri vengono rifiutate. Un prodotto non ancora configurato viene attivato con le impostazioni predefinite. Gli ordini in attesa di chiavi vengono consegnati subito dopo l'importazione, dai più vecchi.

Per generare un lotto nelle scorte (fino a 10.000 chiavi), indica numero e modello e clicca su **Genera**. Utile per alimentare il tuo sistema di licenze o un rivenditore tramite l'esportazione CSV.

## Cosa riceve il cliente

- **E-mail di consegna** nella lingua dell'ordine: chiavi, validità, pulsante di download con il numero rimanente, istruzioni di attivazione. Una nuova e-mail parte ogni volta che vengono assegnate nuove chiavi (consegna differita o sostituzione).
- **Pagina di conferma dell'ordine**: le chiavi compaiono subito se il pagamento è immediato, altrimenti un messaggio indica che verranno inviate alla conferma del pagamento.
- **Il mio account > Le mie chiavi di licenza**: tutte le chiavi di tutti gli ordini, con pulsante copia, link di download, validità e dispositivi attivati. Il link appare solo ai clienti che hanno ricevuto almeno una consegna.
- **Dettaglio ordine e tracciamento ospite**: le chiavi e i download dell'ordine. Un cliente ospite riceve il link del tracciamento nell'e-mail.

Un link di download scaduto o esaurito mostra un messaggio chiaro che invita il cliente a contattarti.

## Gestire un ordine nel back office

Nella pagina dell'ordine, il pannello **Chiavi di licenza e download** mostra ogni riga digitale con le sue chiavi, la loro validità, i dispositivi attivati, i download e gli ultimi cinque accessi (data, IP).

- **Consegna ora / riprova**: elabora l'ordine qualunque sia il suo stato. Utile per un ordine fatto prima di attivare il prodotto, o se il dipendente che ha cambiato lo stato non ha il permesso di vedere il modulo (PrestaShop in quel caso non esegue gli hook del modulo).
- **Reinvia l'e-mail**.
- **Sostituisci** una chiave: viene revocata e al cliente parte una nuova chiave.
- **Azzera i download**: rimette il contatore a zero e prolunga il link della validità del prodotto.
- **Azzera le attivazioni** di una chiave.
- **Revoca tutto** e **Riattiva**: la riattivazione ripristina le chiavi revocate con l'ordine, non quelle sostituite a mano.

## Pagina Catalogo > Chiavi di licenza

### Chiavi

La tabella **Scorte per prodotto** indica per ogni prodotto le chiavi disponibili, consegnate e revocate e le righe in attesa. I prodotti con scorte basse sono evidenziati. L'elenco delle chiavi si filtra per prodotto, stato, chiave esatta, riferimento o ID ordine e lotto. Le chiavi sono mascherate per impostazione predefinita (pulsante occhio per mostrarle, pulsante copia). Azioni: revoca e sostituisci, rimetti in magazzino una chiave revocata, elimina una chiave disponibile o revocata, azzera le attivazioni, esportazione CSV delle chiavi filtrate.

### Consegne

Tutte le righe consegnate o in attesa, prima quelle in attesa, filtrabili per stato, riferimento o ID ordine o e-mail del cliente. Azioni: riprova, reinvia, azzera i download.

## API delle licenze

Attiva **Attiva l'API delle licenze** nelle impostazioni. La pagina di configurazione mostra l'indirizzo dell'API, un esempio curl e l'elenco dei codici di errore.

Endpoint: `https://tuo-negozio.it/module/dflicensekeys/api` (POST o GET). Parametri:

- `action`: `validate`, `activate` o `deactivate`.
- `license_key`: la chiave inserita dal cliente.
- `instance`: identificativo univoco del dispositivo, del dominio o dell'installazione, obbligatorio per activate e deactivate.
- `label`: nome leggibile facoltativo mostrato al cliente («PC dell'ufficio»).
- `product_id`: facoltativo, limita il controllo a un prodotto.
- `secret`: obbligatorio solo se **Richiedi il segreto dell'API** è attivo. Attivalo quando solo il tuo server chiama l'API, non quando il software la chiama dal computer del cliente.

La risposta JSON contiene `success`, `error` e un oggetto `license`: `status` (active, revoked, expired), `product_id`, `product_name`, `purchased_at`, `expires_at`, `max_activations`, `activations`, `activated`.

```
curl -X POST "https://tuo-negozio.it/module/dflicensekeys/api"
  -d action=activate
  -d license_key=ABCD-EFGH-JKLM-NPQR
  -d instance=7f3c9a1e-postazione
  -d label="PC dell'ufficio"
```

Codici di errore: 404 `invalid_license` (chiave sconosciuta o non ancora venduta), 403 `license_revoked` o `license_expired`, 403 `activation_limit_reached`, 400 `missing_instance` o `unknown_action`, 401 `invalid_secret`, 429 `too_many_failed_attempts` (più di 30 errori all'ora dallo stesso IP).

Chiama `activate` al primo inserimento della chiave, poi `validate` con la stessa `instance` all'avvio del software. Un'attivazione già registrata per quel dispositivo non viene mai contata due volte.

## GDPR e hook per sviluppatori

Con il modulo ufficiale psgdpr, l'esportazione dei dati di un cliente include le sue chiavi, le date, i download e i dispositivi attivati. L'eliminazione di un cliente anonimizza consegne e attivazioni e cancella il registro dei download: le chiavi restano valide, perché sono state pagate.

Due hook permettono di collegare un CRM o un server di licenze esterno:

- `actionDfLicenseKeysDelivered`: id_order, id_order_detail, id_customer, id_product, id_product_attribute, new_keys, keys (chiavi in chiaro).
- `actionDfLicenseKeysRevoked`: id_order.

## Risoluzione dei problemi

### Il cliente non ha ricevuto le chiavi

Verifica che lo stato dell'ordine sia in **Consegna quando l'ordine passa a**, poi clicca su **Consegna ora / riprova** nell'ordine. Se il pannello mostra chiavi consegnate, clicca su **Reinvia l'e-mail** e controlla la configurazione e-mail di PrestaShop.

### Gli ordini restano «In attesa di chiavi»

Le scorte del prodotto (o della combinazione) sono vuote. Importa chiavi: gli ordini in attesa partono automaticamente. Verifica che l'opzione per combinazione corrisponda alla combinazione in cui importi.

### Le chiavi appaiono come «[?]» con un banner rosso

La chiave cookie del negozio o l'impostazione `DFLK_SECRET` è cambiata, spesso dopo una migrazione. Ripristina il file `parameters.php` precedente.

### Il link di download indica che il file non è disponibile

Il file è stato tolto dal prodotto o cancellato dalla cartella `/download/`. Caricalo di nuovo dalla scheda Moduli del prodotto.

### La quantità del prodotto è negativa

Ci sono ordini che attendono più chiavi di quante ne contengano le scorte. Importa chiavi e la quantità risale da sola.

## Compatibilità

- PrestaShop da 8.0 a 9.x, lo stesso ZIP copre entrambi i rami, con la vecchia e la nuova pagina prodotto.
- Architettura ModuleAdminController, senza dipendenze Composer, PHP 7.2 o superiore, estensione openssl.
- Interfaccia ed e-mail in francese, inglese, spagnolo, tedesco, italiano, olandese, polacco e portoghese.
