commercetools-connect

commercetools Connect

以意图为导向，指导构建可用于生产环境的 Connect 应用。本技能讲解能够通过生产就绪审查的决策框架、平台约定和最佳实践，而不是某个连接器的具体代码。它总结了真实连接器中的通用模式（并提醒避开反模式），且每项平台事实都有官方文档作为依据。

**语言范围：**Connect 应用可以使用 JavaScript/TypeScript 或 Java 编写（文档）；create-connect-app 模板支持 JS 和 TS。本技能面向 TypeScript/Node——决策框架、平台约定（超时、确认语义、作用域、生命周期）以及 connect.yaml 指引与语言无关，同样适用于 Java 连接器，但代码片段以及 supertest + msw 测试栈特定于 Node/Express。

**工具链——使用 Connect CLI，不要自行实现。**使用官方 Connect CLI（@commercetools/cli）搭建脚手架、运行和发布。所有 CLI 命令、引导流程和固定的依赖版本都集中在一个地方：Connect CLI 参考文档（connect-cli.md）。Merchant Center 自定义应用/视图是例外：它们使用独立的前端工具链（@commercetools-frontend/*），只有在部署时和目录结构方面才使用 Connect CLI——请参阅 merchant-center-cli.md 和 merchant-center-customizations.md。

工作流

调用本技能时，始终遵循以下步骤：

1. 搜索文档（必需，首先执行）——在某个会话中首次使用本技能时，必须先运行此操作，再作答。它会汇集经过验证的最新文档，作为主要依据，并筛选出本技能涵盖的产品。使用此脚本在使用本技能期间搜索文档；其他内容由 Knowledge MCP 负责。请务必根据检索到的文档确认细节，不要只依据技能文本：

   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   

   仅当上下文中已有 commercetools 项目密钥和区域（例如 api.{region}.commercetools.com）时才传入；否则两者都省略。绝不要搜索文件或向用户索要这些信息。

2. 根据决策框架（如下）选择路径——在编写代码之前，确定应用类型并敲定同步与异步约定。该约定决定几乎所有后续决策。

3. 打开匹配的参考文档（位于 ./references/），并遵循其中的模式和 ## Checklist。

4. 根据生产就绪检查清单（如下）进行把关，然后再宣布连接器已完成。

可选脚本

获取 GraphQL 架构 — 需要了解 commercetools GraphQL 查询或变更的上下文时运行此脚本 — 例如，在编写查询之前检查资源的字段、类型和可用操作，或根据真实架构验证刚生成的 GraphQL 查询/变更。此脚本会获取单个 commercetools 资源的部分 GraphQL SDL：

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出是该资源的 GraphQL SDL。如果无法识别资源名称，脚本会打印有效资源名称列表 — 选择正确的名称并重新运行。注意： SDL 可能包含 存根类型 — 以存根形式呈现的引用资源，并在注释中注明其真实类型名称。如需获取这些类型，请使用对应类型名称作为 --resource-name 重新运行此脚本。

获取 OpenAPI（REST）架构 — 需要了解 commercetools REST 端点、请求/响应负载或更新操作的上下文时运行此脚本 — 例如，在构造请求之前检查资源的 REST 操作，或根据真实规范验证刚生成的 REST 请求/负载。此脚本会获取单个 commercetools 资源的部分 OpenAPI 规范：

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出是该资源的 OpenAPI 规范（YAML）。REST 资源采用读写分离的命名形式（例如 api-Cart-read、api-Cart-write）。如果无法识别资源名称，脚本会打印有效资源名称列表 — 选择正确的名称并重新运行。注意： 该规范不包含引用展开架构 — 如需获取被引用资源的架构，请使用该资源名称作为 --resource-name 重新运行此脚本。

---

步骤 1 — 决策框架：选择哪种应用类型？

一个 Connector 是一个在 connect.yaml 中声明一个或多个应用的代码仓库。请根据代码的调用方式和数据流向为每个应用选择类型，而不是根据它的功能。

首先需要明确两点：

• 方向。 变更的来源是 commercetools（commercetools → 外部系统），还是外部系统（外部系统 → commercetools）？两种情况都很常见，但路由方式不同。
• service 只是一个 HTTP 端点，不一定是 API Extension。 service 应用会公开一个 HTTP 端点。该端点可以注册为 API Extension（commercetools 在操作过程中同步调用），也可以是一个普通的入站 webhook / REST API，由外部系统调用以推送数据。这是两种具有不同契约的模式。

触发条件 / 需求	类型	代码的调用方式	硬性契约
在 commercetools 操作持久化之前阻止或修改该操作（验证购物车、注入税费、拒绝订单）	作为 API Extension 的 service	commercetools 在 API 请求期间同步调用你的端点（注册为 Extension）	Extension 响应时限：默认 2 s，自助服务最长 10 s（可通过支持请求申请提高单个项目的上限，但需经过性能审查）。你的延迟和停机时间将成为平台的延迟和停机时间。
外部系统向 commercetools 推送数据，随源系统变更而更新（系统 A 更新产品 → 将其写入 commercetools）	作为入站 webhook / API 的 service	外部系统调用你的端点	服务请求超时时间为 5-min。你需要验证调用方身份并自行调用 commercetools API；不会注册 Extension。
在 commercetools 变更发生后做出响应（将已确认的订单同步到 WMS、发送电子邮件、为产品建立索引）	event（Subscription 处理程序）	commercetools 将 Subscription 消息发送到队列 → 你的处理程序	至少一次投递，不保证顺序，未确认时会重新投递。必须具备幂等性。
定时或按需批处理（每晚轮询外部系统并写入数据、对账、清理、批量导入）	job	cron 调度器（properties.schedule）	请求在 30 min 后超时。没有并发保护机制 — 需要自行处理锁定。
在 Merchant Center 中添加 UI	merchant-center-custom-application（整页应用）/ merchant-center-custom-view（嵌入式面板）	使用 MC CLI 构建并托管的 React 应用，通过 Connect 部署	单独的前端工具链（@commercetools-frontend/*）+ 配置文件契约；在 connect.yaml 中以 merchant-center-* 应用的形式发布。→ merchant-center-cli.md、merchant-center-customizations.md
提供静态文件 / CDN 包	assets	静态主机	—

单个 Connector 通常会组合多种类型（例如，一个 service API Extension 用于计算购物车税费，以及一个 event 处理程序用于在下单时提交交易；或者，一个 service 入站 webhook 用于实时推送，以及一个 job 用于每晚进行完整对账）。

详细信息和权衡：architecture-decisions.md。

Connector 类型集成子领域

本技能中的构建指南与 Connector 类型无关（适用于任何 service/event/job）。某些 Connector 类型也有专门的端到端子领域，负责该类型的整个工作 — 从“是否已有 Connector？”到配置、分叉或构建 Connector，再到围绕它构建应用后端。这些子领域由与本技能一同发布的 commercetools-integrations 技能负责；下表会直接指向这些子领域，因此请前往对应位置阅读，而不要在此处寻找副本：

连接器类型	涵盖内容	前往
支付（例如 Stripe、Adyen、Mollie、PayPal 等）	自定义店面的完整支付生命周期：判断认证连接器／公共连接器是否适用 → 配置它，或分叉它，或基于支付集成模板启动新连接器 → 构建后端（会话 BFF、授权后的订单、通过处理商捕获／退款／取消、Webhook 对账）；以及调试往返流程	commercetools-integrations: payment/overview.md
税务（例如 Avalara、Vertex、TaxJar 等）	完整的税务集成：判断认证连接器是否适用（Avalara／Vertex 有认证连接器；TaxJar 没有）→ 配置它，分叉它，或基于税务集成模板构建 → 两个应用（在 ExternalAmount 模式下计算税额的购物车 API Extension + 记录／提交交易的 OrderCreated Subscription）；以及沙盒不持久化数据、没有 nexus 意味着税额为零这两个陷阱	commercetools-integrations: tax/overview.md
CRM（例如 Salesforce、HubSpot、Dynamics 365、Zoho 等）	完整的客户关系集成：判断公共连接器是否适用（传统 CRM 通常没有连接器 → 需要构建）→ 配置它，分叉它，或针对你定义的 CRM 构建 → 先选定方向 + 事实来源，再构建由此决定的客户同步应用（向外发送事件的同步器、接收数据的入站 Webhook／轮询、一次性迁移任务），并通过 externalId 关联；以及重复联系人、同步循环和 PII／删除相关陷阱	commercetools-integrations: crm/overview.md
PIM（例如 Akeneo、inriver、Bluestone、Pimcore 等）	完整的商品数据同步任务：判断公共 PIM 连接器是否适用 → 配置它，或分叉它，或自行构建 → 将 PIM 模型映射到 Product Types／属性／类别／媒体，单独处理价格和库存，并选择同步架构（Import API 与 HTTP API、事件 Webhook 与任务）	commercetools-integrations: pim/overview.md
订单管理（OMS，例如 Fluent Commerce、kbrw、OneStock、NewStore、Pipe17）	将 commercetools 连接到 OMS：判断是否安装公共连接器 → 配置它，或分叉／自定义连接器，或针对定制的订单管理服务构建新连接器（基于 fulfilment-integration 模板搭建）→ 设计同步流程（通过 OrderCreated 导出订单、通过入站 Webhook 同步状态／发货／履约、同步库存、运行对账任务）。没有固定的连接器契约；由与类型无关的事件／服务／任务构建端组合而成	commercetools-integrations: order-management/overview.md
ERP（例如 SAP S/4HANA 或 ECC、Microsoft Dynamics 365、Oracle NetSuite、Infor、Odoo、Sage、自建 ERP）	完整的 ERP 集成：“ERP 集成”从来不是单一集成——将商品、价格、库存、客户／B2B、订单和发票界定为各自独立的流程，并分别确定其方向、频率和幂等性，同时确认连接器实际连接的对象（通常是中间件，而不是 ERP）→ 然后询问用户是直接使用公共连接器、通过配置弥补差距、自定义／分叉连接器，还是针对用户指定的 ERP 或中间件端点构建（没有 ERP 模板，但 erp 是一个有效的 IntegrationType，可用于搜索注册表）→ 设计各流程（通过 OrderCreated 导出订单并回写 SyncInfo；通过 Import API 或 HTTP API 导入主数据；库存设置缓冲值／阈值；将 B2B 账户建模为 Business Units／Associates；在订单自定义字段中保存发票）；以及连接性、过时数据覆盖和库存偏差相关陷阱	commercetools-integrations: erp/overview.md
礼品卡（例如 Voucherify、内部商店额度等）	完整的礼品卡集成：判断是直接使用公共连接器（Voucherify）、自定义／分叉连接器，还是针对你定义的礼品卡系统基于礼品卡模板构建新连接器 → 两个应用（启用器 UI + 处理器；处理器会检查余额、兑换金额，并通过会话认证的余额／兑换功能及 Payment Intents 退款／撤销来管理 Payment）；以及必须配合备用方案和示例仅模拟操作这两个陷阱	commercetools-integrations: giftcard/overview.md
电子邮件（例如 SendGrid、Mailgun、AWS SES、Postmark 等）	完整的事务性电子邮件集成：判断现成连接器是否适用（电子邮件集成以模板为先——大多数 ESP 都没有现成连接器）→ 配置它、分叉／自定义它，或基于事务性电子邮件模板构建唯一的 event 应用 → 构建应用（订阅 Customer／Order Messages → 通过 ESP 发送）；为非幂等发送在至多一次与至少一次之间做出关键选择；以及令牌邮件、订单状态筛选和本地化相关陷阱	commercetools-integrations: email/overview.md
Marketplace — 多供应商模式，或在外部 Marketplace 上销售（例如 Marketplacer、Mirakl、Convictional、渠道管理器等）	完整的 Marketplace 集成：确定角色（运营 Marketplace，还是在他人的 Marketplace 上销售）及各领域的方向 → 询问用户是直接使用公共连接器、自定义／分叉连接器，还是针对用户指定的服务构建（大多数 Marketplace 列表都是合作伙伴集成，而且没有 Marketplace 模板）→ 对卖家和商品报价建模（每个卖家对应一个 Channel／Store／CustomObject；每个卖家单独定价并管理库存；共享 SKU 使用一个 Product）→ 构建同步应用（同步卖家和商品报价、导入订单或按卖家路由订单并使用 syncInfo、同步履约状态、执行对账）；以及没有 Channel 的价格、聚合可用性和 Channel 无法删除相关陷阱	commercetools-integrations: marketplace/overview.md
促销／忠诚度（例如 Talon.One、Voucherify、Dovetech、Eagle Eye、NULogic 等）	完整的促销集成：首先排除使用原生 Cart Discounts／Discount Codes／Discount Groups 的方案（第 0 级） → 然后询问用户是直接使用现有公共连接器、自定义／分叉连接器，还是针对用户指定的促销服务构建连接器（没有促销模板）→ 两个应用（通过 setDirectDiscounts 应用促销引擎折扣的购物车 API Extension + 通过 OrderCreated Subscription 兑换折扣并奖励积分）；以及直接折扣会使折扣码失效这一规则，还有重复兑换和废弃购物车相关陷阱	commercetools-integrations: promotion/overview.md
分析 — 导出到数据仓库／CDP／产品分析工具（例如 BigQuery、Snowflake、Redshift、Databricks、Segment、mParticle 等）	完整的分析数据导出：没有现成的分析连接器，也没有 Export API，因此（检查实时注册表后）基于商品导出模板构建（CLI --template product-ingestion）→ 由两个基本组件构成的单向数据导出管道：在 Subscriptions／Messages 上运行的 event 流式处理器（近实时）和／或按 lastModifiedAt 时间窗口查询 API 并使用游标分页的 job（批处理／回填）→ 将事件转换为行，并在目标端按 resource.id+sequenceNumber 去重；还要区分 Platform Insights（APM）和 Change History（治理）、明确客户端跟踪的边界，并留意重复行、事件缺失和 payloadNotIncluded 相关陷阱	commercetools-integrations: analytics/overview.md
搜索／商品发现（例如 Algolia、Constructor、Bloomreach、Coveo、Elasticsearch、Typesense 等）	完整的搜索集成（出站，仅限后端——不使用 API Extension）：首先排除原生 Product Search（第 0 级） → 然后使用公共连接器、分叉现有连接器，或基于商品导出模板搭建（CLI --template product-ingestion）→ 将 Product Projection 映射为扁平搜索文档（价格上下文、本地化、类别反规范化、Store 商品范围）→ 两个应用（以原子方式重建商品目录索引的完整导入 service／job + 针对 ProductPublished／ProductUnpublished／Store 选择 Subscriptions 的增量更新 event）；以及幽灵记录、只重建一半、最终一致性相关陷阱，还有供应商托管的集成并非连接器这一规则	commercetools-integrations: search/overview.md
配送（承运商、比价引擎、标签／配送执行平台，例如 DHL、UPS、FedEx、ShipperHQ、Sendcloud、nShift 等）	完整的配送集成：首先排除原生 Shipping Methods（第 0 级）——区域、基于购物车评分的阶梯费率、谓词，以及冻结 + setCustomShippingMethod 模式已涵盖大多数“动态配送”需求 → 然后询问用户是使用公共连接器（搜索 integrationTypes=shipping）、自定义／分叉现有连接器，还是针对用户指定的配送服务构建连接器（没有 Checkout 配送连接器契约，也没有配送模板，而且大多数供应商提供的是供应商托管的集成）→ 最后确定所有后续设计都取决于的方案：使用原生阶梯费率的 setShippingRateInput，还是使用 setCustomShippingMethod／addCustomShippingMethod；后者不会出现在 matching-cart 中	commercetools-integrations: shipping/overview.md
对于任何支付、税务、CRM、PIM、订单管理、ERP、礼品卡、电子邮件、市场、促销、分析、搜索或配送连接器任务——无论是集成已部署的连接器，还是构建或分叉一个连接器——都从匹配的 overview.md 开始。每条决策路径都会引导你：第 1 级，配置；第 2 级，配置即可弥补差距；第 3 级，分叉；第 4 级，从模板构建（提供商的注意事项见提供商文件——支付/stripe.md、税务/avalara.md、电子邮件/providers.md；CRM 和 PIM 子领域与供应商无关——实时查询连接器；OMS 子领域没有固定的连接器契约，直接组合构建侧内容；ERP 子领域与供应商无关且涵盖多个数据领域——它会按数据领域拆分请求，在任何设计开始前明确中间件边界，并且没有模板，因此订单导出使用 fulfilment-integration 搭建，主数据导入使用纯起始模板搭建（product-ingestion 是形状为导出的模板——它是入站加载的错误对应模板）；礼品卡子领域有一个公开连接器（Voucherify），以及一条为内部系统从模板构建的路径；市场子领域与供应商无关且没有模板——根据当前仓库评估任何分叉候选项；促销子领域有两个公开的 MIT 集成且没有模板——促销/public-connectors.md 会指出哪个制品才是真正用于生产的版本；分析子领域没有开箱即用的连接器，也没有 Export API——它仍要求实时检查注册表，然后从 Product 导出模板构建定向出站管道（--template product-ingestion）——分析/destinations.md 会为数据仓库/CDP/产品分析/BI 决策指路；搜索子领域与供应商无关，首先检查原生 Product Search，并从 Product 导出模板搭建出站构建（--template product-ingestion，即上文提到的同一个对应模板）；配送子领域与供应商无关，首先检查原生 Shipping Methods，没有 Checkout 连接器契约，也没有模板——shipping 是可用于查询注册表的有效 IntegrationType，但没有任何规范规定连接器的形态，因此使用 tax-integration 和/或 fulfilment-integration 搭建）。它只会在涉及深层、与类型无关的发布/认证生命周期以及生产就绪门槛时，才交回给构建侧工作流，并引用上文内容。

促销、搜索和配送子领域各自都有第 0 级。 commercetools 提供自有折扣引擎（Cart Discounts、Discount Codes、Discount Groups）、自有搜索（Product Search），以及自有配送模型（Zones、Shipping Methods、基于 shippingRateInput 的分级费率、谓词），因此，在这三个领域中，“是否真的需要连接器？”确实是一个需要考虑的问题，而支付、税务和其他领域则并非如此——在推荐连接器之前，务必明确排除原生功能的可能性。

每个子领域都位于 commercetools-integrations 技能中，在各自的 overview.md 下，归入 references/<type>/——这里仅保留一个由该技能维护的规范版本，并在此处提供链接。之后如需新增连接器类型，只需在该技能中添加一个同级目录树，并在上表中新增一行；构建侧指南无需更改。

市场列表中的集成并非都是 Connect 连接器——推荐前请先核实

每当某个子领域要求你检查 commercetools marketplace 是否有现成连接器时，无论连接器类型或供应商如何，都应遵循以下规则：

• 市场可作为发现渠道，但其中列出的集成不一定是 commercetools Connect 连接器——合作伙伴运营的服务、SaaS 产品和 iPaaS 中间件，都会与可部署的 Connect 应用一起出现。市场信息也可能与实际的 Connect 连接器注册表不同步（某个列表可能对应无法通过 Connect 部署的项目，或版本有所不同），而且任何特定供应商（Akeneo、Stripe 等）在任何时候都可能有列表，也可能没有——切勿假设某个具名连接器一定存在。
• 在推荐候选项供用户安装、配置或分叉之前，务必再次确认它确实是 commercetools Connect 连接器：查看是否具备 Connect 相关依据（公开的连接器代码仓库、connect.yaml 或 Connect 部署操作），并以 Connect CLI / 连接器注册表为准，而非营销列表。
• 然后询问用户想怎么做——不要擅自替用户决定。说明适配情况以及是否可通过 Connect 部署。
• 如果用户想使用非 Connect 集成，请提醒他们本技能不涵盖非 Connect 连接器的使用方法——本技能中的构建、配置和部署模式（connect.yaml、Connect CLI、生命周期脚本、Connect 部署模型）不适用。请引导他们参考供应商或合作伙伴自己的入门流程，并提供本技能内的替代方案：构建或分叉一个 Connect 连接器。

每个子领域一开始就列出可选路径——不要等用户询问

当请求指向上述任一子领域时，用户已经告诉你想集成什么，但没有告诉你如何集成，你也不应擅自假设。因此，在收集需求、配置或编写代码之前，先列出可选路径，让用户选择：

0. 优先考虑原生功能；如果存在第 0 档，就从这里开始（促销、搜索、配送；ERP 也有类似的判断环节）。如果 commercetools 已经提供该功能，就明确说明并停止。不要围绕平台已有的功能设计方案。
1. 原样部署现有的公开连接器——必须基于实时注册表/市场查询结果，而非凭记忆，并按照上述规则确认它可通过 Connect 部署。
2. 分叉并修改现有连接器——仅当存在无法通过配置弥补的实际差距时采用。
3. 新建连接器——基于该子领域的模板构建；如果没有模板，则使用与类型无关的 service / event / job 模式。

说明你推荐哪一档以及原因，然后请用户选择。这些方案的工作量差别很大，决定权在用户，而不是你。

在你对该子领域的首次实质性回复中主动执行此流程——尤其是用户的说法已经听起来像是预设了答案时。用户说“帮我构建一个 X 集成”“将 Y 同步到 commercetools”或提到自己已经在使用的服务，都不意味着可以跳过这套流程：用户说“构建”通常只是想“让它能用”，如果已有可安装的方案，他们通常会乐于采用。如果你确实无法在没有更多信息的情况下评估适配情况，可以先问一两个澄清问题，但不要让需求收集拖延对现有方案的介绍——尽早列出已有选项，再根据需求决定采用哪一档。

每个子领域的 overview.md 都包含完整且有序的判断流程（其步骤 1.4/1.5），其中列有适配标准和可用于构建的模板。这是所有子领域都必须遵循的规则。

第 2 步 — 构建前先评估契约的代价

代价高昂的错误，往往源于没有评估刚刚选定的契约：

• service 作为 API Extension 会使你的可用性和延迟与 commercetools 操作耦合。扩展缓慢或不可用，会导致购物车和订单变慢，甚至无法使用。因此，需要设置一个低于扩展超时时间的严格出站超时，审慎决定失败时开放还是关闭，并尽量减少热路径上的工作（跳过冗余的外部调用）。
• service 作为入站 webhook 不会与 commercetools 操作耦合（适用的是 5 分钟的服务超时，而不是 2 秒的扩展时限），但一切都由你负责：验证调用方身份、校验载荷，并确保写入操作幂等（同一产品更新可能会到达两次）——按键执行 upsert，不要盲目创建。确定写入失败时返回什么，以便调用方安全地重试。
• 异步（event） 以即时性换取韧性，但你需要处理至少一次投递、无顺序保证和重新投递。因此，需要使用稳定标识符作为幂等键，返回可安全处理重新投递的确认响应（对于“不再发送”的消息返回 2xx），根据 ID 重新获取资源，而不是信任可能已过期或被省略的载荷，并过滤自身引发的更改以避免循环。
• job 需要自行预留调度余量、锁定重叠任务，并使用可在重启后安全恢复的检查点；每个工作单元都必须幂等，以免重新运行或任务重叠造成重复写入。

如果你无法分别用一句话说明延迟预算（扩展）、幂等策略（入站 webhook / event / job）以及失败和重试行为，就还没有准备好编写处理程序。

---

生产就绪检查清单（准入门槛）

只有所有适用项都满足，连接器才算完成。每项都对应一个包含实现模式的参考文档。

可靠性

• 已说明并实现幂等策略 — 采用无状态方式。 通过目标系统自身的幂等机制、重新获取 commercetools 资源并重新检查其状态，或按稳定键执行 upsert，确保重复处理消息时不产生操作 — 绝不使用本地去重存储。→ event-applications.md
• 返回可安全处理重新投递的响应。 对于已处理和无关但已确认的消息，事件端点返回肯定确认（102/200/201/202/204）；任何不是 102、200、201、202 或 204 的响应都会触发重试。→ event-applications.md
• 按 ID 重新获取，不要信任载荷。 处理程序通过 resource.id 获取当前资源；设置 payloadNotIncluded 时必须这样做。→ event-applications.md
• 尽量减少热路径上的工作（同步）。 当相关数据未更改时，扩展会跳过外部调用（例如，通过存储的哈希判断），并尽早短路返回。→ service-applications.md

安全性

• 对入站端点进行身份验证。 服务扩展注册的目标，其 authentication.type 应为判别值 AuthorizationHeader——而不是架构中的类型名称 AuthorizationHeaderAuthentication，否则会报错 InvalidJsonInput——（或 AzureFunctions），并且在应用内验证该密钥。来自外部系统的 Webhook 应验证完整的 JWT（签名、颁发者、受众、主题、过期时间、算法）。如果 postDeploy 遇到此拼写错误，可能不会显示部署失败，因此请通过 GET /{projectKey}/extensions 确认扩展确实已注册。→ security.md、service-applications.md 模式 1
• 遵循最小权限原则设置 CT 作用域。 使用 inheritAs.apiClient.scopes，只包含应用所需的作用域（例如 manage_orders、manage_subscriptions、manage_extensions），不要使用管理员客户端或 manage_project 客户端。→ security.md
• 将密钥存储在 securedConfiguration 中。 API 密钥、客户端密钥、JWT 密钥绝不应放在 standardConfiguration 中，也绝不应硬编码。→ security.md
• 响应中不得包含堆栈跟踪或密钥。 错误中间件在生产环境中应返回通用消息。→ security.md

正确性

• 验证信封。 根据注入的目标类型解码信封——根据 CONNECT_SUBSCRIPTION_DESTINATION 进行分支处理（Pub/Sub：message.data 为 base64；SNS 有自己的信封）——然后在处理前依次验证（→ JSON → 资源引用 → notificationType）；拒绝格式错误的信封。→ event-applications.md
• 筛选消息类型。 仅订阅所需的消息类型；对其他任何消息（包括平台的测试消息和订阅消息）都予以确认并忽略。→ event-applications.md
• 筛选自身变更。 连接器自身执行的更新不应再次触发连接器，形成循环。→ event-applications.md
• 路由路径与 connect.yaml 中的 endpoint 一致。 Express 路由器挂载在与应用 endpoint 相同的基础路径上（例如 endpoint: /service ↔ app.use('/service', router)），否则平台流量会收到 404。→ project-structure.md
• 固定 SDK 和客户端版本。 JS/TS：@commercetools/platform-sdk@^8 + @commercetools/ts-client@^4（不要使用旧版 @commercetools/sdk-client-v2）。Java：spring-boot-starter-parent 3.5.15+ 和 commercetools Java SDK 19+。端到端使用类型，不使用 any 逃逸，并在边界处完成映射。→ connect-cli.md (Step 3)。

可观测性

• 使用带关联 ID 的结构化日志。 每条请求的日志行都应包含消息/资源关联键（扩展使用 X-Correlation-ID，事件使用 resource.id + sequenceNumber）。→ observability-operations.md
• 健康检查端点。 类似 /status 的路由应在存活状态下返回 200。→ observability-operations.md

运维

• 生命周期脚本具备幂等性。 postDeploy 通过先查询再更新来创建资源（仅在资源不存在时才创建），绝不盲目删除后重建。preUndeploy 负责清理资源。→ lifecycle-scripts.md
• 部署时验证依赖项。 postDeploy 会测试连接外部服务，并立即显示无效凭据。→ lifecycle-scripts.md
• 记录故障时放行与故障时拒绝的处理方式。 README 按使用场景说明外部依赖不可用时会发生什么，并为出站调用设置超时预算。→ service-applications.md
• 毒消息／重放操作手册。 说明如何处理反复失败的消息（移入 DLQ／保留期结束后丢弃），以及如何重放。→ observability-operations.md

质量

• 测试覆盖真实行为，并通过 commercetools connect application test 运行。 至少包括：参数化的认证拒绝矩阵（缺失／过期／签发者错误／受众错误／alg:none）、信封／确认边缘情况（事件），或纯业务逻辑和响应操作（服务）、幂等性／重复投递测试，以及具备幂等性的 postDeploy 注册测试。仅有几个正常流程测试并不足够。→ testing.md
• 没有死代码，不使用 any 逃避类型检查。 不保留已注释掉的代码块；端到端保留 SDK 类型。→ project-structure.md
• 使用 Connect CLI 搭建并运行。 通过 commercetools connect init 创建项目；commercetools connect validate 验证通过。→ connect-cli.md (Step 2)

生成的连接器文档

• 连接器附带 README，说明故障时放行／故障时拒绝的处理方式、所需作用域、配置表（包含每个 connect.yaml 键），以及毒消息／重放操作手册。→ deployment-installation.md

---

参考索引

关注点	参考资料
Connect CLI 操作：安装/身份验证、connect init 模板、固定版本、构建/测试/验证、暂存/预览/发布/部署命令	connect-cli.md
Merchant Center CLI：使用 create-mc-app 搭建脚手架；使用 mc-scripts 运行/构建/提供服务/登录/配置同步；固定 @commercetools-frontend/* 版本	merchant-center-cli.md
自定义应用与自定义视图；配置文件约定；本地开发/测试；通过 Connect 部署（connect.yaml 中的 merchant-center-* 类型、操作顺序）	merchant-center-customizations.md
同时包含连接器和店面的单体仓库：根目录同级布局、为何不使用 npm workspaces、两种独立的部署生命周期	monorepo-with-storefront.md
event、service 与 job 的区别；同步与异步约定的成本	architecture-decisions.md
CLI 脚手架与本地开发、单体仓库布局、客户端设置（ts-client）、connect.yaml 结构、路由与端点匹配、快速失败式环境验证	project-structure.md
订阅：信封、确认语义、幂等性、重新投递、重新获取、注入的订阅目标（Pub/Sub 或 SNS）	event-applications.md
API 扩展：经过身份验证的注册、触发器、超时预算、故障开放/关闭、热路径	service-applications.md
定时/按需任务：计划、超时、并发、检查点	job-applications.md
部署后/取消部署前：幂等注册、架构即代码、部署时验证	lifecycle-scripts.md
端点身份验证、最小权限范围、securedConfiguration、错误处理规范	security.md
结构化日志与关联 ID、运行状况、功能标志、运行手册、DLQ	observability-operations.md
身份验证/信封测试矩阵、supertest + msw 模式、模拟内容	testing.md
connect.yaml 配置、沙盒→预览→发布、安装、重新部署、认证、区域、CLI	deployment-installation.md

集成已部署的支付连接器（子领域）

从概览开始；它会引导你查看其余内容（集成、配置、分叉，或构建新的连接器）。另请参阅上方的连接器类型集成子领域部分。

关注事项	参考资料
从这里开始 — 侧重后端的工作流：需求 → 是否足以使用认证连接器 → 配置 → BFF/订单/捕获-退款/ Webhook	commercetools-integrations: payment/overview.md
认证连接器是否足够？使用实时市场和文档数据，对照公共连接器评估用例是否适用	commercetools-integrations: payment/connector-selection.md
需求 → connect.yaml 配置映射，附完整示例	commercetools-integrations: payment/config-from-requirements.md
后端：会话/BFF、支付后的订单、通过处理器捕获/退款/取消、Webhook 对账、谁拥有支付	commercetools-integrations: payment/backend-integration.md
先编写测试来试运行后端：针对各个部分断言还是模拟，以及作为回归测试的不变量	commercetools-integrations: payment/backend-tdd.md
针对已部署的真实连接器和测试卡进行全流程集成测试	commercetools-integrations: payment/integration-test.md
与服务提供商无关的前端契约：会话正文、enabler 加载、处理器路由及认证、常见问题目录	commercetools-integrations: payment/connector-contract.md
Stripe 相关细节：connect.yaml 的确切键和默认值、enabler bundle、测试卡、Webhook 设置	commercetools-integrations: payment/stripe.md
部署公共支付连接器（CLI 身份验证、作用域、deployment create，而非 connectorstaged）	commercetools-integrations: payment/deploy-public-connector.md
部署分叉/自定义支付连接器（connectorstaged → publish → deployment create）	commercetools-integrations: payment/deploy-custom-connector.md
验证往返流程；使用一次性测试工具验证已部署的连接器	commercetools-integrations: payment/verification.md、commercetools-integrations: payment/test-harness.md

集成或构建税务连接器（子领域）

从概览开始；概览会引导你完成后续步骤（配置已认证的连接器、派生现有连接器，或使用模板构建两个应用）。另请参阅上文的连接器类型集成子领域部分。

关注点	参考资料
从这里开始 — 双应用工作流：需求 → is-a-certified-connector-enough → 配置 → 计算 + 记录	commercetools-integrations: tax/overview.md
已认证的连接器是否够用？按引擎说明（Avalara/Vertex 已认证；TaxJar 使用模板构建），依据实时 Marketplace 数据	commercetools-integrations: tax/connector-selection.md
需求 → connect.yaml：税务模式（ExternalAmount 与 External）、nexus、税码来源、免税、权限范围；示例	commercetools-integrations: tax/config-from-requirements.md
双应用契约：计算器 API Extension（全部四种税务操作、200 而非 202、失败模式、减少调用）+ 订单同步器 Subscription（提交/作废/退款、幂等性）；完整的陷阱目录	commercetools-integrations: tax/tax-contract.md
Avalara 实际依据（来自已认证的开源连接器）：确切的键、AvaTax createTransaction 的报价与提交、税码/实体用途映射、MC 配置应用 — 另以 TaxJar 作为使用模板构建的对照	commercetools-integrations: tax/avalara.md
验证往返流程：购物车上的 taxedPrice、已记录的交易；沙盒不持久化和无 nexus 即税额为零这两个陷阱	commercetools-integrations: tax/verification.md

集成或构建 CRM 连接器（子领域）

从概览开始；概览会引导你完成后续步骤（配置公开连接器、派生现有连接器，或为你定义的 CRM 构建连接器）。另请参阅上文的连接器类型集成子领域部分。

关注点	参考资料
从这里开始 — 同步工作流：需求 → 方向 + 事实来源 → is-a-public-connector-enough → 配置 → 构建同步应用	commercetools-integrations: crm/overview.md
公开连接器是否够用？为何经典 CRM（Salesforce/HubSpot/Dynamics/Zoho）通常需要从头构建；实时 Marketplace 检查；层级路径	commercetools-integrations: crm/connector-selection.md
需求 → connect.yaml：方向 → 应用组成、事实来源、通过 externalId/Custom-Field 关联、最小权限范围、安全配置；示例	commercetools-integrations: crm/config-from-requirements.md
同步契约：出站事件同步器、入站 webhook/轮询、迁移任务；按 externalId 幂等 Upsert、按 ID 重新获取、确认语义、自身变更/循环过滤、删除/PII；完整的陷阱目录	commercetools-integrations: crm/crm-contract.md
验证往返流程：通过 externalId 关联记录、增量变更仅传播一次、删除会传播；循环 / 速率限制 / 沙盒陷阱	commercetools-integrations: crm/verification.md

将 PIM 同步到 commercetools（子领域）

从概览开始；它会引导你了解其他内容（使用公开连接器、进行配置、分叉，或自行构建）。另请参阅上文的连接器类型集成子领域部分。

关注事项	参考资料
从这里开始——以同步为重点的工作流：需求 → 公开连接器是否足够？→ 配置/分叉/构建 → 数据映射 → 验证	commercetools-integrations: pim/overview.md
公开 PIM 连接器是否足够？实时检查市场、具名连接器、适配维度、配置/分叉/构建的选择路径	commercetools-integrations: pim/connector-selection.md
数据映射（核心内容）：Product Type 策略（绝不能与 PIM 产品系列一一对应）、属性映射、本地化、类别、媒体、价格/库存分离、键与幂等性	commercetools-integrations: pim/data-mapping.md
构建或分叉连接器：Import API 与 HTTP API、service webhook 与 job、全量与增量、幂等 upsert、依赖关系解析、删除处理	commercetools-integrations: pim/build-connector.md
测试并安全运行同步：映射单元测试，然后在限定范围的沙盒中运行实时同步，并预先统计项目数量、设置大型目录门槛以及重新运行以验证幂等性（绝不使用生产凭证）	commercetools-integrations: pim/testing.md

订单管理（OMS）连接器（子领域）

从概览开始；它会引导你了解其他内容（使用公开连接器、自定义/分叉现有连接器，或为定制 OMS 构建新连接器），并将同步设计应用于所有路径。另请参阅上文的连接器类型集成子领域部分。

关注事项	参考资料
从这里开始——同步方向与事实来源、需求 → 使用/配置/分叉/构建的选择路径，以及导出/入站/对账工作流	commercetools-integrations: order-management/overview.md
公开 OMS 连接器是否足够？实时适配性检查与市场连接器对比；可安装的 Connect 连接器与供应商托管集成的区别	commercetools-integrations: order-management/connector-selection.md
同步设计：导出（OrderCreated 上的 event）、入站（service webhook）、对账（job）；要订阅哪些 Messages；OMS 状态 → CT 状态映射；各流程的幂等性	commercetools-integrations: order-management/sync-architecture.md
为用户自定义的 OMS 构建新连接器（第 4 级）：搭建框架、声明哪些应用、连接 OMS API、从模板复用哪些内容	commercetools-integrations: order-management/build-oms-connector.md

OMS 连接器没有固定的运行时契约，因此构建部分会组合使用上述与类型无关的 event/service/job 参考资料（使用 fulfilment-integration CLI 模板搭建框架）；部署使用 deployment-installation.md，而非特定子领域的流程。

集成或构建 ERP 连接器（子领域）

从概览开始；它会引导你查看其余内容。两件事决定了整个设计，而且在编写任何代码之前都必须先考虑：“ERP 集成”绝不是单一集成（产品、价格、库存、客户/B2B、订单、发票都是独立流程，符合有文档记录的最佳实践），并且连接器的对接方通常是中间件（SAP Cloud Integration、Boomi、MuleSoft、云 API 网关），而不是 ERP 本身——如果 ERP 只能在企业网络内部响应，Connect 应用就无法访问它。没有 ERP 模板，不过 erp 确实是有效的 IntegrationType，可用于搜索注册表；ERP 市场列表尤其常见的是中间件内容或由合作伙伴托管的集成——请参阅并非所有市场列表都是 Connect 连接器。范围边界：来自 PIM 的产品内容属于 pim；履约、发货和订单状态回写属于 order-management。

关注事项	参考资料
从这里开始——工作流：确定领域范围 → rung-0（是否根本不需要复制？）→ 需求 → 按领域选择使用/配置/分叉/构建 → 配置 → 各项流程 → 验证；需要预先说明的三个事实，以及与 PIM、OMS、CRM 和税务的边界	commercetools-integrations: erp/overview.md
使用、配置、分叉还是构建？实时检查 integrationTypes=erp 注册表、四种列表类型（连接器、中间件内容、供应商/SI 托管、加速器）、按领域进行的适配性检查、评估分叉候选项的方法，以及每项流程应从哪个模板搭建	commercetools-integrations: erp/connector-selection.md
契约（编码前阅读）：各流程的触发条件 + 写入 API + 幂等键，涵盖订单导出（OrderCreated、SyncInfo/自定义字段回写）、主数据入站（Import API 与 HTTP API、每个请求 20 条、48 小时引用解析）、库存（绝对数量、供应 Channels、缓冲/阈值、最终一致性）、客户/B2B 和发票回写；连接性、运行时预算、排序和循环限制；完整的常见陷阱目录	commercetools-integrations: erp/erp-contract.md
字段映射：键和标识（material → SKU，Order 上没有 externalId）、金额和舍入、价格条件 → Price 范围（嵌入式或独立式）、计量单位和包装规格、分类和税务类别、ERP 账户层级 → Business Units/Associates、订单负载、发票——以及映射表为何应存放在配置或 CustomObjects 中	commercetools-integrations: erp/data-mapping.md
需求 → connect.yaml：每项流程一个应用、ERP/中间件端点 + 凭证、计划任务和批次大小、地点→Channel 映射、缓冲/阈值、各领域的最小权限范围、实际的 postDeploy 工作（Channels、Types、Subscription、状态容器、凭证验证）；完整示例	commercetools-integrations: erp/config-from-requirements.md
按流程验证：Order → 销售订单且仅创建一次并建立关联，主数据可重复运行且导入轮询直至完成，库存收敛和阈值行为，B2B 层级和合同价格，发票回写；需要强制触发的故障路径，以及异步导入/最终一致性/过期数据覆盖陷阱	commercetools-integrations: erp/verification.md
ERP 连接器没有固定的运行时契约，因此构建端会组合上文中与类型无关的 event/service/job 引用；部署请使用 deployment-installation.md，而不是特定子领域的流程。

集成或构建礼品卡连接器（子领域）

从概览开始；它会引导你了解其余内容（直接使用公开连接器、自定义或分叉一个连接器，或从礼品卡模板构建新连接器）。另请参阅上文的连接器类型集成子领域部分。

关注事项	参考资料
从这里开始 — 双应用工作流：需求 → 使用/自定义/构建 → 配置 → 余额 + 兑换 + 退款	commercetools-integrations: giftcard/overview.md
使用/自定义/构建？选择路径（Voucherify 公开连接器；内部从模板构建）、用于 PoC 的示例连接器、通过实时市场数据	commercetools-integrations: giftcard/connector-selection.md
需求 → connect.yaml：CT 连接配置块 + JWKS/颁发者、货币、礼品卡系统凭据、最小权限范围；示例详解	commercetools-integrations: giftcard/config-from-requirements.md
双应用契约：启用器（由会话驱动的 UI）+ 处理器（余额/兑换使用会话身份验证，Payment Intents modifyPayment 退款/冲正）、部分支付/多张卡、幂等性、始终与备用方案配对；完整的陷阱目录	commercetools-integrations: giftcard/giftcard-contract.md
验证完整流程：余额 → 兑换 → Payment 交易 → 备用方案补足余款 → 退款/冲正；仅模拟操作的示例和缺少备用方案的陷阱	commercetools-integrations: giftcard/verification.md

集成或构建电子邮件连接器（子领域）

从概览开始；其中会引导你查看其他内容（配置现成的连接器、分叉并自定义一个连接器，或根据事务性电子邮件模板构建单事件应用）。另请参阅上文的连接器类型集成子领域部分。这是一个纯 event 应用，因此基于 event-applications.md 构建。

关注点	参考资料
从这里开始 — 单应用工作流：需求 → 现成连接器是否够用 → 配置 → 发送并验证	commercetools-integrations: email/overview.md
现成连接器是否够用？配置与分叉/自定义/从模板构建之间的选择；电子邮件为何优先采用模板；实时市场检查	commercetools-integrations: email/connector-selection.md
需求 → connect.yaml：要订阅哪些 Messages、ESP 密钥和每封电子邮件对应的模板 ID、发件人、仅限于正在使用的电子邮件的最小权限作用域；完整示例	commercetools-integrations: email/config-from-requirements.md
单应用契约：订阅注册和消息→电子邮件路由；针对非幂等发送，在至多一次与至少一次之间进行选择；令牌电子邮件（≤60 min）的注意事项；订单状态筛选、本地化、PII；完整的问题目录	commercetools-integrations: email/email-contract.md
ESP 具体说明：SendGrid / Mailgun / AWS SES / Postmark 的发送调用形式、ESP 托管模板、幂等键；提供商对比	commercetools-integrations: email/providers.md
验证往返流程：针对每个事件的检查；未订阅和沙盒不会实际投递的问题；重复/静默丢弃的症状	commercetools-integrations: email/verification.md

集成或构建 Marketplace 连接器（子领域）

从概览开始；其中会指引你了解其他内容（直接使用公开连接器、自定义或分叉现有连接器，或者为用户定义的 Marketplace 服务构建连接器）。另请参阅上文的连接器类型集成子领域部分。Marketplace 列表中的项目尤其常常并非 Connect 连接器——推荐之前，请先查看Marketplace 列表中的项目并非都是 Connect 连接器。

关注点	参考资料
从这里开始——工作流：明确“Marketplace”的含义 → 按领域确定角色和方向 → 选择路径 → 建模卖家和商品 → 构建同步应用	commercetools-integrations: marketplace/overview.md
选择路径——询问用户：直接使用公开连接器、自定义或分叉现有连接器，还是为其服务构建连接器；检查当前列表，并根据候选分叉项目的当前仓库（connect.yaml、处理程序、映射）对照生产准入标准进行评估	commercetools-integrations: marketplace/connector-selection.md
卖家与商品建模及 connect.yaml：每位卖家对应的 Channel/Store/CustomObject、商品键、按卖家划分的价格和库存范围、订单导入与 syncInfo、限制设计的 Project 限制、作用域；附示例	commercetools-integrations: marketplace/config-from-requirements.md
同步契约：卖家同步、商品/库存/价格同步、订单导入与按卖家路由、履约状态、对账任务；按 Marketplace ID 幂等更新或插入、拆分多卖家订单；完整的陷阱清单	commercetools-integrations: marketplace/marketplace-contract.md
验证往返流程：卖家可用、商品可按卖家销售、订单仅导入或路由一次、多卖家订单拆分；无 Channel 的价格、聚合可用性、限流以及无法删除的 Channel 等陷阱	commercetools-integrations: marketplace/verification.md

集成或构建促销 / 忠诚度连接器（子领域）

从概览开始；它会引导你了解其余内容（先排除原生折扣，然后使用公共连接器、自定义 / 分叉连接器，或为自己的引擎构建连接器）。另请参阅上文的连接器类型集成子领域部分。

关注点	参考资料
从这里开始 — 工作流：需求 → 原生还是连接器 → 使用 / 自定义 / 构建 → 配置 → 评估 + 兑换	commercetools-integrations: promotion/overview.md
原生、使用、自定义还是构建？第 0 级原生检查（购物车折扣 / 折扣码 / 折扣组）、实时市场操作流程、各引擎概况，以及为什么没有促销模板	commercetools-integrations: promotion/connector-selection.md
需求 → connect.yaml：折扣如何应用到购物车（setDirectDiscounts、负数自定义行项目或由引擎管理的代码）；优惠券代码自定义字段、作用域；完整示例	commercetools-integrations: promotion/config-from-requirements.md
两个应用的约定：评估器（效果→操作映射、万分比、拒绝优惠券代码但不导致购物车失败、200 而非 202、失败时放行、减少调用、与税务扩展串联）+ 兑换同步器（兑换 / 回滚、幂等性、会话身份）；完整陷阱目录	commercetools-integrations: promotion/promotion-contract.md
实际应使用哪个公共集成 — Talon.One 的 Connect 连接器由第三方提供，而供应商自己的仓库是 PoC 加速器；Voucherify 的是移植版本，并非安装包 — 以及分叉时要应用的 commercetools 端修复	commercetools-integrations: promotion/public-connectors.md
验证往返流程：购物车中的 directDiscounts、引擎中的兑换；无效折扣码、零折扣、失败时放行自我修复和购物车合并等陷阱	commercetools-integrations: promotion/verification.md

集成或构建分析连接器（子领域）

从概览开始；其中会引导你了解其余内容（运行实时注册表检查，然后基于 Product 导出模板构建单向出站数据管道，CLI --template product-ingestion）。另请参阅上文的连接器类型集成子领域部分。目前没有开箱即用的分析连接器，也没有 Export API，因此需要组合使用与类型无关的 event/job 构建端（event-applications.md、job-applications.md）。

关注点	参考资料
从这里开始 — 出站工作流：需求 → 是否只需连接器（无论如何都要进行实时检查）→ 管道设计 → 先测试再构建；区分 commerce analytics 与 Platform Insights + Change History；明确客户端侧的边界	commercetools-integrations: analytics/overview.md
连接器是否足够？即使预计需要构建，也必须进行实时注册表/市场检查；CDP/ELT 加载器如何改变判断；配置/分叉/基于 Product 导出模板构建的阶梯式方案	commercetools-integrations: analytics/connector-selection.md
需求 → connect.yaml：选择哪些 Messages / 作业计划、最小权限的读取范围、在 securedConfiguration 中填写目标凭据；附带示例	commercetools-integrations: analytics/config-from-requirements.md
管道（核心内容）：事件流处理器（订阅→解码→重新获取→转换→交付）+ 批处理/回填作业（lastModifiedAt 时间窗口 + 游标分页 + 检查点）；事件→行转换、目标端去重（resource.id+sequenceNumber/version）、payloadNotIncluded 重新获取、PII/GDPR、各种限制；完整的陷阱目录	commercetools-integrations: analytics/pipeline-architecture.md
目标：数据仓库 vs CDP vs 产品分析 vs BI — 流式与批处理、数据流向、PII 影响；订阅代理；坦诚说明 GA4/Mixpanel 优先在客户端侧处理的注意事项	commercetools-integrations: analytics/destinations.md
验证往返流程：一项更改 → 一行数据（无重复），批处理窗口可幂等加载；无订阅/重复行/payloadNotIncluded/查询默认关闭等陷阱	commercetools-integrations: analytics/verification.md

集成或构建搜索连接器（子领域）

从概览开始；其中会引导你查看其他内容（先排除原生 Product Search，然后使用公开连接器、分叉一个连接器，或使用 Product 导出模板为你的引擎搭建脚手架——CLI --template product-ingestion）。它是仅出站的后端集成——不使用 API Extension。另请参阅上文的连接器类型集成子领域部分。引擎自身通过仪表板配置的集成（例如“适用于 commercetools 的 Algolia”）通常并不是 Connect 连接器——在推荐之前，请先参阅 Marketplace 列表并不都是 Connect 连接器——推荐前请先验证。

关注点	参考资料
从这里开始 — 工作流：第 0 级原生功能检查 → 需求 → 使用／分叉／构建 → 数据映射 → 两个应用 → 验证	commercetools-integrations：search/overview.md
原生、使用、分叉还是构建？第 0 级原生搜索检查（Product Search）、实时市场检查、供应商托管集成陷阱，以及使用 Product 导出模板搭建脚手架（--template product-ingestion）	commercetools-integrations：search/connector-selection.md
需求 → 搜索文档和 connect.yaml：两个应用（完整数据导入 + 增量更新器）、索引／引擎键、只读最小权限范围、安全配置；完整示例	commercetools-integrations：search/config-from-requirements.md
数据映射（核心内容）：Product Projection → 扁平文档、objectID 键控、记录粒度、价格上下文激增、本地化、类别反规范化、Store 商品组合、可用性边界	commercetools-integrations：search/data-mapping.md
两个应用的约定：完整数据导入（游标分页、原子／蓝绿重建索引、数量检查）+ 增量更新器（幂等 upsert、删除传播、过时数据保护）；完整陷阱目录	commercetools-integrations：search/search-contract.md
验证同步：发布后内容可见、取消发布／删除后内容消失、完整加载数量匹配、重复运行保持幂等、按 Store 限定范围；最终一致性、可用性偏移和非原子重建陷阱	commercetools-integrations：search/verification.md

集成或构建配送连接器（子领域）

从概览开始；它会指引你了解其余内容（先排除原生配送方式，然后使用公共连接器、定制／分叉现有连接器，或为用户指定的承运商或费率服务构建连接器）。Checkout 没有配送连接器契约，也没有配送模板（不过 shipping 是有效的 Connect IntegrationType，可用于搜索注册表），而且配送供应商尤其常见的做法是提供供应商托管的集成——推荐前请先参阅Marketplace 列出的并非都是 Connect 连接器。范围边界：如果 OMS/WMS 已经负责预订承运商服务，那么发货和跟踪就由它负责——这属于订单管理，而非本领域。

关注点	参考资料
从这里开始——工作流：第 0 阶段原生功能检查 → 需求 → 使用原生功能／使用现有连接器／定制／构建 → 配置 → 应用 → 验证；需要预先说明的三个事实，以及与 commerce-patterns、OMS 和税务之间的范围边界	commercetools-integrations: shipping/overview.md
使用原生功能、使用现有连接器、定制还是构建？第 0 阶段表格（区域／等级／谓词／冻结并报价，与真正的连接器之间的区别）、shippingRateInputType 和 100 个 Shipping Method 的限制、实时检查、供应商托管陷阱，以及应从哪个模板创建脚手架	commercetools-integrations: shipping/connector-selection.md
契约（编码前必读）：最终落地决策（使用 setShippingRateInput 而非等级，还是使用 setCustomShippingMethod／addCustomShippingMethod）及其对 matching-cart 的影响；费率扩展的超时预算（默认 2 s，最长 10 s）、缓存和失败时放行；选项列表端点；标签与跟踪信息回写（addDelivery／addParcelToDelivery／setParcelTrackingData，在 deliveryKey 上保持幂等）；Single 与 Multiple 模式；完整的陷阱目录	commercetools-integrations: shipping/shipping-contract.md
从需求到 connect.yaml：需要哪些应用、承运商凭证、启用的承运商／服务等级／发货地／加价、超时与回退键、最小权限范围、实际的 postDeploy 工作（回退 Shipping Method、Types、Extension、凭证验证）；完整示例	commercetools-integrations: shipping/config-from-requirements.md
验证往返流程：报价 → 可见选项 → Cart 价格 → Order 价格 → 标签 → 跟踪；购物车被阻止、选项不可见、沙盒费率列表和重复 Delivery 等陷阱	commercetools-integrations: shipping/verification.md

相关技能： SDK 客户端设置、范围、查询谓词和核心数据模型请参阅 commercetools-platform——链接到该文档即可，无需在此重复介绍客户端／身份验证基础知识。税务模式（Platform／External／ExternalAmount／Disabled）、折扣叠加顺序、sortOrder 语义，以及 Direct Discounts 阻止 Discount Codes 作为领域概念的内容，请参阅 commercetools-commerce-patterns；这些子领域介绍的是驱动这些功能的连接器。