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

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

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

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.