発送方法拡張のチュートリアル

pipedream.com に移動し、新規登録するかログインします。

新規ワークフロー （または ワークフローを追加）をクリックします。

トリガーには、「HTTP/Webhook」を選択します。

トリガーの設定で、「HTTP 応答」を「ワークフローからカスタム応答を返す に設定します。 これにより、コードステップで JSON 応答のモックを送信できます。

Pipedream は、などの一意の HTTP エンドポイント URLhttps://123456.m.pipedream.net を表示します。

Commerce Admin で拡張機能を設定する際には、この URL をコピー して、サービス URL として使用します。

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

+ アイコンをクリックしてステップを追加します。

「Node.js コードを実行」（コードステップ）を選択します。

デフォルトのコードを次の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 },
   });
},
});

デプロイ をクリックします。

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

コーディングエージェントの MCP 設定に移動します。 例えば、カーソルでは、Cursor/Settings/Cursor Settings/Tools & MCP に移動します。 commerce-extensibility ツールセットがエラーなく有効になっていることを確認します。 エラーが表示された場合は、ツールセットのオン/オフを切り替えます。

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

カーソルのコンテキストにドキュメントを追加した場合は、無効にします。 カーソル/設定/カーソル設定/インデックスとドキュメント に移動し、一覧表示されているドキュメントを削除します。

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

エージェントにモック率 API 仕様へのアクセス権を付与して、クライアントを正しく実装できるようにします。 まだ行っていない場合は、​ モックリレート API 仕様ファイル ​ をダウンロードして開き、.md ファイルをプロジェクト（例：docs/mock-rates-api-spec.md）に追加してから、プロンプトでそのファイルを参照します。

発送方法拡張機能を生成します。

• エージェントのチャットウィンドウで、プラン モードを選択します（使用可能な場合）。 これにより、エージェントが計画なしで続行するのを防ぎます。
• 次のプロンプトを入力します。

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

エージェントが最適なコードを生成できるように、エージェントの質問に正確に答えます。 使用するキットまたはテンプレートを尋ねられた場合は、出荷先ドメインと管理者 UI SDK拡張機能を使用して ​ チェックアウトスターターキット ​ に送ります。これにより、出荷 Webhook とマーチャント設定画面の両方が実装されます。

エージェントは、実装の信頼できる情報源として機能する requirements.md （または同等の）ファイルを作成できます。

requirements.md （または同等の）ファイルを確認し、計画を検証します。 すべてが正しいと思われる場合は、アーキテクチャ計画（またはフェーズ 2 に移行するようエージェントに指示し す。 次のことを確認します。

• shipping-methods アクション（または同等の）がCommerce Webhook を処理し、外部レート API を呼び出します。
• shipping-config （または同等の）アクションは、GET（読み取り設定、API キーがマスクされた）および SET （保存サービス URL、API キー、ウェアハウスアドレス）をサポートします。設定は Runtime State などに安全に保存されます。
• 管理 UI には、サービス URL、API キー（パスワード/マスク）、ウェアハウスのアドレスのフィールドを持つ モック出荷 （または同様の）タブが含まれています。

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

エージェントがアーキテクチャプランを提供したら、レビューします。

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

コードの生成を続行するようにエージェントに指示します。 エージェントは、Commerceが返されたメソッドを受け入れ、Webhook メソッドの （Webhook タイプ afterplugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates、必須 オプション）を使用できるように、配送先設定に モック 配送業者を追加する必要があります。

このエージェントは、必要なコードを生成し、次の手順（依存関係のインストール、モックキャリアの登録、Commerce Webhook の設定、デプロイなど）に関する詳細な概要を提供します。

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

生成されたコードを検証した後、次のプロンプトを使用して拡張機能をデプロイします。

Deploy the app.

エージェントは、デプロイメント前の準備状況を評価します（例えば、管理 UI またはCommerce API が使用されている場合、.env、COMMERCE_WEBHOOKS_PUBLIC_KEY および OAuth/IMS 変数に関する COMMERCE_BASE_URL を確認します）。

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

評価結果に自信がある場合は、エージェントにデプロイメントを続行するように指示します。 エージェントは、MCP ツールキットを使用して、検証、ビルド、およびデプロイを自動的に行います。

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

Commerceへのモックキャリアの登録 （デプロイ後に 1 回実行）:

npm run create-shipping-carriers

.env に COMMERCE_BASE_URL と有効な OAuth/IMS 認証情報が設定されていることを確認し、スクリプトで通信事業者を登録できるようにします。

Commerce Admin での配送 Webhook の設定：

• ストア/設定/設定/Adobe サービス/Commerce Webhook に移動します。

• Webhook を追加します。

  • Webhook メソッド： plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates
  • Webhook タイプ： after
  • URL: デプロイされた shipping-methods web アクション URL （デプロイ出力または Adobe Developer Console から）。
  • 必須：​オプション – 外部 API がレートを返さない場合でも、チェックアウトを引き続き機能させることができます。

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

Admin UI SDK 拡張機能を設定します。

• Commerce Admin で、ストア/設定/設定 に移動します。
• Adobe サービス / 管理 UI SDK を開きます。
• 管理 UI SDKを有効にする を はい に設定し、設定を保存 をクリックします（まだ有効になっていない場合）。
• 「拡張機能を設定」をクリックし、アプリのデプロイ先のワークスペースを選択して、「適用」をクリックします。 また、「カスタム」オプションを選択して、ワークスペース名を入力することもできます。
• リストで App Builder アプリを選択して保存します。 アプリが表示されない場合は、「登録を更新」をクリックして、もう一度試してください。

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

Adobe Commerce管理 UI でのモック出荷方法の設定：

• アプリ を開き、アプリを選択します。

• 「モック出荷」タブ（または同等のタブ）を開きます。

• 次の詳細を入力します。

  • サービス URL: コピーした Pipedream ワークフローの URL （例：https://123456.m.pipedream.net）。
  • API キー： モック用の空でない値（例：tutorial-key）。
  • 倉庫（発送元）住所： 名、電話、住所、市区町村、都道府県、郵便番号、国。

• 保存 をクリックします。 設定はランタイム状態に保存され、shipping-methods アクションで使用されます。

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

チェックアウト時に確認： 買い物かごに商品を追加し、チェックアウトに移動して、配送先住所を入力します。 例えば Mock Standard や Mock Express などのモック配送オプションが表示されます。

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