Clés de licence et produits numériques : documentation DataFirefly License Keys

Installation

Installez le module depuis Modules > Gestionnaire de modules > Installer un module avec le fichier ZIP, ou déposez le dossier dflicensekeys dans le répertoire /modules/ de la boutique puis cliquez sur Installer. L’extension PHP openssl est requise.

À l’installation, le module crée ses tables, enregistre ses hooks et ajoute le menu Catalogue > Clés de licence. Il génère aussi un secret de chiffrement propre à la boutique.

La désinstallation conserve les clés, les livraisons et le secret, pour qu’une réinitialisation du module ne vide pas votre stock. Activez l’option Supprimer toutes les clés, livraisons et fichiers à la désinstallation seulement si vous voulez tout effacer.

Réglages du module

Livraison

• Livrer quand la commande passe en : les statuts marqués comme payés (Paiement accepté, Paiement à distance accepté, Expédié, Livré…) sont cochés à l’installation. Un changement de statut vers l’un d’eux déclenche la livraison. Le traitement est idempotent : repasser par un de ces statuts ne renvoie pas de nouvelles clés.
• Afficher la mention de livraison immédiate sur les fiches produits : petit encadré sous le prix des produits numériques.
• Envoyer une copie des e-mails de livraison à l’adresse d’alerte : copie cachée à la première adresse d’alerte.

Annulations et remboursements

Avec la révocation automatique activée, une commande qui passe en Annulé ou Remboursé (statuts par défaut) voit ses clés révoquées et ses téléchargements bloqués. Les clés révoquées ne retournent jamais seules en stock.

Stock de clés

• Synchroniser la quantité du produit avec les clés disponibles : la quantité PrestaShop devient le nombre de clés réellement libres, c’est-à-dire les clés disponibles moins celles réservées par des commandes pas encore livrées (virement en attente, par exemple) et moins les clés manquantes des commandes en attente. Avec plusieurs clés par unité, la quantité est divisée d’autant.
• Seuil d’alerte de stock bas (5 par défaut) et Adresse(s) e-mail d’alerte : une alerte part quand les clés disponibles descendent à ce seuil ou qu’une commande attend des clés, au plus une fois par jour et par produit.

Valeurs par défaut des nouveaux produits numériques

Limite de téléchargements (5 par défaut, 0 = illimité) et Validité du lien en jours (0 = sans expiration), reprises à l’activation d’un produit.

API de licences et activations

Voir la section API plus bas. L’option Permettre aux clients de libérer des activations depuis leur compte est activée par défaut.

Configurer un produit numérique

Ouvrez la fiche produit, onglet Modules, bloc Livraison numérique et clés de licence. Le bloc s’enregistre avec son propre bouton Enregistrer les réglages numériques, indépendamment du formulaire produit. Un message « Modifications non enregistrées » s’affiche tant que vous n’avez pas cliqué.

Passez le produit en type Produit virtuel pour qu’aucune livraison ne soit demandée au paiement. Le bloc vous le rappelle si ce n’est pas le cas.

Clés de licence

• Source des clés : stock importé uniquement ; stock importé puis génération automatique quand il est vide ; toujours générées automatiquement.
• Motif de clé : utilisé par le générateur. X = lettre ou chiffre, A = lettre, 9 = chiffre, les autres caractères sont conservés. Au moins 8 caractères aléatoires, 128 caractères maximum. Les caractères ambigus (0, O, 1, I) ne sont jamais tirés.
• Validité de la licence (jours) : 0 = licence à vie. La date de fin est calculée à la livraison de chaque clé.
• Activations maximum par clé : 0 = illimité. Contrôlé par l’API de licences.
• Clés par unité commandée : 5 pour un pack de 5 licences, par exemple.
• Seuil d’alerte de stock bas : laissez vide pour reprendre le réglage global.
• Gérer un stock de clés distinct pour chaque déclinaison : utile pour « 1 an » et « 3 ans », ou « Windows » et « Mac ».

Fichier téléchargeable

Envoyez le fichier (installeur, PDF, archive). Il est stocké dans le dossier /download/ de PrestaShop sous un nom aléatoire et n’est jamais accessible directement. Réglez la limite de téléchargements par ligne de commande et la validité du lien. Remplacer le fichier profite aussi aux clients déjà servis.

Instructions d’activation

Texte facultatif par langue, affiché avec les clés dans l’e-mail et dans le compte client. Un point vert signale les langues remplies.

Importer et générer des clés

Depuis la fiche produit (bloc Ajouter des clés au stock) ou depuis Catalogue > Clés de licence > Importer des clés :

• Collez les clés, une par ligne, ou choisissez un fichier TXT (une clé par ligne) ou CSV (clés en première colonne, séparateur ;, , ou tabulation). Cochez La première ligne du fichier est un en-tête si besoin.
• Pour un produit géré par déclinaison, choisissez la déclinaison.
• Le libellé du lot (facture fournisseur, par exemple) permet de retrouver ou d’exporter ces clés plus tard.

Les doublons, déjà en stock pour ce produit ou répétés dans la liste, sont ignorés. Les clés de plus de 1000 caractères sont rejetées. Un produit qui n’était pas encore configuré est activé avec les réglages par défaut. Les commandes en attente de clés sont livrées dès la fin de l’import, les plus anciennes d’abord.

Pour générer un lot en stock (jusqu’à 10 000 clés), indiquez le nombre et le motif puis cliquez sur Générer. Pratique pour fournir les clés à votre propre système de licences ou à un revendeur via l’export CSV.

Ce que reçoit le client

• E-mail de livraison dans la langue de la commande : clés, validité, bouton de téléchargement avec le nombre restant, instructions d’activation. Un nouvel e-mail part chaque fois que de nouvelles clés sont attribuées (livraison différée ou remplacement).
• Page de confirmation de commande : les clés s’affichent directement si le paiement est immédiat, sinon un message indique qu’elles seront envoyées à la confirmation du paiement.
• Mon compte > Mes clés de licence : toutes les clés de toutes les commandes, avec bouton copier, liens de téléchargement, validité et appareils activés. Le lien n’apparaît que pour les clients qui ont reçu au moins une livraison.
• Détail de commande et suivi invité : les clés et téléchargements de la commande. Un client invité reçoit le lien du suivi dans l’e-mail.

Un lien de téléchargement expiré ou épuisé affiche un message clair qui invite le client à vous contacter.

Gérer une commande en back-office

Sur la page de la commande, le panneau Clés de licence et téléchargements affiche chaque ligne numérique avec ses clés, leur validité, les appareils activés, les téléchargements et les cinq derniers accès (date, IP).

• Livrer maintenant / réessayer : traite la commande quel que soit son statut. Utile pour une commande passée avant l’activation du produit, ou si l’employé qui a changé le statut n’a pas le droit de voir le module (PrestaShop n’exécute alors pas les hooks du module).
• Renvoyer l’e-mail.
• Remplacer une clé : elle est révoquée et une nouvelle clé part au client.
• Réinitialiser les téléchargements : remet le compteur à zéro et prolonge le lien de la durée de validité du produit.
• Réinitialiser les activations d’une clé.
• Tout révoquer et Réactiver : la réactivation rend les clés révoquées avec la commande, pas celles remplacées à la main.

Page Catalogue > Clés de licence

Clés

Le tableau Stock par produit donne, pour chaque produit, les clés disponibles, livrées, révoquées et les lignes en attente. Les produits en stock bas sont surlignés. La liste des clés se filtre par produit, statut, clé exacte, référence ou ID de commande et lot. Les clés sont masquées par défaut (bouton œil pour les afficher, bouton copier). Actions : révoquer et remplacer, remettre en stock une clé révoquée, supprimer une clé disponible ou révoquée, réinitialiser les activations, export CSV des clés filtrées.

Livraisons

Toutes les lignes livrées ou en attente, les attentes en premier, filtrables par statut, référence, ID de commande ou e-mail client. Actions : réessayer, renvoyer, réinitialiser les téléchargements.

API de licences

Activez Activer l’API de licences dans les réglages. La page de configuration affiche l’adresse de l’API, un exemple curl et la liste des codes d’erreur.

Point d’accès : https://votre-boutique.com/module/dflicensekeys/api (POST ou GET). Paramètres :

• action : validate, activate ou deactivate.
• license_key : la clé saisie par le client.
• instance : identifiant unique de l’appareil, du domaine ou de l’installation, obligatoire pour activate et deactivate.
• label : nom lisible facultatif montré au client (« PC du bureau »).
• product_id : facultatif, limite la vérification à un produit.
• secret : requis seulement si Exiger le secret de l’API est activé. Activez cette option quand seul votre serveur appelle l’API, pas quand le logiciel l’appelle depuis le poste du client.

La réponse JSON contient success, error et un objet license : status (active, revoked, expired), product_id, product_name, purchased_at, expires_at, max_activations, activations, activated.

curl -X POST "https://votre-boutique.com/module/dflicensekeys/api" 
  -d action=activate 
  -d license_key=ABCD-EFGH-JKLM-NPQR 
  -d instance=7f3c9a1e-poste 
  -d label="PC du bureau"

Codes d’erreur : 404 invalid_license (clé inconnue ou pas encore vendue), 403 license_revoked ou license_expired, 403 activation_limit_reached, 400 missing_instance ou unknown_action, 401 invalid_secret, 429 too_many_failed_attempts (plus de 30 échecs par heure depuis la même IP).

RGPD et hooks développeurs

Avec le module officiel psgdpr, l’export des données d’un client inclut ses clés, leurs dates, les téléchargements et les appareils activés. La suppression d’un client anonymise ses livraisons et ses activations et efface le journal de téléchargements : les clés restent valides, puisqu’elles ont été payées.

Deux hooks permettent de brancher un CRM ou un serveur de licences externe :

• actionDfLicenseKeysDelivered : id_order, id_order_detail, id_customer, id_product, id_product_attribute, new_keys, keys (clés en clair).
• actionDfLicenseKeysRevoked : id_order.

Dépannage

Le client n’a pas reçu ses clés

Vérifiez que le statut de la commande figure dans Livrer quand la commande passe en, puis cliquez sur Livrer maintenant / réessayer dans la commande. Si le panneau indique des clés livrées, cliquez sur Renvoyer l’e-mail et vérifiez la configuration e-mail de PrestaShop.

Les commandes restent « En attente de clés »

Le stock du produit (ou de la déclinaison) est vide. Importez des clés : les commandes en attente partent automatiquement. Vérifiez que l’option par déclinaison correspond bien à la déclinaison dans laquelle vous importez.

Les clés s’affichent « [?] » et un bandeau rouge apparaît

La clé cookie de la boutique ou le réglage DFLK_SECRET a changé, souvent après une migration. Restaurez l’ancien fichier parameters.php.

Le lien de téléchargement affiche « fichier temporairement indisponible »

Le fichier a été retiré de la fiche ou supprimé du dossier /download/. Renvoyez-le depuis l’onglet Modules du produit.

La quantité du produit est négative

Des commandes attendent plus de clés que le stock n’en contient. Importez des clés, la quantité remonte d’elle-même.

Compatibilité

• PrestaShop 8.0 à 9.x, le même ZIP couvre les deux branches, ancienne et nouvelle page produit.
• Architecture ModuleAdminController, sans dépendance Composer, PHP 7.2 et plus, extension openssl.
• Interface et e-mails en français, anglais, espagnol, allemand, italien, néerlandais, polonais et portugais.