选择接入方式

选择适合你的 Xcotton 接入方案

按平台和控制范围选择方案

先查找适用的平台集成；如果没有适用方案，或希望完全自主控制前端与服务端流程，再选择 OpenAPI 自主接入。

优先选择适用的平台方案；同一业务职责不得由平台方案和自研 OpenAPI 重复实现。

需要接入 Xcotton
├── 存在适用的平台或前端集成方案
│   └── 先查看该方案的能力声明
│       ├── 完整方案：通常无需完整接入 OpenAPI
│       ├── 前端组件：按文档补充所需 OpenAPI
│       └── 补充型 OpenAPI：只用于平台方案未覆盖的职责
└── 没有适用方案，或希望完全自主控制
    └── 选择 OpenAPI 自主接入
        ├── 自研前端与购物车交互
        └── 商家服务端对接 Xcotton OpenAPI / Webhooks

当前可用方案

当前可用方案如下。

对比项	OpenAPI 自主接入	Shopify Headless SDK
典型场景	自研商城、SaaS 平台或希望完全控制流程	Shopify Headless 商城
前端实现	商家自行开发	使用 Xcotton Widget 与 SDK 能力
购物车操作	商家自行实现	SDK 通过 Shopify Storefront API 实现，或调用商家提供的 adapter
Xcotton OpenAPI	商家服务端直接接入	标准场景通常不需要完整接入；非重叠补充能力以文档为准
Shopify App	不作为 OpenAPI 通用前置条件	必须先安装并配置 Xcotton Shopify App
职责边界	商家负责所选 OpenAPI 流程	SDK 负责 Widget 和购物车集成；商家不得重复实现相同职责

OpenAPI 自主接入

商家自研前端展示与用户交互，由商家服务端调用 Xcotton OpenAPI，并维护报价、订单、发货、服务单、理赔与 Webhook。选择这条路线时，通常不再使用 Headless SDK 管理同一套购物车保障流程。

开始 OpenAPI 接入

Shopify Headless SDK

当前属于平台完整方案。SDK 使用 Shopify Storefront API 操作购物车，商家通常无需完整接入 Xcotton OpenAPI。仍需完成 App 安装、Token、cartId、Widget 容器和宿主购物车刷新。非重叠的查询或运营类 OpenAPI 可以补充，但不能与 SDK 已覆盖的职责重叠。

开始 Shopify Headless SDK 接入

checkout 和 checkout+ 适配模式见 适配模式。

职责不能重复

报价展示、保障商品加购、购物车状态、订单同步、发货同步等每项职责只能有一个实现方，不能由 SDK、平台插件和商家自研逻辑重复处理。文档未明确支持的组合方案，必须先由 Xcotton 确认职责边界。

仍然无法确定时

联系 Xcotton Support 或客户经理（AM）确认能力边界，不要自行拼接文档未明确支持的混合架构。