Intégration Shopify

Alkax propose une application Shopify hébergée à commerce.alkax.io. La configuration de l’intégration commence dans un projet développeur Alkax, et non dans un écran de configuration commerçant autonome.

Le projet développeur délimite le tenant. Un projet peut connecter plusieurs boutiques Shopify, et chaque connexion choisit l’environnement Sandbox ou Production du projet.

Connecter une boutique

1. Ouvrez la Console développeur et sélectionnez le projet auquel la boutique Shopify doit appartenir.
2. Ouvrez E-commerce → Shopify.
3. Saisissez le domaine *.myshopify.com de la boutique.
4. Choisissez Sandbox ou Production.
5. Choisissez Connect store (Connecter la boutique).
6. Terminez l’installation et l’autorisation Shopify à commerce.alkax.io.

Alkax crée un transfert de connexion de courte durée. Le service Shopify partagé l’échange après l’authentification Shopify et rattache la boutique à :

DeveloperProject.Id   -> tenant identity
DeveloperEnvironment  -> Sandbox or Production execution/billing context
Shopify shop domain   -> connected store

Une boutique ne peut avoir qu’un seul rattachement actif à un projet Alkax à la fois.

Configuration automatique

Les développeurs ne copient pas de clé API Alkax dans Shopify. Après un rattachement réussi, Alkax émet un identifiant réservé à l’intégration pour le projet et l’environnement sélectionnés, et le renvoie uniquement au service partagé commerce.alkax.io.

Les appels de l’intégration Shopify utilisent donc les mêmes règles d’attribution au projet et à l’environnement, les mêmes limites et le même circuit de facturation que le trafic habituel de la Plateforme développeur.

L’identifiant reste côté serveur. Il n’est jamais inclus dans une extension de paiement, une extension de compte client ou une réponse au navigateur.

Autocomplétion des adresses

L’autocomplétion des adresses est la fonctionnalité Shopify de base. L’extension de paiement appelle le service partagé avec un jeton de session Shopify. Le service retrouve le tenant du projet associé à la boutique et appelle :

GET /api/v1/addresses/suggestions?q=<query>&countryCode=<optional>&limit=5
X-Alkax-Key: <managed project/environment credential>

Les suggestions proviennent de la recherche d’adresses gérée par Alkax. La saisie manuelle d’adresse Shopify reste disponible si Alkax est temporairement indisponible.

La disponibilité des extensions d’adresse au paiement dépend des exigences actuelles de Shopify concernant la formule de paiement, les données clients protégées et l’accès réseau.

Suivi facultatif des commandes

Le suivi des commandes s’active par boutique connectée depuis Console développeur → E-commerce → Shopify.

Lorsqu’un développeur sélectionne Enable tracking (Activer le suivi) :

1. Alkax enregistre la demande de suivi pour cette connexion entre projet et boutique.
2. Le parcours ouvre l’application Shopify installée.
3. Shopify demande à la boutique d’accorder la portée facultative read_orders.
4. commerce.alkax.io transmet cette approbation à l’intégration de référence du projet.
5. Les nouveaux webhooks orders/create peuvent créer des livraisons Alkax rattachées au projet.
6. L’extension de statut de commande du compte client peut afficher l’état de livraison Alkax après avoir vérifié que la commande appartient au client connecté. Le suivi est masqué pour les sessions anonymes ou lorsque Shopify ne peut pas vérifier cette appartenance.

La désactivation du suivi dans la Console développeur prend effet sur la connexion de référence même si la permission Shopify n’a pas encore été révoquée manuellement. L’application installée peut aussi révoquer un accès aux commandes devenu inutile.

Service partagé entre tenants

Alkax Developer Project
  └── E-commerce
       └── Shopify
            ├── store-a.myshopify.com -> Sandbox
            └── store-b.myshopify.com -> Production
                         |
                         v
                commerce.alkax.io
             shared Shopify runtime
                         |
              tenant = DeveloperProject.Id
                         |
                         v
                  Alkax platform

La base de données de l’application Alkax détient la connexion de référence et l’état des fonctionnalités. Celle du service Shopify ne détient que l’état opérationnel Shopify : sessions OAuth, rattachement au tenant résolu, réceptions de webhooks et correspondances entre commandes Shopify et livraisons Alkax.

Les lignes opérationnelles incluent les identifiants du projet et de l’environnement pour rendre l’attribution au tenant explicite et vérifiable.

Sécurité de la connexion

Le projet crée un jeton de transfert aléatoire à courte durée de vie. Alkax ne conserve que son empreinte. Le service Shopify conserve le transfert juste assez longtemps pour terminer OAuth Shopify, puis l’échange via un point de terminaison Alkax authentifié pour le service.

L’échange est à usage unique. Une activation réussie efface le transfert et crée automatiquement l’identifiant de projet/environnement utilisé par cette connexion de boutique.

La désinstallation ou la suppression des données d’une boutique Shopify appelle le plan de contrôle Alkax, marque la connexion de référence comme déconnectée, désactive le suivi et révoque son identifiant d’intégration.

Identité des livraisons et nouvelles tentatives

Chaque commande Shopify est associée de façon déterministe à partir du domaine de boutique et du GID de commande Shopify. L’intégration utilise des valeurs Alkax stables d’idempotence et d’activation et conserve les identifiants de webhook Shopify : les nouvelles tentatives Shopify et Alkax ne créent donc pas de livraisons en double.

Lorsque Shopify ne fournit pas de coordonnées de destination, l’intégration peut décoder un Plus Code Alkax intégré à l’adresse sélectionnée. Si aucune coordonnée ni aucun code Alkax utilisable n’existe, la commande est enregistrée comme awaiting_address ; aucune livraison à 0,0 n’est créée.

Configuration pour les responsables techniques

L’implémentation se trouve dans integrations/shopify/ et se déploie séparément du frontend web principal.

Configuration d’exécution requise :

DATABASE_URL=postgresql://...
SHOPIFY_API_KEY=...
SHOPIFY_API_SECRET=...
SHOPIFY_APP_URL=https://commerce.alkax.io
SCOPES=

ALKAX_API_URL=https://<alkax-api-host>
ALKAX_SHOPIFY_SERVICE_KEY=<shared service identity>

Le déploiement de l’API Alkax doit définir les valeurs correspondantes :

ShopifyIntegration:AppUrl=https://commerce.alkax.io
ShopifyIntegration:ServiceKey=<same shared service identity>

Validation locale :

cd integrations/shopify
npm install
npm run prisma:generate
npm test
npm run typecheck
npm run build

Consultez la Plateforme développeur et Delivery Intelligence pour les contrats sous-jacents de projet, de quota et de livraison.