Aperçu
Cette documentation décrit comment enregistrer et configurer une application publique Shopify dans le Shopify Dev Dashboard et l'intégrer à AdlerDo V6.1 pour l'installation OAuth. Le processus produit un Client ID et un Client Secret qu'AdlerDo utilise pour s'authentifier auprès de toute boutique Shopify qui installe l'application.
Contexte de l'architecture
AdlerDo expose /api/shopify/install comme point d'entrée OAuth. L'application du Dev Dashboard redirige chaque demande d'installation vers ce point de terminaison, qui effectue l'échange du code OAuth, conserve le jeton d'accès dans la base de données du locataire et enregistre les webhooks requis via des tâches d'arrière-plan Hangfire.
Prérequis
Avant de commencer, assurez-vous de disposer :
- D'un accès à l'organisation Shopify de TecSee GmbH avec l'autorisation de gérer les applications
- Du middleware AdlerDo déployé et accessible via HTTPS sur l'hôte public configuré pour l'environnement cible
- Des points de terminaison
/api/shopify/install et /api/shopify/callback accessibles et renvoyant des réponses valides
- D'une boutique de développement disponible pour les tests de bout en bout avant de promouvoir les identifiants en production
- De la liste des portées (scopes) OAuth requises par AdlerDo, finalisée et enregistrée dans la configuration
Étape 1 — Ouvrir la page de développement d'applications
Connectez-vous à l'organisation Shopify et accédez à Paramètres → Applications et canaux de vente → Développement d'applications. Cliquez sur le bouton « Build apps in Dev Dashboard ».
Important : n'utilisez PAS le bouton « Create an app » situé sous le panneau des applications personnalisées héritées (Legacy custom apps). Les applications personnalisées héritées cesseront de fonctionner pour les nouveaux marchands à compter du 1er janvier 2026.
Étape 2 — Créer une nouvelle application dans le Dev Dashboard
Le Dev Dashboard s'ouvre à l'adresse dev.shopify.com/dashboard/{organizationId}/apps. Cliquez sur le bouton « Create app » dans le coin supérieur droit de la liste des applications.
Étape 3 — Choisir un mode de création et définir le nom de l'application
Deux modes de création sont proposés :
- Start with Shopify CLI — génère un projet Node/Remix localement. AdlerDo n'a pas besoin de ce mode.
- Start from Dev Dashboard — enregistre les métadonnées de l'application directement dans le tableau de bord et produit immédiatement un Client ID et un Secret. Utilisez ce mode pour AdlerDo.
Saisissez le nom de l'application (par exemple : AdlerDo) et cliquez sur Create.
Convention de nommage
Utilisez un nom stable et destiné au client, affiché sur l'écran de consentement d'installation. Pour TecSee, ajoutez un préfixe par environnement si nécessaire : AdlerDo (Production), AdlerDo Staging, AdlerDo Dev.
Étape 4 — Configurer les URL, la version des webhooks et les portées
Après la création, l'application s'ouvre sur l'onglet Versions avec une nouvelle version brouillon. C'est là que sont définis l'URL d'installation, la version d'API des webhooks et les portées.
6.1 App URL
Définissez App URL sur le point de terminaison public d'installation d'AdlerDo :
https://whlvm133440.wawihost.de/api/shopify/install
Cette URL est celle vers laquelle Shopify redirige lorsqu'un marchand installe l'application. Le ShopifyInstallController d'AdlerDo lit les paramètres de requête shop et hmac, valide le HMAC et redirige vers la page d'octroi OAuth de Shopify.
6.2 Intégrer l'application dans l'administration Shopify
Laissez la case « Embed app in Shopify admin » cochée. AdlerDo sert une interface d'administration intégrée à l'intérieur du cadre d'administration Shopify à l'aide d'App Bridge.
6.3 Preferences URL
Facultatif. Laissez vide, sauf si l'application expose une page de paramètres distincte en dehors de l'expérience intégrée.
6.4 Version d'API des webhooks
Épinglez explicitement la version d'API des webhooks. L'exemple montre 2026-04, qui est la version actuellement consommée par AdlerDo. Modifier cette valeur nécessite de revoir chaque correspondance de charge utile de webhook.
6.5 Portées d'accès
Cliquez sur « Select scopes » et cochez les portées requises par AdlerDo. Limitez la liste au minimum réellement utilisé par AdlerDo — les marchands voient la liste complète sur l'écran de consentement d'installation.
La liste exactement identique doit également être conservée dans la configuration d'AdlerDo (appsettings.Shopify.json → Shopify:Scopes), car le contrôleur d'installation la transmet comme paramètre de requête scope. Une divergence forcera des réinstallations.
Portées facultatives ou requises
Les portées facultatives peuvent être demandées à l'exécution après l'installation. AdlerDo traite toutes les portées listées comme requises lors de l'installation initiale ; laissez donc le bloc des portées facultatives vide.
6.6 Redirect URLs
Ajoutez l'URL de redirection OAuth — l'URL publique du callback OAuth d'AdlerDo :
https://whlvm133440.wawihost.de/api/shopify/callback
Ajoutez une URL de redirection par environnement. Shopify rejette le callback OAuth si l'URL fournie dans le paramètre redirect_uri ne figure pas sur cette liste blanche.
Étape 5 — Publier la version
Après avoir enregistré tous les champs, cliquez sur Release en bas de la page de version.
- Version name — une étiquette lisible par un humain. Convention TecSee :
alderdoo-{n} où n est le numéro de version à incrémentation automatique
- Version message — un court journal des modifications (par exemple, « added read_locales scope », « bumped webhooks API to 2026-04 »)
Cliquez sur Release. La nouvelle version devient immédiatement active (Active) et remplace la version active précédente pour toutes les nouvelles installations.
Modifications de portées après publication
L'ajout d'une nouvelle portée à une version publiée ne l'accorde PAS automatiquement aux boutiques déjà installées. Le propriétaire de la boutique doit approuver une réautorisation. AdlerDo détecte tout écart de portée à chaque requête et déclenche une redirection de réinstallation lorsque nécessaire.
Étape 6 — Vérifier la version active
Ouvrez l'onglet Versions depuis la barre latérale de gauche. La version publiée la plus récente est marquée du badge vert « Active ». Toutes les versions précédentes restent visibles à des fins d'audit.
Depuis cette vue, vous pouvez cliquer sur n'importe quelle version historique pour inspecter sa configuration, ce qui est utile lors du débogage d'une installation sur une boutique plus ancienne.
Étape 7 — Récupérer le Client ID et le Secret
Ouvrez l'onglet Settings depuis la barre latérale de gauche. Le bloc Credentials en haut expose le Client ID et le Secret.
9.1 Client ID
Identifiant public. Peut être ajouté en toute sécurité à la configuration. Copiez-le via l'icône du presse-papiers et collez-le dans la configuration d'AdlerDo.
9.2 Client Secret
Sensible. À traiter comme un identifiant. Le secret n'est affiché qu'une seule fois, lors de sa première génération ; par la suite, seule la forme masquée est affichée. Utilisez l'icône en forme d'œil pour le révéler une fois afin de le copier, puis stockez-le via le chemin standard de stockage des secrets d'AdlerDo.
Dans AdlerDo, les secrets des intégrations de places de marché sont conservés chiffrés en AES-256 dans la base de données du locataire via MarketplaceCredentialEncryptor.
9.3 Rotation du Secret
Cliquez sur Rotate pour générer un nouveau secret. Le secret précédent est invalidé immédiatement. Coordonnez la rotation avec un déploiement du nouveau secret vers AdlerDo.
9.4 Adresse e-mail de contact API
Définissez-la sur une boîte aux lettres surveillée (actuellement dev@tecsee.de). Shopify envoie les avis d'obsolescence d'API et les alertes de sécurité à cette adresse.
Câblage des identifiants dans AdlerDo
Une fois le Client ID et le Secret en main, ajoutez les identifiants à la configuration d'AdlerDo.
10.1 Configuration
Ajoutez le bloc suivant à la configuration propre à l'environnement :
"Shopify": {
"ClientId": "1d15c8413f636e7cfda6f4402d9ef552",
"ClientSecret": "<from Settings page>",
"Scopes": "read_products,write_products,read_orders,write_orders,…",
"WebhooksApiVersion": "2026-04",
"InstallRedirectUrl": "https://whlvm133440.wawihost.de/api/shopify/callback"
}
10.2 Flux d'installation
La poignée de main d'installation de bout en bout est la suivante :
- Le marchand clique sur le lien d'installation → Shopify redirige vers App URL avec les paramètres de requête shop et hmac
/api/shopify/install d'AdlerDo valide le HMAC par rapport au Client Secret et redirige vers https://{shop}/admin/oauth/authorize avec la liste de portées configurée et un nonce d'état généré- Le marchand approuve les portées sur l'écran de consentement Shopify
- Shopify redirige vers
/api/shopify/callback avec les paramètres code, hmac et state
- AdlerDo valide le HMAC et le nonce d'état, puis envoie une requête POST avec code + Client ID + Client Secret vers
https://{shop}/admin/oauth/access_token pour recevoir le jeton d'accès hors ligne
- Le jeton est stocké chiffré en AES-256 pour le locataire ; les abonnements aux webhooks et les tâches Hangfire de synchronisation récurrente sont enregistrés
- AdlerDo redirige le marchand vers l'URL d'administration intégrée
10.3 Vérification de l'installation
Après la poignée de main :
- Confirmez qu'une nouvelle entité
ShopifyConnection existe dans la base de données du locataire, avec un EncryptedAccessToken non nul et la liste des portées accordées
- Confirmez que les tâches récurrentes (
SyncShopifyOrdersV2026, SyncShopifyProductsV2026) sont enregistrées dans Hangfire sous le nouvel identifiant de locataire
- Déclenchez un webhook de test depuis l'administration Shopify et confirmez que le gestionnaire d'AdlerDo le traite sans erreur HMAC
Annexe A — Portées courantes utilisées par AdlerDo
| Portée |
Utilité dans AdlerDo |
read_products, write_products |
Synchronisation du catalogue : créer/mettre à jour des produits et des variantes depuis Odoo ou JTL-Wawi |
read_orders, write_orders |
Récupérer les commandes dans AdlerDo et renvoyer les modifications de commande / traitements |
read_inventory, write_inventory |
Synchronisation des niveaux de stock par emplacement |
read_locations |
Résoudre les emplacements de traitement pour le stock et l'expédition |
read_fulfillments, write_fulfillments |
Créer des traitements et renvoyer les numéros de suivi des transporteurs : DHL, GLS, DPD, DB Schenker |
read_assigned_fulfillment_orders, write_assigned_fulfillment_orders |
Requis lorsqu'AdlerDo agit en tant que service de traitement enregistré |
read_customers, write_customers |
Synchronisation des clients et segmentation B2B |
read_shipping |
Lire la configuration des transporteurs et des zones pour le calcul des tarifs |
read_app_proxy, write_app_proxy |
Requis pour les routes de proxy de l'administration intégrée |
read_analytics |
Tableaux de bord de reporting dans l'administration intégrée |
Annexe B — Dépannage
La redirection d'installation renvoie 401 / HMAC invalide
Cause : le Client Secret dans la configuration d'AdlerDo ne correspond pas au secret dans Settings, ou le secret a été renouvelé sans redéploiement.
Action : copiez le secret depuis la page Settings du Dev Dashboard et redéployez.
Le callback OAuth renvoie « redirect_uri is not whitelisted »
Cause : l'URL de callback n'est pas présente dans le champ Redirect URLs de la version active.
Action : ouvrez la version active, ajoutez l'URL, publiez une nouvelle version, relancez l'installation.
La boutique s'installe mais aucune tâche Hangfire n'apparaît
Cause : l'échange du code OAuth a réussi, mais l'amorçage post-installation a échoué (par exemple, le provisionnement du locataire).
Action : inspectez les journaux d'AdlerDo autour de l'horodatage de l'installation ; le ShopifyInstallController émet un journal Information par étape et un journal Error avec l'étape fautive.
Les livraisons de webhooks échouent avec des erreurs HMAC
Cause : AdlerDo a calculé le HMAC du webhook sur une charge utile analysée au lieu du corps brut.
Action : confirmez que le middleware de requête met en mémoire tampon le corps brut de la requête avant la liaison du modèle pour les routes /api/shopify/webhooks/*.
Le marchand signale des données manquantes après l'ajout d'une portée
Cause : la boutique a été installée avec une version plus ancienne qui n'incluait pas la portée.
Action : déclenchez une redirection de réinstallation — AdlerDo détecte l'écart de portée dans ShopifyConnectionMiddleware et redirige vers le point de terminaison d'installation, où le marchand approuve la nouvelle portée.
Deutsch
English
Polski
Čeština
Español
简体中文
