Guide du module Gumroad

Connectez votre site Larapen à l’API Gumroad. Importez vos produits Gumroad comme produits de licence, enregistrez chaque vente grâce aux notifications Ping de Gumroad, envoyez sa clé de licence par e-mail à chaque acheteur, et laissez vos clients vérifier leurs clés Gumroad sur votre site.

Cas d’utilisation

Logiciel vendu sur Gumroad

Vous vendez des scripts, des plugins ou des thèmes sur Gumroad et vous gérez votre site de support sur Larapen.

• Importez votre catalogue Gumroad. Chaque nouveau produit devient aussi un produit de licence dans l’add-on Licences.
• Activez le webhook Ping. Chaque nouvelle vente est enregistrée et l’acheteur reçoit une clé de licence par e-mail, même pour les produits qui n’utilisent pas la fonctionnalité de clés de licence de Gumroad.
• Vos applications vérifient ces clés via l’API de licences de l’add-on Licences.

Support réservé aux acheteurs

Vous voulez que seuls les acheteurs Gumroad puissent ouvrir des tickets dans le département de helpdesk d’un produit.

• Dans l’add-on Licences, liez le produit de licence au département de helpdesk.
• Les acheteurs ajoutent leur clé sur Mes licences Gumroad, ou se la voient rattacher automatiquement lorsqu’ils s’inscrivent avec l’adresse e-mail utilisée sur Gumroad.
• Les agents voient les licences Gumroad du client dans la barre latérale du ticket.

Répondre à “Où est ma clé ?”

Un acheteur vous écrit en ne donnant qu’une adresse e-mail ou un reçu Gumroad.

• Ouvrez Gumroad → Vérifier une clé de licence et recherchez par clé de licence, e-mail de l’acheteur, numéro de commande ou identifiant de vente Gumroad.
• Renvoyez la clé depuis le tableau de bord Gumroad (Resend ping) : l’e-mail de la clé est envoyé de nouveau.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• L’add-on Licences, installé et actif. Cet add-on en dépend (1.0.13 ou ultérieur pour cette version, voir Mise à jour).
• Un compte Gumroad et un jeton d’accès (voir Créer un jeton d’accès)
• Facultatif : l’add-on HelpDesk, pour la barre latérale des tickets et le lien de support sur la page front-end
• Facultatif : un worker de file d’attente en fonctionnement, uniquement si vous activez la synchronisation en arrière-plan (voir Paramètres)

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Vérifiez d’abord que l’add-on Licences est actif. Repérez ensuite Intégration Gumroad dans la liste et cliquez sur Activer. Ses migrations et ses permissions sont mises en place automatiquement, et un menu Gumroad apparaît dans la barre latérale d’administration.

Étape 3 : Se connecter à Gumroad

Allez dans Admin → Gumroad → Paramètres, collez votre jeton d’accès et cliquez sur Tester la connexion. En cas de succès, le message affiche le nom de votre compte Gumroad. Voir Configuration.

Étape 4 : Activer la marketplace Gumroad dans Licences

Dans Admin → Licences → Paramètres, activez la marketplace Gumroad (voir Paramètres de l’add-on Licences). Si elle reste désactivée, l’import des produits Gumroad ne crée pas de produits de licence.

Étape 5 : Importer vos produits

Allez dans Admin → Gumroad → Produits et cliquez sur Importer depuis Gumroad (voir Importation des produits).

Étape 6 : Activer le webhook Ping (recommandé)

Dans Gumroad → Paramètres → Ping Gumroad, activez le ping et copiez l’URL de ping. Sur Gumroad, collez-la dans Settings → Advanced → Ping. Voir Webhook Ping.

Code d’achat (clé de licence)

Intégration Gumroad est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence) — distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Intégration Gumroad dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée — acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous — il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Tous les paramètres sont gérés dans Admin → Gumroad → Paramètres (stockés dans la table settings, groupe gumroad). Les valeurs enregistrées remplacent les valeurs par défaut du fichier config/gumroad.php de l’add-on.

La durée de conservation des journaux de ping utilisée par l’action Purger (ping_log_retention_days, 90 jours) est une valeur définie uniquement dans config/gumroad.php.

Créer un jeton d’accès

1. Connectez-vous à Gumroad et ouvrez Settings → Advanced.
2. Dans la section Applications, créez une application (n’importe quel nom, par exemple “Larapen Support Site”, et l’URL de votre site comme URI de redirection).
3. Ouvrez l’application et cliquez sur Generate access token.
4. Copiez le jeton et collez-le dans Admin → Gumroad → Paramètres → Configuration de l’API, puis cliquez sur Tester la connexion.

Paramètres de l’add-on Licences

La marketplace Gumroad se configure dans Admin → Licences → Paramètres. Ces paramètres appartiennent à l’add-on Licences :

Admin : Tableau de bord

Gumroad → Tableau de bord (/admin/gumroad) affiche :

• Un avertissement avec un lien vers les paramètres lorsqu’aucun jeton d’accès n’est défini.
• Des compteurs : produits (total / actifs), clients, licences (total / vérifiées / remboursées), revenu des ventes qui n’ont pas été remboursées, et nombre de liens produit → produit de licence.
• Les licences les plus récentes (produit, e-mail de l’acheteur, date) et les meilleurs produits.
• Des raccourcis vers Vérifier une clé de licence et Paramètres.

Admin : Paramètres

La page des paramètres (Gumroad → Paramètres) comporte les onglets suivants :

Configuration de l’API

• Jeton d’accès : champ masqué avec un bouton afficher/masquer.
• Nom du vendeur : informatif uniquement.
• Bouton Tester la connexion : vérifie le jeton immédiatement, y compris un jeton saisi mais pas encore enregistré, et affiche le nom de votre compte Gumroad lorsqu’il fonctionne.

Dépendances

Indique si l’add-on Licences est actif, avec un avertissement lorsqu’il ne l’est pas.

Options de vérification

• Exiger la correspondance des e-mails : l’e-mail de l’acheteur d’une vente Gumroad doit correspondre à l’e-mail du compte (activé par défaut).

Ping Gumroad

• Interrupteur Activer le point de terminaison Ping.
• URL de ping : champ en lecture seule avec un bouton de copie. Il affiche l’URL complète de la route gumroad.api.ping, par exemple https://yoursite.com/api/gumroad/ping.
• Une note de sécurité et un lien vers le journal des pings.
• Clés de licence créées à partir des ventes : créer une clé lorsque Gumroad n’en fournit aucune, envoyer la clé par e-mail à l’acheteur, copie cachée (les adresses administrateur sont listées à côté du champ), ignorer les ventes de test, format de clé, type de licence et nombre d’activations.

Synchronisation des licences

Cet onglet n’est affiché que lorsque l’add-on Licences est actif.

• Autoriser plusieurs produits de licence par produit : désactivé par défaut, de sorte qu’un produit Gumroad n’est lié qu’à un seul produit de licence et que la fenêtre le remplace lorsque vous en choisissez un autre.
• Exécuter la synchronisation en arrière-plan : envoie la synchronisation Licences → Gumroad dans la file d’attente. N’activez cette option que si un worker de file d’attente tourne (ex. php artisan queue:work sous supervisor). Sans worker, laissez-la désactivée : la synchronisation s’exécute alors pendant la requête.

Admin : Produits

Gumroad → Produits liste votre copie locale du catalogue Gumroad.

Liste des produits

• Recherche par nom, ID de produit Gumroad, permalien personnalisé ou permalien court.
• Filtres : publiés / non publiés, liés / non liés à un produit de licence, avec / sans licences enregistrées.
• Tri : nom (par défaut), ventes, licences, prix (du plus élevé au plus bas / du plus bas au plus élevé), dernière synchronisation.
• Les colonnes comprennent la miniature, le nom avec les produits de licence liés affichés en dessous, le prix, le nombre de ventes, le nombre de licences et le compteur Liens.
• Actions par ligne : voir, Produits de licence liés (voir ci-dessous), supprimer. Vous pouvez aussi sélectionner plusieurs lignes et les supprimer.

Importation des produits

Cliquez sur Importer depuis Gumroad. L’import s’exécute en une seule requête AJAX (POST /admin/gumroad/products/import) :

1. Gumroad renvoie les produits par pages de 10, du plus récent au plus ancien. Le serveur demande toutes les pages jusqu’à la dernière, de sorte que les produits de n’importe quelle ancienneté sont importés. Il s’arrête à 100 pages (1 000 produits) ou si Gumroad renvoie deux fois la même page.
2. Les produits existants (identifiés par leur ID de produit Gumroad) sont actualisés. Les nouveaux produits sont créés.
3. Pour chaque nouveau produit, lorsque l’add-on Licences est actif et que sa marketplace Gumroad est activée, un produit de licence est créé (ou le produit de licence déjà référencé sous les mêmes identifiants Gumroad est réutilisé) et le produit Gumroad est référencé sous lui.
4. Les permaliens courts sont ensuite lus depuis votre boutique publique Gumroad (voir Identifiants Gumroad). Si cette étape échoue, l’import réussit quand même et un avertissement est écrit dans le journal.
5. Le résultat indique combien de produits ont été importés, actualisés et traités au total.

Identifiants Gumroad

Un produit Gumroad possède trois identifiants :

Les trois peuvent être recherchés dans la liste des produits, apparaissent sur la page du produit et dans la fenêtre des liens, et sont copiés dans la fiche Gumroad du produit de licence. L’API Licences peut ainsi identifier le produit à partir de n’importe lequel d’entre eux.

La commande gumroad:permalinks

# List every imported product: ID, short permalink, custom permalink, name
php artisan gumroad:permalinks

# Find the products matching one or more identifiers (ID, short or custom permalink)
php artisan gumroad:permalinks abcde my-plugin-pro

# Read the short permalinks from the storefront first
php artisan gumroad:permalinks --sync
php artisan gumroad:permalinks --sync --storefront=https://seller.gumroad.com

# JSON output
php artisan gumroad:permalinks --json

La commande se termine avec un code de sortie non nul si un identifiant ne correspond à aucun produit importé. Elle vous aide à renseigner l’ID Gumroad dans le manifeste d’un add-on ou d’un thème (marketplace_item_ids.gumroad).

Détail du produit & ventes

La page du produit (Gumroad → Produits → {produit}) affiche :

• Informations du produit : identifiants, prix, devise, nombre de ventes, état de publication, dernière synchronisation, et les produits de licence liés.
• Synchroniser : récupère de nouveau le produit depuis GET /v2/products/{id} et actualise ses champs.
• Importer les ventes (permission gumroad.customers.manage) : demande les ventes du produit page par page (GET /v2/sales?product_id=…&page_key=…, une page par appel AJAX) jusqu’à la dernière page. Seules les ventes qui portent une license_key sont importées. Les ventes déjà enregistrées sont ignorées. Les acheteurs sont rattachés aux comptes du site par e-mail. Les ventes qui n’ont pas été remboursées ni contestées sont aussi ajoutées à l’add-on Licences.
• Ajouter une clé de licence : ajoutez manuellement une clé connue. La clé est vérifiée auprès de Gumroad pour ce produit uniquement, et l’e-mail de l’acheteur n’est comparé à aucun compte. L’acheteur est tout de même rattaché à un compte du site par e-mail lorsqu’il en existe un.
• Tableau des licences : toutes les licences enregistrées pour le produit, avec l’acheteur, le compte lié, la clé, le montant et l’état de remboursement / contestation.

Lier les produits Gumroad aux produits de licence

Cliquez sur l’action Produits de licence liés d’une ligne de la liste des produits (ou sur la page du produit) pour ouvrir une fenêtre :

• Elle affiche l’ID du produit Gumroad, le permalien court et le permalien personnalisé.
• Elle utilise le sélecteur de produits de licence partagé (filtre par marketplace, recherche par mot-clé, slug / SKU / version sur chaque ligne).
• Un bouton Créer un produit de licence crée le produit de licence manquant à partir du produit Gumroad et le sélectionne (disponible lorsque vous avez la permission licenses.products.create ou licenses.products.edit).
• À l’enregistrement, les produits de licence sélectionnés remplacent les liens actuels. Sans l’option Autoriser plusieurs produits de licence par produit, un seul peut être sélectionné.

Lorsqu’une vente est enregistrée, sa clé est attribuée au produit de licence sous lequel le produit Gumroad est référencé. Si le produit Gumroad n’a aucune fiche, l’add-on essaie dans cet ordre : un produit de licence dont le slug ou l’alias de slug correspond au nom du produit, puis le premier produit de licence actif. Si aucun n’existe, il crée un produit de licence et y référence immédiatement le produit Gumroad. Pour éviter que des clés ne se retrouvent sur le mauvais produit, liez explicitement chaque produit Gumroad.

Admin : Clients

Gumroad → Clients regroupe les licences enregistrées par e-mail d’acheteur. Gumroad ne fournit pas de nom d’utilisateur d’acheteur : c’est donc l’e-mail qui identifie le client.

• Colonnes : e-mail de l’acheteur, compte du site lié, nombre de licences et de produits, total dépensé (ventes remboursées exclues), nombre de remboursements, dernier achat.
• Recherche par e-mail d’acheteur, ou par le nom / l’e-mail du compte lié.
• Filtres : acheteurs d’un produit donné (leurs totaux continuent d’inclure tous leurs achats), liés / non liés à un compte, avec / sans remboursement.
• Tri : les plus récents (par défaut), les plus anciens, licences, montant dépensé, e-mail.

Détail du client

L’URL de la page client est /admin/gumroad/customers/show?email=…. L’e-mail est transmis dans la chaîne de requête parce que certains pare-feu applicatifs bloquent les chemins d’URL qui se terminent par .com. La page affiche :

• L’e-mail de l’acheteur et le compte du site lié (avec un lien vers l’utilisateur).
• Des statistiques : licences, produits, total dépensé, nombre de licences vérifiées, nombre de remboursements.
• Toutes les licences de l’acheteur, de la vente la plus récente à la plus ancienne, avec un lien vers chaque produit.

Admin : Journaux de ping

Gumroad → Journaux de ping enregistre chaque ping reçu, y compris ceux qui ont été rejetés, ainsi que chaque relance lancée par un administrateur.

• Cartes de statistiques : total, créées, doublons, en échec (échecs + rejets), dernier ping reçu.
• Filtre par statut, et recherche par ID de vente, e-mail de l’acheteur, clé de licence, nom de produit ou ID de produit Gumroad.
• Chaque ligne indique l’origine (ping ou relance manuelle), la vente, le produit et l’acheteur, ainsi que la clé de licence (avec un lien vers la clé dans Licences lorsqu’il en existe une) et un badge précisant si Gumroad l’a délivrée ou si le site l’a créée. Elle indique aussi si l’e-mail de la clé a été envoyé et à quelle adresse, ainsi que le message. Les détails affichent la requête brute et les données de vente renvoyées par l’API.
• Relancer (uniquement pour les journaux qui ont un ID de vente) : traite de nouveau la vente. La vente est récupérée de nouveau depuis l’API Gumroad, comme pour un ping en direct.
• Supprimer une entrée de journal, ou Purger les journaux de plus de 7, 30, 60, 90, 180 ou 365 jours.

Admin : Vérifier une clé de licence

Gumroad → Vérifier une clé de licence retrouve un achat à partir de n’importe lequel de ces éléments :

• une clé de licence : une clé délivrée par Gumroad, ou une clé créée par le site dans n’importe quel format de l’add-on Licences,
• l’e-mail de l’acheteur,
• le numéro de commande figurant sur le reçu Gumroad, ou l’identifiant de vente Gumroad.

Les enregistrements locaux sont consultés en premier. Si plusieurs ventes correspondent (par exemple l’e-mail d’un acheteur récurrent), jusqu’à 25 sont listées et vous en choisissez une. Pour une correspondance locale unique, la vente est revérifiée auprès de l’API Gumroad (GET /v2/sales/{id}), et les changements éventuels (par exemple un nouveau remboursement) sont enregistrés. Si rien n’est trouvé en local et que la valeur est une clé de licence, elle est vérifiée auprès de Gumroad. Vous pouvez choisir un produit pour ne chercher que dans celui-ci. Cochez Ignorer la vérification du format pour envoyer à Gumroad, comme clé, une valeur dont le format n’est pas reconnu.

La même recherche s’ouvre dans une fenêtre depuis la barre latérale des tickets (voir Barre latérale HelpDesk).

Webhook Ping

Gumroad peut notifier votre site de chaque vente (“Ping”). Le point de terminaison est :

{
  "success": true,
  "status": "created",
  "created": true
}

E-mail de clé de licence

Pour les produits sans la fonctionnalité de clés de licence de Gumroad, le reçu Gumroad ne contient aucune clé : cet e-mail est donc le seul exemplaire dont dispose l’acheteur.

• Envoyé à chaque ping traité, rejeux compris. Pour renvoyer une clé perdue, utilisez Resend ping sur la vente dans le tableau de bord Gumroad. Un second e-mail pour la même clé n’est pas envoyé dans les 60 secondes, ce qui évite les doublons lorsqu’un ping arrive deux fois.
• Non envoyé pour les ventes remboursées ou contestées, ni pour les ventes sans e-mail d’acheteur.
• Lorsque l’acheteur a un compte, l’e-mail est envoyé à ce compte, de sorte que sa langue et ses préférences de notification s’appliquent. Sinon, il est envoyé directement à l’e-mail de l’acheteur.
• Il s’agit du type de notification Clé de licence Gumroad (gumroad_license_key_issued, e-mail uniquement). Il peut être désactivé dans les paramètres de notification. Les journaux de ping n’enregistrent que les e-mails réellement envoyés.
• L’option Copie cachée envoie une copie à une adresse unique, ou à tous les comptes administrateur si aucune adresse n’est définie.

Mes licences Gumroad

Les utilisateurs connectés disposent d’une page Mes licences Gumroad dans le menu de leur compte, à l’adresse /{locale}/gumroad/licenses. Elle est disponible dans les six thèmes (default, creative, elegant, minimalist, olive, studio).

Des versions sans {locale} sont également enregistrées (gumroad.licenses, gumroad.licenses.store, …).

Mise en page

• Formulaire Ajouter une clé de licence : la clé figurant sur le reçu Gumroad ou dans l’e-mail de clé de licence.
• Vos licences vérifiées : recherche par nom de produit, e-mail d’acheteur ou clé, 5 par page. Chaque entrée affiche le produit, la clé avec un bouton de copie, les dates de vente et de vérification, un badge Remboursée le cas échéant, et un bouton Supprimer.
• Bouton Enregistrer (lorsque l’add-on Licences est actif et que la clé n’y figure pas encore) : crée la clé de licence dans l’add-on Licences afin qu’elle débloque le support et les autres fonctionnalités auxquelles elle donne accès. Si la clé existe déjà, l’utilisateur y est ajouté comme propriétaire.
• Barre latérale : conseils d’aide (où trouver la clé, utiliser la même adresse e-mail que sur Gumroad, plusieurs clés autorisées) et, lorsque l’add-on HelpDesk est actif, une carte Besoin d’aide ?.

Comment les clients vérifient une clé Gumroad

Lorsqu’un utilisateur soumet une clé (sur la page, ou avec POST /api/gumroad/validate-license), la clé est convertie en majuscules puis vérifiée comme suit :

1. Format : la clé doit ressembler à une clé Gumroad (XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX) ou à une clé dans l’un des formats de l’add-on Licences (ces clés proviennent des pings).
2. Déjà enregistrée ? (sans tenir compte de la casse)
   • Déjà sur ce compte : “déjà enregistrée sur votre compte”.
   • Appartient à un autre compte : already_used.
   • Enregistrée sans compte (typiquement une vente reçue par ping) : l’utilisateur l’obtient si l’e-mail de l’acheteur correspond (lorsque c’est exigé) et si la vente n’a pas été remboursée ni contestée.
3. Vérification par produit auprès de Gumroad : Gumroad ne vérifie une clé qu’avec un ID de produit (POST /v2/licenses/verify, toujours avec increment_uses_count=false). L’add-on essaie la clé sur chaque produit importé actif jusqu’à ce que l’un corresponde. Si aucun produit n’est importé, le résultat est product_mismatch.
4. Les ventes remboursées ou contestées sont refusées (refunded).
5. Identité de l’acheteur : si gumroad_require_email_match est activé, l’e-mail de la vente doit correspondre à l’e-mail du compte (sans tenir compte de la casse), sinon email_mismatch.
6. La licence est enregistrée (verification_method = api) et la clé est créée dans l’add-on Licences.

Statuts de validation

Abonnements

Pour un produit par abonnement, la clé de licence expire à la plus proche des dates de fin, d’annulation et d’échec de l’abonnement (expires_at). Un achat unique n’expire jamais.

Acheteurs sans compte

Un ping ou un import des ventes peut enregistrer une vente avant que l’acheteur n’ait un compte sur votre site. Ces licences sont enregistrées sans propriétaire. Elles sont attribuées au compte qui porte l’e-mail de l’acheteur (sans tenir compte de la casse), avec les clés Licences correspondantes, lorsque :

• un compte utilisateur est créé avec cet e-mail, ou
• l’e-mail d’un compte est vérifié (ce qui couvre aussi un utilisateur qui remplace son e-mail par celui qu’il a utilisé sur Gumroad).

Intégration de l’add-on Licences

Gumroad → Licences

• Chaque vente ajoutée depuis le front-end, le formulaire d’administration, un import des ventes ou un ping est aussi créée comme clé Licences (marketplace gumroad, référence marketplace = la clé, ou l’ID de vente pour les clés créées par le site). Les détails tels que le produit, l’e-mail, le numéro de commande, l’ID de vente, le montant et la devise sont enregistrés avec elle. Les clés qui existent déjà ne sont pas modifiées.
• L’import des produits crée les produits de licence et leurs fiches Gumroad (lorsque la marketplace Gumroad est activée).
• Dans l’add-on Licences, Licences → Produits → Importer depuis Gumroad crée des produits de licence à partir des produits Gumroad déjà importés ici.

Licences → Gumroad

• Si l’API Licences reçoit une clé qu’elle ne connaît pas et que la marketplace Gumroad est activée, elle vérifie la clé auprès de Gumroad sur les produits actifs de cet add-on. S’il n’y en a aucun, elle utilise licenses_gumroad_product_ids. Les clés valides sont créées en local. Les résultats valides sont mis en cache pendant 1 heure, car une vente Gumroad peut être remboursée.
• Chaque fois que l’add-on Licences vérifie une clé Gumroad, l’écouteur SyncGumroadLicenseFromLicense en recopie le résultat ici (verification_method = licenses). Vos pages Clients et Produits contiennent donc aussi les clés qui n’ont été vérifiées que via l’API Licences.

Contrôle d’accès

Les départements du helpdesk, les collections KB et les catégories du forum sont liés à des produits de licence dans l’add-on Licences (licenses_entity_links). Une clé Gumroad les débloque dès qu’elle est une clé Licences d’un produit lié. C’est pourquoi chaque produit Gumroad doit être lié au bon produit de licence.

Ce que l’API Licences accepte comme product

Une application cliente envoie le paramètre product à côté de la clé de licence sur GET /api/licenses/verify. L’add-on Licences accepte plusieurs identifiants du même produit, et les trois identifiants Gumroad en font partie — via la fiche Gumroad du produit, et non via le SKU :

L’ordre complet essayé par le serveur, ainsi que les identifiants des autres marketplaces, sont documentés dans la documentation de l’add-on Licences (Comment l’API reconnaît un produit).

Barre latérale des tickets HelpDesk

Lorsque l’add-on HelpDesk est actif et qu’un ticket appartient à un utilisateur inscrit, la page d’administration du ticket affiche une carte Gumroad dans la barre latérale, avec les licences Gumroad vérifiées de cet utilisateur :

• La miniature et le nom du produit (avec un lien vers Gumroad), accompagnés des badges Remboursée, Contestée et Abonnement terminé le cas échéant.
• La date de vente et la clé de licence. Les administrateurs voient la clé complète avec un bouton de copie. Les autres agents n’en voient que les 8 derniers caractères.
• Un bouton Vérifier (permission gumroad.products.view) qui ouvre la recherche dans une fenêtre.
• Un bouton Voir le client qui ouvre la fiche client.

HelpDesk comptabilise aussi les ventes Gumroad vérifiées dans le total dépensé par le client qu’affichent ses badges.

Mise à jour

Il existe deux façons de mettre cet add-on à jour : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléversement via le panneau d’administration (recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les mises à jour en attente.

Méthode 2 : Remplacement manuel des fichiers

1. Sauvegardez votre base de données.
2. Remplacez le répertoire extensions/addons/gumroad par la nouvelle version.
3. Ouvrez Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les mises à jour en attente. Les fichiers qui ne sont plus utilisés sont supprimés par la mise à jour.
4. Rendez-vous sur Gumroad → Paramètres et cliquez sur Tester la connexion.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Gumroad Integration et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/gumroad/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez Gumroad Integration (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations — ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent — et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/gumroad/, public/vendor/gumroad/ et storage/app/public/addons/gumroad/ ;
• supprime le dossier de l’add-on extensions/addons/gumroad/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/gumroad/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Le test de connexion échoue

• Vérifiez que le jeton a bien été généré depuis une application Gumroad et qu’il n’a pas été révoqué.
• Votre serveur doit pouvoir atteindre api.gumroad.com en HTTPS.

Seuls certains produits sont importés

Depuis la correction de la pagination, toutes les pages sont demandées. S’il manque encore des produits, cherchez dans le journal un avertissement “repeated cursor” ou “page cap” (la limite est de 1 000 produits).

L’import ne crée aucun produit de licence

• L’add-on Licences doit être actif et sa marketplace Gumroad activée (licenses_gumroad_marketplace_enabled).
• Les produits de licence ne sont créés que pour les nouveaux produits Gumroad. Pour les produits importés auparavant, utilisez le bouton Créer un produit de licence de la fenêtre des liens, ou Licences → Produits → Importer depuis Gumroad.

Les permaliens courts sont vides

Ils sont lus depuis votre boutique publique, que Gumroad ne met pas à disposition via son API. Exécutez php artisan gumroad:permalinks --sync. Si vos produits n’ont pas d’URL de boutique, ajoutez --storefront=https://<seller>.gumroad.com.

“Clé de licence invalide” pour une clé réelle

• Le produit doit être importé et actif, car Gumroad ne vérifie une clé qu’avec son produit.
• Les clés créées par le site (UUID, etc.) sont inconnues de Gumroad. Elles sont vérifiées à partir des enregistrements locaux : la vente doit donc avoir été enregistrée par un ping ou par un import.

“Correspondance d’e-mail incorrecte”

L’e-mail du compte diffère de celui utilisé sur Gumroad. Demandez à l’acheteur d’utiliser la même adresse, ou désactivez Exiger la correspondance des e-mails si la clé seule vous suffit comme preuve.

Les pings n’arrivent pas, ou sont rejetés

• Consultez les journaux de ping. Si rien n’est journalisé, l’URL de ping renseignée sur Gumroad est incorrecte ou un pare-feu bloque la requête.
• rejected avec un code HTTP 403 : le ping est désactivé dans les paramètres.
• failed avec un code HTTP 404 : la vente n’a pas pu être récupérée. Vérifiez le jeton d’accès, qui doit appartenir au même compte Gumroad que la vente.
• rejected avec un message “no license key” : activez Générer une clé de licence, ou activez les clés de licence sur le produit chez Gumroad.

L’acheteur n’a pas reçu l’e-mail de la clé

• Consultez la ligne du journal de ping : elle indique si l’e-mail a été envoyé, et à quelle adresse.
• Demandez à l’acheteur de vérifier son dossier spam / courrier indésirable, puis utilisez Resend ping sur la vente dans Gumroad.
• Vérifiez que Envoyer la clé de licence par e-mail est activé, que le type de notification Clé de licence Gumroad n’est pas désactivé, et que l’envoi d’e-mails est configuré.

Une clé a été attribuée au mauvais produit de licence

Le produit Gumroad n’était référencé sous aucun produit de licence : les règles de repli ont donc été utilisées (slug, puis premier produit actif). Liez-le avec la fenêtre Produits de licence liés. Les ventes enregistrées ensuite sont attribuées correctement.

gumroad_product_links est toujours dans la base de données après la mise à jour

Gumroad 1.0.3 a été appliqué avant Licences 1.0.13. Mettez l’add-on Licences à jour, puis relancez la mise à jour de Gumroad depuis Mise à jour du système.