Tutorial zur Erweiterung der Versandmethode

Gehen Sie pipedream.com und melden Sie sich an oder melden Sie sich an.

Klicken Sie Neuer Workflow (oder Workflow hinzufügen).

Wählen Sie für den Trigger HTTP / Webhook aus.

Legen Sie in der Trigger-Konfiguration HTTP-Antwort auf Eine benutzerdefinierte Antwort aus Ihrem Workflow zurückgeben fest. Dadurch kann der Code-Schritt die JSON-Pseudoantwort senden.

Pipedream zeigt eine eindeutige HTTP-Endpunkt-URL an, z. B. https://123456.m.pipedream.net.

Kopieren Sie diese URL und verwenden Sie sie als Service-URL beim Konfigurieren der Erweiterung in Commerce Admin.

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

Klicken Sie auf das Symbol + , um einen Schritt hinzuzufügen.

Wählen Sie Node.js-Code ausführen (Code-Schritt) aus.

Ersetzen Sie den Standardcode durch die folgende JavaScript.

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 },
   });
},
});

Klicken Sie Bereitstellen.

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

Navigieren Sie zu den MCP-Einstellungen in Ihrem Codierungs-Agent. Gehen Sie beispielsweise im Cursor zu Cursor > Settings > Cursor Settings > Tools & MCP. Stellen Sie sicher, dass das commerce-extensibility Toolset fehlerfrei aktiviert ist. Wenn Fehler angezeigt werden, schalten Sie das Toolset aus und ein.

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

Wenn Sie dem Kontext des Cursors eine Dokumentation hinzugefügt haben, deaktivieren Sie diese. Navigieren Sie zu Cursor > Einstellungen > Cursor-Einstellungen > Indizierung und Dokumente und löschen Sie alle aufgelisteten Dokumentationen.

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

Erteilen Sie dem Agenten Zugriff auf die Pseudo-Raten-API-Spezifikation, damit er den Client korrekt implementieren kann. Wenn Sie dies noch nicht getan haben, laden Sie die Pseudo-Raten-API-Spezifikationsdatei herunter, öffnen Sie sie und fügen Sie die .md-Datei zu Ihrem Projekt hinzu (z. B. docs/mock-rates-api-spec.md) und verweisen Sie dann in Ihrer Eingabeaufforderung auf diese Datei.

Erstellen Sie die Erweiterung der Versandmethode:

• Wählen Sie im Chat-Fenster des Agenten den Plan-Modus aus, falls verfügbar. Dadurch wird verhindert, dass der Agent ohne Plan fortfährt.
• Geben Sie die folgende Eingabeaufforderung ein:

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"}

Beantworten Sie die Fragen des Agenten genau, damit er den besten Code generieren kann. Wenn der Agent fragt, welches Kit oder welche Vorlage verwendet werden soll, leiten Sie ihn an das Checkout-Starter-Kit mit der SDK-Erweiterung für die Versand-Domain und die Admin-Benutzeroberfläche weiter, damit sowohl der Versand-Webhook als auch der Bildschirm für die Händlerkonfiguration implementiert sind.

Der Agent kann eine requirements.md-Datei (oder eine entsprechende Datei) erstellen, die als Datenquelle für die Implementierung dient.

Überprüfen Sie die requirements.md (oder vergleichbare Datei) und überprüfen Sie den Plan. Wenn alles korrekt aussieht, weisen Sie den Agenten an, zur Architekturplanung (oder Phase 2) zu wechseln. Bestätigen Sie Folgendes:

• Eine shipping-methods-Aktion (oder Ähnliches) verarbeitet den Commerce-Webhook und ruft die API für externe Raten auf.
• Eine shipping-config-Aktion (oder eine entsprechende Aktion) unterstützt GET (Lesekonfiguration, API-Schlüssel maskiert) und SET (Dienst-URL speichern, API-Schlüssel, Warehouse-Adresse), wobei die Konfiguration sicher gespeichert ist, z. B. im Laufzeitstatus.
• Die Admin-Benutzeroberfläche enthält eine Registerkarte Pseudolieferung (oder eine ähnliche Registerkarte) mit Feldern für die Service-URL, den API-Schlüssel (Kennwort/maskiert) und die Warehouse-Adresse.

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

Überprüfen Sie den Architekturplan, wenn der Agent ihn bereitstellt.

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

Weisen Sie den Agenten an, mit der Code-Generierung fortzufahren. Der Agent sollte der Konfiguration der Versanddienstleister einen Pseudo-Provider hinzufügen, sodass Commerce die zurückgegebenen Methoden akzeptieren kann, und die Webhook-Methode plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates verwenden (Webhook-Typ after, erforderlich optional).

Der Agent generiert den erforderlichen Code und stellt eine detaillierte Zusammenfassung für Ihre nächsten Schritte bereit (einschließlich der Installation von Abhängigkeiten, der Registrierung des Pseudo-Providers, der Konfiguration des Commerce-Webhooks und der Bereitstellung).

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

Nachdem Sie den generierten Code überprüft haben, stellen Sie die Erweiterung mithilfe der folgenden Eingabeaufforderung bereit:

Deploy the app.

Der Agent führt vor der Bereitstellung eine Bewertung der Bereitschaft durch (z. B. .env auf COMMERCE_WEBHOOKS_PUBLIC_KEY-, COMMERCE_BASE_URL- und OAuth/IMS-Variablen, wenn die Admin-Benutzeroberfläche oder die Commerce-API verwendet wird).

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

Wenn Sie mit den Bewertungsergebnissen vertraut sind, weisen Sie den Agenten an, mit der Bereitstellung fortzufahren. Der Agent verwendet das MCP-Toolkit, um automatisch zu überprüfen, zu erstellen und bereitzustellen.

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

Pseudo-Provider in Commerce registrieren (einmal nach der Bereitstellung ausführen):

npm run create-shipping-carriers

Stellen Sie sicher, dass Ihr .env über COMMERCE_BASE_URL und gültige OAuth/IMS-Anmeldeinformationen verfügt, damit das Skript den Provider registrieren kann.

Konfigurieren des Versand-Webhooks in Commerce Admin:

• Navigieren Sie Stores > Einstellungen > Konfiguration > Adobe Services > Commerce Webhooks.

• Webhook hinzufügen:

  • Webhook-Methode: plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Webhook-Typ: after
  • URL: die bereitgestellte shipping-methods-Web-Aktions-URL (aus der Bereitstellungsausgabe oder der Adobe Developer Console).
  • Erforderlich: Optional - Dadurch kann das Auschecken weiterhin funktionieren, wenn die externe API keine Raten zurückgibt.

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

Konfigurieren der Admin UI SDK:

• Navigieren Sie in Commerce Admin zu Stores > Einstellungen > Konfiguration.
• Öffnen Sie Adobe Services > Admin-Benutzeroberfläche - SDK.
• Setzen Sie Admin-UI SDK aktivieren auf Ja und klicken Sie auf Konfiguration speichern, falls diese noch nicht aktiviert ist.
• Klicken Sie auf Erweiterungen konfigurieren, wählen Sie den Arbeitsbereich aus, in dem Ihre App bereitgestellt wird, und klicken Sie dann auf Anwenden. Sie können auch die Option Benutzerdefiniert auswählen und den Arbeitsbereichsnamen eingeben.
• Wählen Sie Ihre App Builder App in der Liste aus und speichern Sie sie. Wenn die App nicht angezeigt wird, klicken Sie auf Registrierungen aktualisieren und versuchen Sie es erneut.

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

Konfigurieren Sie die Pseudo-Versandmethode in der Admin-Benutzeroberfläche von Adobe Commerce:

• Öffnen Sie Apps und wählen Sie Ihre App aus.

• Öffnen Sie die Pseudo-" (oder eine entsprechende Option).

• Geben Sie die folgenden Details ein:

  • Service-URL: die Pipedream-Workflow-URL, die Sie kopiert haben (z. B. https://123456.m.pipedream.net).
  • API-Schlüssel Beliebiger nicht leerer Wert für die Nachahmung, z. B. tutorial-key.
  • Warehouse (Lieferadresse):, Telefon, Straße, Stadt, Bundesland, Postleitzahl, Land.

• Klicken Sie Speichern. Die Konfiguration wird im Laufzeitstatus gespeichert und von der Aktion „shipping-methods“ verwendet.

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

Überprüfen an der Kasse: Fügen Sie ein Produkt zum Warenkorb hinzu, gehen Sie zur Kasse und geben Sie eine Versandadresse ein. Sie sollten die Pseudo-Versandoptionen sehen, z. B. Mock Standard und Mock Express.

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