Tutoriel sur l’extension des méthodes d’expédition

Accédez à pipedream.com et inscrivez-vous ou connectez-vous.

Cliquez sur Nouveau workflow (ou Ajouter un workflow).

Pour le déclencheur , sélectionnez HTTP/Webhook.

Dans la configuration du déclencheur, définissez Réponse HTTP sur Renvoyer une réponse personnalisée à partir de votre workflow. Cela permet à l’étape de code d’envoyer la réponse JSON simulée.

Pipedream affiche une URL de point d’entrée HTTP unique, telle que https://123456.m.pipedream.net.

Copiez cette URL et utilisez-la comme URL du service lors de la configuration de l’extension dans Commerce Admin.

{width="600" modal="regular"}

Cliquez sur l’icône + pour ajouter une étape.

Choisissez Exécuter le code Node.js (étape du code).

Remplacez le code par défaut par le code JavaScript suivant.

export default defineComponent({
async run({ steps, $ }) {
   const event = steps.trigger.event;
   const body = event.body ?? {};
   const headers = event.headers ?? {};
   const apiKey = headers["api-key"] ?? body.api_key ?? "";

   if (!apiKey || String(apiKey).trim() === "") {
      await $.respond({
      immediate: true,
      status: 401,
      headers: { "Content-Type": "application/json" },
      body: { error: "Missing or invalid API-Key header" },
      });
      return;
   }

   const shipment = body.shipment;
   if (!shipment || typeof shipment !== "object") {
      await $.respond({
      immediate: true,
      status: 400,
      headers: { "Content-Type": "application/json" },
      body: { error: "Missing or invalid shipment" },
      });
      return;
   }

   const rates = [
      {
      service_code: "mock_standard",
      service_name: "Mock Standard",
      carrier_friendly_name: "Mock Carrier",
      shipping_amount: { amount: 5.99 },
      shipment_cost: 5.99,
      cost: 5.99,
      },
      {
      service_code: "mock_express",
      service_name: "Mock Express",
      carrier_friendly_name: "Mock Carrier",
      shipping_amount: { amount: 12.99 },
      shipment_cost: 12.99,
      cost: 12.99,
      },
   ];

   await $.respond({
      immediate: true,
      status: 200,
      headers: { "Content-Type": "application/json" },
      body: { rates },
   });
},
});

Cliquez sur Déployer.

{width="600" modal="regular"}

Accédez aux paramètres MCP dans votre agent de codage. Par exemple, dans Cursor, accédez à Cursor > Settings > Cursor Settings > Tools & MCP. Vérifiez que l'ensemble d'outils commerce-extensibility est activé sans erreur. Si des erreurs s’affichent, désactivez la palette d’outils et activez-la.

{width="600" modal="regular"}

Si de la documentation est ajoutée au contexte du curseur, désactivez-la. Accédez à Curseur > Paramètres > Paramètres du curseur > Indexation et documents et supprimez toute documentation répertoriée.

{width="600" modal="regular"}

Donnez à l’agent l’accès à la spécification de l’API de taux simulés afin qu’il puisse implémenter correctement le client. Si vous ne l’avez pas déjà fait, téléchargez le fichier de spécification de l’API de taux simulés, ouvrez-le et ajoutez le fichier .md à votre projet (par exemple, docs/mock-rates-api-spec.md), puis référencez ce fichier dans votre invite.

Générez l’extension du mode d’expédition :

• Dans la fenêtre de conversation de l’agent, sélectionnez le mode Planifier, le cas échéant. Cela empêche l’agent de procéder sans plan.
• Saisissez l’invite suivante :

Build an Adobe Commerce extension that adds a shipping method at checkout. The rates come from an external mock shipping rates service: the merchant configures the service's URL and API key in Admin, and at checkout the extension asks that service for rates and shows the returned options to the customer.

External service (mock shipping rates API):
- The service endpoint URL is configurable by the merchant (for example https://123456.m.pipedream.net).
- The API is specified in ./docs/mock-rates-api-spec.md.

The merchant must be able to configure the following in the Adobe Commerce Admin UI. Use the Adobe Commerce Admin UI SDK (or equivalent App Builder extensibility options for the Admin) to add a configuration screen where the merchant can set:
- The service URL (where the extension sends rate requests).
- An API key the service expects (any non-empty value for the mock). The API key is sensitive data: it must be stored securely and must never appear in logs, error messages, or in the UI in full (e.g. mask in the UI).
- The warehouse (ship-from) address: name, phone, street, city, state, postal code, country. This is the origin used when requesting rates.

{width="600" modal="regular"}

Répondez précisément aux questions de l’agent pour l’aider à générer le meilleur code. Si l’agent demande le kit ou le modèle à utiliser, redirigez-le vers le kit de démarrage de passage en caisse avec le domaine d’expédition et l’extension SDK de l’interface utilisateur d’administration, de sorte que le webhook d’expédition et l’écran de configuration du commerçant soient mis en œuvre.

L’agent peut créer un fichier requirements.md (ou équivalent) qui sert de source de vérité pour l’implémentation.

Consultez le fichier requirements.md (ou équivalent) et vérifiez le plan. Si tout semble correct, demandez à l'agent de passer à la planification de l'architecture (ou Phase 2). Confirmez que :

• Une action shipping-methods (ou équivalente) gère le webhook Commerce et appelle l’API des taux externes.
• Une action shipping-config (ou équivalente) prend en charge GET (lecture de la configuration, clé d’API masquée) et SET (enregistrement de l’URL du service, clé d’API, adresse d’entrepôt de données), avec la configuration stockée en toute sécurité, par exemple à l’état d’exécution.
• L’interface utilisateur d’administration comprend un onglet Simulation d’expédition (ou similaire) avec des champs pour l’URL du service, la clé API (mot de passe/masqué) et l’adresse de l’entrepôt de données.

{width="600" modal="regular"}

Examinez le plan d’architecture lorsque l’agent le fournit.

Plan de mise en œuvre de l’agent {width="600" modal="regular"}

Demandez à l’agent de poursuivre la génération du code. L’agent doit ajouter un transporteur simulé à la configuration des transporteurs, ce qui permet à Commerce d’accepter les méthodes renvoyées et d’utiliser la méthode webhook plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates (type webhook after, obligatoire facultatif).

L’agent génère le code nécessaire et fournit un résumé détaillé des étapes suivantes (y compris l’installation des dépendances, l’enregistrement du transporteur simulé, la configuration du Webhook Commerce et le déploiement).

{width="600" modal="regular"} {width="600" modal="regular"}

Après avoir vérifié le code généré, déployez l’extension à l’aide de l’invite suivante :

Deploy the app.

L’agent effectue une évaluation du niveau de préparation avant le déploiement (par exemple, en vérifiant la .env des variables COMMERCE_WEBHOOKS_PUBLIC_KEY, COMMERCE_BASE_URL et OAuth/IMS si l’interface utilisateur d’administration ou l’API Commerce est utilisée).

{width="600" modal="regular"}

Lorsque vous êtes certain des résultats de l’évaluation, demandez à l’agent de procéder au déploiement. L’agent utilise la boîte à outils MCP pour vérifier, créer et déployer automatiquement.

{width="600" modal="regular"}

Enregistrez l’opérateur simulé dans Commerce (exécutez-le une fois après le déploiement) :

npm run create-shipping-carriers

Assurez-vous que votre .env dispose de COMMERCE_BASE_URL et d’informations d’identification OAuth/IMS valides, de sorte que le script puisse enregistrer l’opérateur.

Configuration du webhook d’expédition dans Commerce Admin:

• Accédez à Magasins > Paramètres > Configuration > Services Adobe > Webhooks Commerce.

• Ajoutez un webhook :

  • Méthode Webhook : plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Type de Webhook : after
  • URL : URL d’action web shipping-methods déployée (à partir de la sortie de déploiement ou de la Adobe Developer Console).
  • Obligatoire : Facultatif - Cela permet à l’extraction de continuer à fonctionner si l’API externe ne renvoie aucun taux.

{width="600" modal="regular"}

Configurer l’extension Admin UI SDK :

• Dans Commerce Admin, accédez à Magasins > Paramètres > Configuration.
• Ouvrez Adobe Services > Admin UI SDK.
• Définissez Activer Admin UI SDK sur Oui et cliquez sur Enregistrer la configuration s’il n’est pas déjà activé.
• Cliquez sur Configurer les extensions, choisissez l’espace de travail sur lequel votre application est déployée, puis cliquez sur Appliquer. Vous pouvez également sélectionner l’option Personnalisé et saisir le nom de l’espace de travail.
• Sélectionnez l’application App Builder dans la liste et enregistrez-la. Si l’application n’apparaît pas, cliquez sur Actualiser les enregistrements et réessayez.

{width="600" modal="regular"}

Configurez la méthode d’expédition simulée dans l’interface utilisateur d’administration d’Adobe Commerce :

• Ouvrez Applications et sélectionnez votre application.

• Ouvrez l’onglet Expédition simulée (ou l’équivalent).

• Saisissez les informations suivantes :

  • URL du service : l’URL du workflow Pipedream que vous avez copiée (par exemple, https://123456.m.pipedream.net).
  • Clé API : toute valeur non vide pour la simulation, par exemple tutorial-key.
  • Adresse de l’entrepôt de données (d’expédition) : nom téléphone, rue, ville, État, code postal, pays.

• Cliquez sur Enregistrer. La configuration est stockée dans l’état d’exécution et est utilisée par l’action shipping-methods.

{width="600" modal="regular"}

Vérifier au passage en caisse : ajoutez un produit au panier, accédez au passage en caisse et saisissez une adresse de livraison. Vous devriez voir les options d’expédition simulées, par exemple Simulation standard et Simulation express.

{width="600" modal="regular"}