接 Sage X3：验证您 folder 的 Sync API 连通性

备齐租户 onboarding 时下发的七个值——环境、Sync API 基址、folder、租户 API Key 与 Sage 身份 OAuth 一对凭证——填进 Integration 再测试：测试会换取 token 并探测您的 folder。本连接只验证连通性，不同步订单、库存或客户。

Sage X3 连接用来验证本系统能到达您租户上某一个 Sage X3 folder 的 Sync API：它换取一个 Sage 身份 token，并读取该 folder 的变更流一次。请先清楚它的范围——本连接目前只做连通性验证。它不拉订单、客户或库存进来，也不把库存推回去，因为 Sync API 是通用的表级同步接口，订单、库存、客户的表名与列映射必须按您自己 folder 的元数据、针对您的部署确认。测试通过只证明下面七个值对该 folder 能一起工作，不证明其他功能。

前置条件#

• 一套已开通 Sync API 的 Sage X3 租户部署，以及一个要验证的 X3 folder，例如 SEED。
• 该部署的租户 onboarding 资料包：Sync API 基址、租户 API Key，以及准确的 folder 名。folder 名大小写敏感，请保留下发时的原样拼写。
• 同一轮 onboarding 下发的、给本租户的 Sage 身份 OAuth 客户端凭证一对（一个 client ID 与一个 client secret）。
• 您知道要接的是哪个环境：production 还是 test。您填的这个词决定测试使用哪个 Sage token 地址。

拿凭证#

1. 向您的 Sage X3 管理员，或负责您租户 onboarding 的团队，索取该部署的 onboarding 资料包。本连接的七个值全部来自那次 onboarding——本指南没有单独的注册页面，任何值都不应编造，也不要借用另一个租户的值。
2. 从资料包里记下您租户的 Sync API 基址，形如 https://tenant-host/syncapi，其中的租户主机是您自己的。
3. 把 folder 名按资料包里的原样记下，包括大小写——例如 SEED。之后的测试会按这个确切名字去问该 folder。
4. 记下资料包里的租户 API Key 并妥善保密。测试时它会作为 X-API-KEY 请求头，与 token 一起发送。
5. 记下同一资料包里的 Sage 身份 OAuth client ID 与 client secret。两者是成对的一套——不要把一对的 secret 配到另一对的 ID 上。
6. 确认资料包是否要求 token audience。只有 onboarding 文档明确要求时才需要这个值——否则在填入时留空。

填进 Integration#

1. 打开 Integration → 连接器市场 → Sage X3 → 新建连接。
2. environment——必填，环境：正式租户填字面词 production，测试租户填 test。production 走 Sage token 地址 https://id.sage.com/oauth/token，test 走 https://id-shadow.sage.com/oauth/token。
3. tenant_base_url——必填，租户 Sync API 基址：粘贴 onboarding 下发的 Sync API 基址，例如 https://tenant-host/syncapi，其中的租户主机换成您自己的。
4. folder——必填，X3 Folder：按下发的原样填写 folder 名，例如 SEED。本字段大小写敏感——在这里 seed 与 SEED 是两个不同的名字。
5. tenant_api_key——必填，租户 API Key：粘贴 onboarding 资料包里的租户 API Key。这是密码类型字段，按秘密保存，测试时作为 X-API-KEY 请求头发送。
6. client_id——必填，OAuth client ID：粘贴同一资料包里 Sage 身份 OAuth 一对中的 client ID。这是密码类型字段，按秘密保存。
7. client_secret——必填，OAuth client secret：粘贴同一对 OAuth 凭证的 client secret。这是密码类型字段，按秘密保存。ID 与 secret 必须来自同一对。
8. audience——选填，Token audience：只有您的租户 onboarding 文档明确要求 token audience 时才填。否则留空——测试会不带 audience 去换 token。

测试连接#

点测试连接。测试先检查五项必填凭证值，缺哪项就以对应名字停下：MISSING_TENANT_BASE_URL、MISSING_FOLDER、MISSING_TENANT_API_KEY、MISSING_CLIENT_ID 或 MISSING_CLIENT_SECRET。然后它在共用的 12 秒时限内做两步真实校验。第一步，按您 environment 选定的地址，用 client_id 与 client_secret 换取 Sage 身份 token；填了 audience 就一并带上。第二步，向您租户的 Sync API 问该 folder 的变更，同时发送两个头：token 作 Authorization: Bearer、租户 API Key 作 X-API-KEY。返回 200 即通过，结果会写明到达的 folder。401 报 INVALID_TOKEN，403 报 MISSING_SCOPE，404 报 NOT_FOUND——各自含义见下方常见问题。

配 Mapping / 选模板#

本连接没有标准 Mapping 可配，也没有模板可供选择。Sync API 工作在表级，订单、库存、客户的表名与列因 folder 而异，因此要等为您的部署搭建数据连接时，按您的 folder 元数据逐项确认——不是在这里猜、也不是在这里填的东西。在您的 folder 完成这种逐部署确认之前，本连接就停留在测试步骤所做的连通性检查上。不要为了迁就猜出来的映射去改 Sage X3 里的表名或字段名。

激活#

测试通过后激活连接，把这组已验证的值保存在 Integration 里，之后可以用同样的凭证再检查同一个 folder。激活不会启动任何数据流：本连接不搬运订单、客户或库存，两个方向都不搬。如果 onboarding 之后下发了新的租户 API Key 或新的 OAuth 凭证对，请更新这里的字段并重新测试后再使用这个连接。

常见问题#

测试报 INVALID_TOKEN（401）

这次检查在 token 一侧被拒了。要么是换 token 时您的 client_id 与 client_secret 这一对被拒绝，要么是换回来的 token 不被租户 Sync API 接受。常见原因是复制的值带了多余空格、把一对 OAuth 凭证的 secret 配了另一对的 ID，或 environment 填的词把换取动作送去了与该凭证对下发环境不同的 Sage token 地址。

从同一份 onboarding 资料包重新复制 client_id 与 client_secret、不带多余空格，并确认 environment 与该凭证对下发的租户一致——正式租户用 production，测试租户用 test。如果填了 audience，除非 onboarding 文档要求，否则先删掉，再重新测试。

测试报 MISSING_SCOPE（403）

token 被接受了，但您的租户 API Key 对 folder 字段里写的那个 folder 没有权限。请求已经到达您租户的 Sync API——卡住的是 Key 本身，不是地址，也不是 OAuth 凭证对。

请您的 Sage X3 管理员给该租户 API Key 授予这个 folder 的访问权，或下发一支覆盖该 folder 的 Key。顺便核对一下 folder 名，然后用更新后的 Key 重新测试。

测试报 NOT_FOUND（404）

folder 字段里写的 folder 没有在本租户上为 Sync API 启用，或这个名字与那里的 folder 对不上。由于 folder 名大小写敏感，即使名字对但大小写错，也会被当成另一个 folder。

把 folder 的值与 onboarding 资料包逐字对照，包括大写字母。如果拼写完全一致，请您的 Sage X3 管理员为 Sync API 启用该 folder，然后重新测试。

测试以 MISSING_TENANT_BASE_URL、MISSING_FOLDER、MISSING_TENANT_API_KEY、MISSING_CLIENT_ID 或 MISSING_CLIENT_SECRET 停下

结果里写明了到底哪个字段是空的。测试会先检查字段，五项不全就什么都不发，因为 folder 探测需要 token 与 API Key 同时在场。

从 onboarding 资料包把结果点名的那个字段补上——基址、folder、租户 API Key、OAuth client ID 或 OAuth client secret——保存后重新测试。如还有缺失提示，照此再补。

我把服务器地址或完整网址填进了 environment，测试失败

environment 不是地址字段。它只接受两个字面词之一，这个词用来选测试使用哪个 Sage token 地址。填别的内容会把换 token 的动作送错地方，或送到不可用的地方。

把 environment 的值改成单个词：本连接是正式租户就填 production，是测试租户就填 test。服务器地址应填在 tenant_base_url 里，然后重新测试。

测试通过了，但订单、库存或客户都没有同步

这是本连接目前的范围，不是您的值填错了。测试只证明换 token 与 folder 探测能工作。数据搬运还不属于本连接，因为 Sync API 是表级的，您 folder 里订单、库存、客户的表与列必须先按您的 folder 元数据、针对您的部署逐项确认。

请把测试通过当作该 folder 的连接已验证，订单、库存与客户的作业暂时继续在 Sage X3 里处理。将来为您的部署搭建数据连接时，会从这组已验证的值出发——您不需要重新收集凭证。