出荷方法の拡張機能チュートリアル

pipedream.comに移動して、サインアップまたはログインします。

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

トリガーで、HTTP / Webhook​を選択します。

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

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

このURL​をコピーし、Commerce Adminで拡張機能を設定する際に​ サービス 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"}

Cursorのコンテキストにドキュメントが追加されている場合は、そのドキュメントを無効にします。 Cursor > Settings > Cursor Settings > Indexing & Docs​に移動し、リストされているドキュメントをすべて削除します。

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

担当者の質問に正確に答えて、最適なコードを生成できます。 使用するキットまたはテンプレートが必要な場合は、担当者が配送ドメインとAdmin UI SDK拡張機能を使用してcheckout starter kitに転送し、配送Webhookとマーチャント設定画面の両方を実装します。

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

requirements.md （または同等の）ファイルを確認し、プランを確認します。 すべてが正しい場合は、担当者にアーキテクチャプランニングに移動するよう指示します（または​フェーズ 2）。 次のことを確認します。

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

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

エージェントが提供するアーキテクチャプランを確認します。

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

エージェントにコード生成を続行するように指示します。 担当者は、Commerceが返されたメソッドを受け入れることを許可する​ モック ​の通信事業者を配送業者設定に追加し、Webhook メソッド plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_ratesを使用する必要があります（Webhook type after、必須​Optional）。

担当者は必要なコードを生成し、次の手順（依存関係のインストール、モックキャリアの登録、Commerce Webhookの設定、デプロイなど）を詳しく説明します。

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

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

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

Deploy the app.

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

{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を設定します：

• Stores/Settings > Configuration > Adobe サービス > Commerce Webhook​に移動します。

• Webhookを追加します。

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

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

拡張機能Admin UI SDKを設定：

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

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

Adobe Commerce管理UIでモック出荷方式を設定します：

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

• 「Mock Shipping」タブ（または同等のタブ）を開きます。

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

  • サービス 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"}