配送方法扩展教程

转到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设置 > 索引和文档，并删除列出的任何文档。

{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包含一个​模拟发货（或类似选项卡），该选项卡具有用于服务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，必需​可选）。

代理会生成必要的代码并提供有关后续步骤(包括安装依赖项、注册模拟运营商、配置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 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中，转到​商店 >设置> 配置。
• 打开​Adobe Services > Admin UI SDK。
• 将​ 启用管理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。
  • 仓库（发货方）地址：​姓名、电话、街道、城市、州/省、邮政编码、国家/地区。

• 单击​保存。 该配置存储在Runtime State中，并由shipping-methods操作使用。

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

结帐时验证：​将产品添加到购物车，转到结帐并输入送货地址。 您应该看到模拟送货选项，例如​ Mock Standard ​和​Mock Express。

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