Intégration Envato Market

Connectez votre site Larapen à l'API Envato Marketplace. Vérifiez les codes d'achat des clients, gérez les acheteurs et contrôlez l'accès au helpcenter, au forum et à la base de connaissances selon la propriété d'achat.

Cas d'Utilisation

Auteur de Plugin CodeCanyon

Vous vendez un plugin WordPress premium ou un package Laravel sur CodeCanyon. Vous gérez un site de support sur Larapen avec un helpcenter.

• Importez vos articles CodeCanyon dans Larapen.
• Liez chaque article à un département du helpcenter (ex. « Support Plugin »).
• Activez « Exiger un Achat pour le HelpCenter » : seuls les acheteurs vérifiés peuvent soumettre des tickets.
• Les clients connectent leur compte Envato via OAuth et leurs achats sont synchronisés automatiquement.

Auteur ThemeForest avec Forum Communautaire

Vous vendez plusieurs thèmes et souhaitez un forum communautaire restreint par produit.

• Créez une catégorie de forum pour chaque thème.
• Liez chaque article Envato à sa catégorie de forum.
• Activez « Exiger un Achat pour le Forum » : les acheteurs ne peuvent publier que dans les forums des articles qu'ils possèdent.

Base de Connaissances avec Contenu Premium

Vous avez une base de connaissances avec de la documentation spécifique aux produits qui ne devrait être accessible qu'aux acheteurs.

• Liez les articles Envato aux collections KB.
• Activez « Restreindre la KB par Achat » : les non-acheteurs voient une page « Achat Requis ».

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• Un token API personnel Envato (voir Créer un Token Envato)
• Au moins un des add-ons : HelpCenter ou Forum (pour les fonctionnalités de contrôle d'accès)

Installation

Étape 1 : Placer l'Add-on

Copiez ou créez un lien symbolique du dossier envato dans le répertoire "extensions/addons" de votre Larapen :

Étape 2 : Activer l'Add-on

Allez dans Admin → Add-ons → Add-ons Installés et activez Intégration Envato Market.

Étape 3 : Exécuter les Migrations

Cela crée 3 tables : envato_items, envato_user_purchases et envato_item_links. Cela ajoute également des colonnes de tokens OAuth (provider_token, provider_refresh_token, provider_token_expires_at) à la table users.

Étape 4 : Définir les Permissions

L'add-on enregistre 10 permissions (voir Permissions). Attribuez-les aux rôles d'administration via Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer

Naviguez vers Admin → Envato → Paramètres et entrez votre token API Envato et votre nom d'utilisateur auteur. Utilisez le bouton Tester la Connexion pour vérifier. Voir Configuration.

Étape 6 : Configurer OAuth (Optionnel)

Pour permettre aux clients de connecter leurs comptes Envato via OAuth :

1. Enregistrez une application sur build.envato.com.
2. Définissez l'URL de rappel sur https://votresite.com/auth/envato/callback.
3. Dans Admin → Paramètres → Auth Sociale, activez le driver Envato et entrez le Client ID et le Client Secret.

Configuration

Tous les paramètres sont gérés dans Admin → Envato → Paramètres (stockés dans la table settings, groupe envato).

Paramètre	Description	Défaut
envato_api_token	Token API personnel Envato pour les appels API au niveau auteur (vérifier les ventes, importer les articles).	(vide)
envato_author_username	Votre nom d'utilisateur Envato Marketplace.	(vide)
envato_require_email_match	Lorsqu'activé, l'email Envato de l'acheteur doit correspondre à l'email de son compte sur le site pour que la vérification d'achat réussisse.	false
envato_helpcenter_require_purchase	Conditionner la création de tickets helpcenter à un achat Envato vérifié.	false
envato_forum_require_purchase	Conditionner la création de fils de discussion du forum à un achat Envato vérifié.	false
envato_kb_restrict_by_purchase	Restreindre l'accès aux collections de la base de connaissances aux acheteurs d'articles liés.	false

Variables d'Environnement

Configuration OAuth (Auth Sociale)

Le OAuth Envato est configuré via les paramètres d'Auth Sociale du noyau, et non directement par l'add-on :

• social_auth_envato_enabled : Activer/désactiver le driver OAuth Envato
• social_auth_envato_client_id : Client ID OAuth de build.envato.com
• social_auth_envato_client_secret : Client Secret OAuth

Créer un Token Envato

1. Allez sur build.envato.com/create-token.
2. Donnez-lui un nom descriptif (ex. « Site Support Larapen »).
3. Activez ces permissions :
   • View and search Envato sites
   • View the user’s Envato Account username
   • View the user’s email address
   • View the user’s account profile details
   • View the user’s items’ sales history
4. Copiez le token généré et collez-le dans Admin → Envato → Paramètres.

Admin : Paramètres

La page des paramètres (Envato → Paramètres) est organisée en quatre sections :

Configuration API

• Token Personnel : Champ mot de passe masqué avec bouton afficher/masquer.
• Nom d'Utilisateur Auteur : Votre nom d'utilisateur Envato Marketplace.
• Tester la Connexion : Appel AJAX qui teste le token en temps réel (fonctionne avec les valeurs non enregistrées saisies dans le formulaire). Renvoie le nom d'utilisateur résolu en cas de succès.

Dépendances d'Add-ons

Affiche des badges indiquant si les add-ons HelpCenter et Forum sont actuellement actifs. Un avertissement est affiché si aucun des deux n'est actif (puisque le contrôle d'accès nécessite au moins l'un d'eux).

Paramètres d'Intégration

Interrupteurs à bascule affichés conditionnellement selon les add-ons actifs :

• Exiger un Achat pour le HelpCenter : affiché si le HelpCenter est actif
• Restreindre la KB par Achat : affiché si le HelpCenter est actif (la KB fait partie du HelpCenter)
• Exiger un Achat pour le Forum : affiché si le Forum est actif

Options de Vérification

• Exiger la Correspondance d'Email : lorsqu'activé, l'email Envato de l'acheteur doit correspondre à l'email de son compte sur le site.

Admin : Articles

La page Articles (Envato → Articles) gère votre catalogue local d'articles Envato Marketplace.

Liste des Articles

Un tableau trié et paginé (20 par page) affichant :

• Miniature : icône de l'article depuis Envato
• Nom & ID Envato
• Site marketplace (ex. codecanyon, themeforest)
• Prix (formaté depuis les centimes)
• Nombre de ventes
• Nombre de liens : combien d'entités (départements, catégories, collections) cet article est lié
• Dernière synchronisation

Actions par article : Voir, Gérer les Liens, Supprimer. Suppression en masse avec sélection par cases à cocher.

Importation d'Articles

Cliquez sur Importer depuis Envato pour lancer une importation séquentielle pilotée par JavaScript :

1. L'interface envoie POST admin/envato/items/import?page=1.
2. Le serveur récupère une page (jusqu'à 10 articles) depuis le point de terminaison Envato author/sales.
3. Pour chaque nouvel article (pas encore en base), il appelle getCatalogItem() pour obtenir les détails complets.
4. Une barre de progression se met à jour en temps réel affichant : nouveaux articles importés, articles ignorés (doublons), pages traitées.
5. Si hasMore = true, le JS demande automatiquement la page suivante.

Détail de l'Article & Synchronisation

La page de détail de l'article (Envato → Articles → {article}) affiche :

• Carte d'info de l'article : miniature, nom, ID Envato, marketplace, auteur, prix, nombre de ventes, note, lien « Voir sur Envato »
• Synchroniser Maintenant : re-récupère l'article depuis l'API catalogue Envato et met à jour tous les champs
• Ajouter un Code d'Achat : l'admin peut ajouter manuellement un code d'achat connu pour cet article
• Tableau des Achats : tous les achats vérifiés pour cet article, affichant le nom d'utilisateur de l'acheteur, l'utilisateur lié du site, l'email, le code d'achat (complet, visible par l'admin), le type de licence, le montant, la date de vente
• Entités liées : barre latérale avec les départements, catégories, collections liés à cet article

Admin : Liens d'Articles

Les Liens d'Articles (Envato → Liens d'Articles) définissent quels départements du helpcenter, catégories du forum et collections KB nécessitent la possession d'articles Envato spécifiques.

Liste des Liens

Un tableau de tous les articles actifs avec leurs entités liées actuelles affichées sous forme de badges. Cliquez sur « Éditer » pour gérer les liens d'un article spécifique.

Édition des Liens

La page d'édition affiche une carte par type d'entité disponible (seuls les types avec des add-ons actifs sont affichés) :

• Départements HelpCenter : cases à cocher pour chaque département actif (si le HelpCenter est actif)
• Catégories du Forum : cases à cocher pour chaque catégorie de forum active (si le Forum est actif)
• Collections KB : cases à cocher pour chaque collection KB active (si le HelpCenter est actif)

L'enregistrement remplace tous les liens existants pour l'article par ceux sélectionnés.

Admin : Clients

La page Clients (Envato → Clients) fournit une vue agrégée de tous les acheteurs.

Liste des Clients

Les achats sont regroupés par buyer_username, affichant :

• Nom d'utilisateur Envato
• Email
• Compte site lié (le cas échéant)
• Nombre d'achats & Nombre d'articles
• Total dépensé
• Statut du support (badge actif/expiré)
• Date du dernier achat

Recherchable par nom d'utilisateur acheteur, email acheteur, ou nom/email de l'utilisateur lié.

Détail du Client

Cliquez sur une ligne client pour voir son historique d'achats complet :

• Barre latérale : nom d'utilisateur, email, compte site lié avec bouton « Révoquer le Lien », grille de statistiques (achats, articles, total dépensé, nombre vérifié), alerte de statut de support
• Tableau des Achats : miniature de l'article, nom de l'article, code d'achat, type de licence, montant, date de vente, badge d'expiration du support

Révocation d'un Lien

L'action Révoquer le Lien :

1. Supprime tous les enregistrements envato_user_purchases de l'acheteur
2. Efface les données OAuth Envato de l'utilisateur (provider, provider_id, provider_token, etc.)
3. L'utilisateur perd immédiatement l'accès à toutes les fonctionnalités conditionnées par l'achat

Comptes Liés

La page Comptes Liés (Envato → Comptes Liés) affiche tous les utilisateurs du site qui ont connecté leur compte Envato via OAuth.

• Utilisateur du site : avatar, nom, email
• Badge Nom d'utilisateur Envato
• Nombre d'achats
• Date de Liaison

Actions par ligne :

• Synchroniser les Achats (AJAX) : appelle le point de terminaison Envato buyer/purchases en utilisant le token OAuth stocké de l'utilisateur et importe tous les nouveaux achats. Met à jour le badge de comptage en ligne.
• Voir les Achats : navigue vers la page de détail du client
• Révoquer le Lien : déconnecte le compte Envato et supprime tous les achats

Flux OAuth

L'intégration OAuth Envato utilise Laravel Socialite et est gérée par le SocialAuthController du noyau.

Pour les Nouveaux Utilisateurs (Connexion/Inscription)

1. L'utilisateur clique sur « Se connecter avec Envato » sur la page de connexion.
2. Redirigé vers la page d'autorisation OAuth d'Envato.
3. Après approbation, Envato redirige vers /auth/envato/callback.
4. Le système trouve ou crée un compte utilisateur (correspondance par nom d'utilisateur Envato, puis par email).
5. Les tokens OAuth (provider_token, provider_refresh_token, provider_token_expires_at) sont stockés dans la table users.
6. Tous les achats Envato de l'utilisateur sont automatiquement synchronisés via syncUserPurchases().
7. L'utilisateur est connecté et redirigé.

Pour les Utilisateurs Existants (Liaison de Compte)

1. L'utilisateur authentifié clique sur « Connecter le Compte Envato » sur la page Mes Achats.
2. Redirigé vers OAuth Envato.
3. Après approbation, le callback lie le compte Envato à l'utilisateur existant.
4. Revalidation : Tous les achats existants appartenant à un autre acheteur Envato sont supprimés.
5. Synchronisation : Tous les nouveaux achats du compte de l'acheteur sont importés.
6. L'utilisateur est redirigé vers la page Mes Achats avec un message récapitulatif.

Rafraîchissement du Token

La méthode EnvatoApiClient::getBuyerPurchases() vérifie automatiquement l'expiration du token. Si le token est expiré (ou expire dans les 5 minutes), elle appelle refreshUserToken() qui utilise le refresh token stocké pour obtenir un nouveau token d'accès depuis l'API Envato. Le nouveau token est enregistré dans la base de données de manière transparente.

Mes Achats

La page d'achats front-end est disponible à /{locale}/envato/purchases (authentification requise).

URL & Routes

Méthode	URL	Nom de Route	Description
GET	/{locale}/envato/purchases	envato.purchases.localized	Page Mes Achats
POST	/{locale}/envato/purchases/add	envato.purchases.store.localized	Ajouter un code d'achat
DELETE	/{locale}/envato/purchases/disconnect	envato.purchases.disconnect.localized	Déconnecter le compte Envato
DELETE	/{locale}/envato/purchases/{id}	envato.purchases.destroy.localized	Supprimer un achat spécifique

Des variantes non localisées (sans {locale}) sont également enregistrées.

Mise en Page

Mise en page responsive à trois colonnes (col-lg-8 + col-lg-4) :

Contenu Principal

• Non connecté : Une carte stylée « Connectez Votre Compte Envato » avec un bouton de connexion vert Envato. Affiche un avertissement si OAuth est désactivé dans les paramètres.
• Connecté : Un badge « Connecté en tant que {nom d'utilisateur} » avec un bouton Déconnexion.
• Formulaire Ajouter un Code d'Achat : champ texte pour le code d'achat (format UUID) + bouton soumettre. Affiché uniquement lorsque le compte Envato de l'utilisateur est connecté.
• Liste des Achats Vérifiés : chaque achat affiche : miniature de l'article, nom, code d'achat masqué, type de licence, date d'expiration du support, date de vérification et un bouton Supprimer.

Barre Latérale

• Carte Statut du Compte Envato (badge connecté/non-connecté, action connecter/déconnecter)
• Carte Besoin d'Aide ? avec lien helpcenter (affichée uniquement si l'add-on HelpCenter est actif)
• Liste de Conseils

Déconnexion

Lorsqu'un utilisateur déconnecte son compte Envato :

1. Tous ses enregistrements envato_user_purchases sont supprimés.
2. Les colonnes provider, provider_id, provider_token, provider_refresh_token, provider_token_expires_at et provider_avatar de la table users sont mises à null.
3. Ils perdent immédiatement l'accès à toutes les fonctionnalités conditionnées par l'achat.

Flux de Validation d'Achat

Lorsqu'un utilisateur soumet un code d'achat (via la page Mes Achats), le système suit ce flux de validation :

1. Vérifier la base locale : ce code d'achat est-il déjà dans envato_user_purchases ? Si oui, vérifier la propriété :
   • Si le code appartient à l'utilisateur actuel : renvoyer « déjà ajouté ».
   • Si le code appartient à un autre utilisateur : renvoyer l'erreur already_used.
2. Vérifier via l'API Envato : appeler author/sale?code={code} en utilisant le token personnel de l'auteur.
3. Trouver ou créer l'article : faire correspondre le item.id de la réponse à un enregistrement local envato_items. Si non trouvé, créer automatiquement l'article à partir de la réponse API.
4. Vérification d'identité de l'acheteur : vérifier que l'utilisateur est le véritable acheteur en utilisant cette priorité :
   1. Correspondance OAuth Envato : provider = 'envato' ET provider_id = buyer_username (plus fiable)
   2. Correspondance de nom : le nom de l'utilisateur correspond au nom d'utilisateur de l'acheteur
   3. Correspondance du préfixe email : le préfixe email correspond au nom d'utilisateur de l'acheteur
5. Créer l'enregistrement d'achat : insérer dans envato_user_purchases avec les données de vérification.
6. Enregistrement automatique de licence : si l'add-on Licences est actif, créer automatiquement un enregistrement LicenseKey (voir Intégration Licences).

Statuts de Validation

Statut	Description
valid	Code d'achat vérifié et ajouté avec succès.
invalid	Code d'achat non trouvé sur Envato ou n'appartient pas à l'auteur configuré.
already_used	Le code d'achat est déjà enregistré par un autre utilisateur sur ce site.
email_mismatch	La correspondance d'email est requise mais l'email de l'acheteur ne correspond pas à l'email de l'utilisateur.
item_mismatch	Le code d'achat est valide mais appartient à un article différent de celui attendu.
api_error	Une erreur s'est produite lors de la communication avec l'API Envato (erreur réseau, token invalide, etc.).

Contrôle d'Accès : Restriction par Achat

Le EnvatoPurchaseValidator est l'utilitaire central pour les décisions de contrôle d'accès. Il est enregistré comme binding IoC (envato.access.checker) afin que les autres add-ons puissent le résoudre sans dépendance directe sur l'add-on Envato.

Fonctionnement de la Restriction

1. Un admin lie des articles Envato à des entités (départements du helpcenter, catégories du forum, collections KB) via la page Liens d'Articles.
2. Un admin active le bouton « Exiger un Achat » correspondant dans les Paramètres.
3. Lorsqu'un utilisateur tente d'accéder à une entité restreinte, l'add-on helpcenter/forum/KB appelle EnvatoPurchaseValidator::userHasPurchaseFor($userId, $linkableType, $linkableId).
4. Le validateur vérifie :
   • Des articles Envato sont-ils liés à cette entité ? Si non → non restreint (renvoie true).
   • L'utilisateur a-t-il un achat vérifié pour l'un des articles liés ? Si oui → accès autorisé.
   • Sinon → accès refusé. L'utilisateur voit une page « Achat Requis ».

Intégration HelpCenter

Lorsque envato_helpcenter_require_purchase est activé :

• Le formulaire de création de ticket du helpcenter inclut un sélecteur d'achat en liste déroulante (envato::front.partials._purchase-field-helpcenter).
• Restriction par département : userHasPurchaseFor($userId, 'helpcenter_department', $departmentId).
• Les utilisateurs sans achat valide pour le département sélectionné voient la page « Achat Requis ».

Intégration Forum

Lorsque envato_forum_require_purchase est activé :

• Le formulaire de création de fil de discussion du forum inclut un sélecteur d'achat en liste déroulante (envato::front.partials._purchase-field-forum).
• Restriction par catégorie : userHasPurchaseFor($userId, 'forum_category', $categoryId).
• Les utilisateurs sans achat valide pour la catégorie sélectionnée voient la page « Achat Requis ».

Intégration Base de Connaissances

Lorsque envato_kb_restrict_by_purchase est activé :

• Restriction par collection : userHasPurchaseFor($userId, 'kb_collection', $collectionId).
• Les non-acheteurs voient la page « Achat Requis » avec la liste des articles requis (passés comme $linkedItems à la vue du thème).
• La méthode getAccessibleEntityIds() renvoie uniquement les ID de collections auxquelles l'utilisateur peut accéder, utile pour filtrer les pages de listing KB.

Intégration de l'Add-on Licences

Lorsque les add-ons Envato et Licences sont tous deux actifs et que le Fournisseur Envato est activé dans Licences → Paramètres, l'intégration est bidirectionnelle.

Envato → Licences (Création Automatique de Clé)

Lorsqu'un achat Envato vérifié est créé, une clé de licence est automatiquement enregistrée :

1. Vérifie si l'add-on Licences est actif et si le Fournisseur Envato est activé.
2. Vérifie si une clé de licence avec ce code d'achat existe déjà (ignore le cas échéant).
3. Résout un LicenseProduct par : correspondance SKU avec le item_id Envato → correspondance metadata.item_id → correspondance slug → en crée un nouveau.
4. Mappe le type de licence Envato : « Extended License » → extended, tous les autres → standard.
5. Crée une clé de licence avec provider = 'envato', le code d'achat comme clé, et expires_at = null (les licences Envato sont perpétuelles).

Articles Envato → Synchronisation Produits Licences

Lorsque le Fournisseur Envato est activé dans les paramètres des Licences :

• Importation : L'importation d'articles Envato sur Admin → Envato → Articles crée automatiquement les produits correspondants dans la table des produits de licences. Le item_id Envato est stocké comme sku du produit.
• Suppression : La suppression d'articles Envato supprime également le produit de licence correspondant (correspondance par sku).

Licences → Envato (Vérification par Fournisseur)

Lorsqu'un code d'achat est vérifié via l'API Licences (GET /api/licenses/verify) et n'est pas trouvé localement, le Fournisseur Envato le vérifie automatiquement contre l'API Envato. Si valide, la clé et un produit correspondant sont créés automatiquement pour les recherches futures.

Si l'add-on Envato est actif, son client API est utilisé pour la vérification. Sinon, l'add-on Licences effectue des appels HTTP directs vers l'API Envato.

Mise à Jour

Étape 1 : Remplacer les Fichiers

Remplacez le répertoire de l'add-on par la nouvelle version.

Étape 2 : Exécuter les Migrations

Étape 3 : Vider les Caches

Étape 4 : Vérifier

Visitez Envato → Paramètres et cliquez sur Tester la Connexion pour confirmer que le token API fonctionne toujours.

Dépannage

Le Test de Connexion échoue : « Could not connect to Envato API »

Vérifiez que :

• Le token API est correct et n'a pas été révoqué.
• Le token possède les permissions requises (notamment « View sales history »).
• Votre serveur peut atteindre api.envato.com (pas de pare-feu bloquant le HTTPS sortant).

L'importation ne trouve aucun article

L'importation utilise le point de terminaison author/sales, qui ne renvoie que les articles que vous avez vendus. Si vous avez un nouvel article avec zéro vente, il n'apparaîtra pas dans l'importation. Vous pouvez ajouter manuellement des articles dans la base de données ou attendre la première vente.

La vérification du code d'achat échoue : « Invalid purchase code »

• Assurez-vous que le code d'achat est un UUID valide (36 caractères, tirets inclus).
• Vérifiez que le code appartient à l'un de vos articles (le point de terminaison author/sale ne renvoie que les ventes de l'auteur configuré).
• Vérifiez que envato_author_username est correctement défini dans les paramètres.

L'utilisateur ne peut pas connecter son compte Envato

• Assurez-vous que le driver OAuth Envato est activé dans Admin → Paramètres → Auth Sociale.
• Vérifiez que le Client ID et le Client Secret sont définis.
• L'URL de rappel chez Envato doit correspondre exactement à https://votresite.com/auth/envato/callback.

Les achats ne se synchronisent pas après la connexion OAuth

• Le token OAuth a peut-être expiré. Essayez de déconnecter et reconnecter.
• Vérifiez que les colonnes provider_token et provider_refresh_token existent dans la table users (exécutez php artisan migrate si la migration n'a pas été exécutée).
• Vérifiez les logs du serveur pour les erreurs de l'API Envato pendant le processus de synchronisation.

La restriction par achat ne fonctionne pas : les utilisateurs accèdent sans achat

• Assurez-vous que le bouton correspondant est activé (envato_helpcenter_require_purchase, envato_forum_require_purchase, ou envato_kb_restrict_by_purchase).
• Assurez-vous qu'au moins un article Envato est lié à l'entité. Les entités sans articles liés sont toujours non restreintes.
• Vérifiez que l'add-on helpcenter/forum appelle EnvatoPurchaseValidator::userHasPurchaseFor() dans ses vérifications d'accès.

Non-correspondance d'identité de l'acheteur : achat rejeté malgré un code valide

Le système essaie de faire correspondre l'acheteur à l'utilisateur authentifié via trois méthodes (dans l'ordre) :

1. Correspondance OAuth Envato (provider_id = nom d'utilisateur acheteur) : plus fiable
2. Correspondance de nom
3. Correspondance du préfixe email

Si aucune ne correspond, l'achat est rejeté. Solution : faites connecter le compte Envato de l'utilisateur via OAuth d'abord, puis ajoutez le code d'achat. La correspondance OAuth est définitive.

La création automatique de licence ne fonctionne pas

• Assurez-vous que l'add-on Licences est installé et actif.
• Vérifiez que la classe Addons\Licenses\Services\LicenseKeyService existe.
• Vérifiez les logs du serveur pour les avertissements pendant le processus d'enregistrement automatique.
• Si une clé de licence avec le même code d'achat existe déjà, la création automatique est ignorée (par conception).