如何建立 Connection：通用流程

每个连接器都是同五步：在市场里选、给连接起名、填凭证、测试、配 Mapping 并激活。没有 key 时还有模拟模式可以先把全流程跑通。

Connection（连接）是连某一个具体外部系统的一套配置——一个 Shopify 店铺、一个 UPS 账号、一家 ERP 公司。各连接器指南（Shopify、UPS）和连接器目录给每个平台的确切字段；这篇讲它们共用的流程。

开始之前#

• 对方平台的账号，且有管理员（或开发者）权限——大多数凭证都在管理员或开发者页面后面。
• 从连接器目录（本栏目三篇）查好您那个连接器的字段清单——先知道要收集什么，不用来回切标签页。
• 第一次连接，平台提供测试/沙箱凭证时优先用它——不要拿真实数据练 Mapping。

第 1–2 步：选连接器、给连接起名#

1. 打开 Integration → 连接器市场，按分类（电商、快递、聚合快递、EDI、WMS、ERP…）筛选，点您的连接器卡片 → 新建连接。
2. 起个团队日后认得出来的名字，如「Shopify — 美国主店」「UPS — 生产账号」。一个平台可以建多个连接（两个店铺、测试+生产），靠名字区分。

第 3 步：填凭证#

• 向导显示的字段就是这个连接器需要的全部——来自连接器注册表，与目录里列的一致。必填有标记；没有隐藏的额外字段。
• 每个字段都有一行帮助，写明这个值在对方平台哪里。本栏目连接器目录里对应平台的那一节写了完整路径，不确定时去查。
• 密钥类字段（key、token、密码）加密存储，保存后永不回显全文——只看到掩码预览。填错了就粘一份新的；旧的无法「查看」。
• 极少数没有注册字段清单的连接器，向导会回退到通用 key-value 编辑器加密钥输入框——key 名按平台文档的叫法原样填。

第 4 步：测试连接#

测试分两级：连通性（凭证到底能不能用）和单据级预览（文档类连接器会真实拉一单，左右对照展示「平台字段 → 标准字段」）。测试失败会告诉您卡在哪一级——401 是凭证问题；预览对不上是 Mapping 问题，不是凭证。改完再测，测多少次都行；测试不会改动任何一边的数据。

测试记录落在哪：诊断日志

每次连接测试都会在连接详情页留下一份逐步记录——承运商则在承运商行的可展开诊断区里。测试失败时打开它：它按测试执行的顺序写清哪一步停了、为什么停，凭证问题还是 Mapping 问题一看便知，不用猜。日志只记步骤和结果，不存您的密钥本身，只记用了哪些 key 名。还没测过时，这个区会直说没有记录：测一次，记录就出现在这里。

第 5 步：Mapping 与激活#

1. 选该连接器的预置 Mapping 模板（如 Shopify 标准模板），再看一遍单据预览——重点核对 SKU、数量、地址和您依赖的自定义字段。
2. 配产品：渠道 SKU 对不上 OMS 产品的会进「产品映射」的待处理列表——去那里配对，否则订单进来会有未映射的行。
3. 激活。此后连接按您设的节奏（拉取频率/推送触发）自动同步，每次运行都能在 Integration → 运行监控和日志里看到。先盯前几单，确认无误再放手。

之后怎么管理连接#

• 查看和编辑各有独立页面：在 Integration → 连接里点开一个连接进入详情页——状态、同步设置、配置摘要、哪些 Flow 在用它，一页看清。改名称、同步内容、频率、凭证在该连接的编辑页完成，保存后自动回到详情页。
• 改凭证：打开连接粘新密钥——轮换 key 或 token 过期后要做。改完立刻测试一次。
• 暂停渠道时用停用不要删除：停用的连接保留 Mapping 和历史，一键可重新启用；删了配置就没了。
• 有意义时可以重复建（同平台两个店铺、一个测试 + 一个生产）。Flow 选定它用的连接，测试连接不会误上生产。