送貨方法擴充功能教學課程

前往pipedream.com註冊或登入。

按一下​新增工作流程 （或​新增工作流程）。

對於觸發器，請選取​HTTP / Webhook。

在觸發設定中，將​ HTTP回應 ​設定為​從工作流程傳回自訂回應。 如此可讓程式碼步驟傳送模擬JSON回應。

Pipedream顯示唯一的​HTTP端點URL，例如https://123456.m.pipedream.net。

在Commerce管理員中設定擴充功能時，複製此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"}

如果您有任何檔案新增到Cursor的內容中，請將其停用。 瀏覽至​Cursor > 設定 > Cursor設定 > 索引與檔案，並刪除列出的任何檔案。

{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金鑰、倉儲位址），且設定儲存安全，例如在執行階段狀態。
• 管理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型別​after，必要的​Optional）。

代理程式會產生必要的程式碼，並提供您後續步驟(包括安裝相依性、註冊模擬電信業者、設定Commerce webhook和部署)的詳細摘要。

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

驗證產生的程式碼後，請使用以下提示來部署擴充功能：

Deploy the app.

代理程式會執行預先部署整備程度評估(例如，如果使用Admin UI或Commerce API，請檢查.env、COMMERCE_WEBHOOKS_PUBLIC_KEY和OAuth/IMS變數的COMMERCE_BASE_URL)。

Mock Shipping擴充功能的 {width="600" modal="regular"}

當您對評估結果有信心時，請指示代理程式繼續進行部署。 代理程式會使用MCP工具組來自動驗證、建置和部署。

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

在Commerce中註冊模擬電信業者 （部署後執行一次）：

npm run create-shipping-carriers

請確認您的.env具有COMMERCE_BASE_URL和有效的OAuth/IMS認證，讓指令碼可以註冊電信業者。

在Commerce Admin中設定送貨webhook：

• 移至​商店 >設定> 設定 > Adobe服務 > Commerce Webhooks。

• 新增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 Services > 管理UI SDK。
• 將​ 啟用Admin UI SDK ​設為​是，如果尚未啟用，請按一下​儲存設定。
• 按一下​設定擴充功能，選擇您的應用程式要部署的工作環境，然後按一下​套用。 您也可以選取​ 自訂 ​選項並輸入工作區名稱。
• 在清單中選取您的App Builder應用程式並儲存。 如果應用程式未出現，請按一下​重新整理註冊，然後再試一次。

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

在Adobe Commerce管理UI中設定Mock Shipping方法：

• 開啟​ 應用程式 ​並選取您的應用程式。

• 開啟​ 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"}