ZiiCloud 对接流程

1. 概述

1.1 应用场景

使用 ZiiCloud / ZiiPOS 管理海外门店 POS、线上点单、库存、报表、会员、储值、礼品卡等业务的客户，可以通过观远数据连接器同步 ZiiCloud 数据，用于门店经营、销售、商品、会员和储值礼品卡分析。

1.2 功能简介

观远数据连接器通过 ZiiCloud API 获取业务数据。创建“ZiiCloud”数据账户时，需要填写 customer_id、clientId 和 clientSecret。

1.3 注意事项

正式对接前，请确认客户具备 ZiiCloud 管理员权限，或可以联系 ZiiCloud 官方支持、实施人员获取 API 凭据。clientSecret 属于敏感信息，只应填写到观远连接器数据账户中，不要在文档、工单、聊天记录或截图中明文传播。

2. 观远数据连接器侧准备

登录观远数据连接器平台：

https://apiconnector.guandata.com/

登录后点击右上角“进入控制台”。

进入控制台后，点击左侧菜单“数据账户管理”。

在数据账户页面，点击右侧“新增数据账户”。

3. 获取授权信息

3.1 字段来源

新增“ZiiCloud”数据账户前，需要准备以下字段：

官方参考入口：

• ZiiCloud 门户：https://portal.ziicloud.com/
• ZiiCloud Help Center：https://support.ziicloud.com/
• ZiiCloud Tanda 集成说明：https://support.ziicloud.com/knowledge-base/integration-how-to-connect-with-tanda/
• ZiiCloud Xero 集成说明：https://support.ziicloud.com/knowledge-base/ziipos-how-to-integrate-ziipos-with-xero/
• ZiiCloud Xero Client ID / Client Secret 申请说明：https://support.ziicloud.com/knowledge-base/zii-inventory-how-to-apply-xero-integration-key/

3.2 填写 customer_id

customer_id 是观远连接器侧的一对多账户区分字段，不需要从 ZiiCloud 官方后台获取，也不一定是 ZiiCloud 接口侧字段。建议按客户简称、环境或项目约定填写，例如用于区分测试/正式环境或不同品牌账户。

填写时请注意：

• 保持简短、稳定、可读。
• 同一个 ZiiCloud 数据账户保存后，后续同步任务应持续使用同一个 customer_id。
• 不要填写手机号、邮箱、登录密码、密钥明文等敏感信息。

3.3 获取 clientId 和 clientSecret

clientId 和 clientSecret 应来自同一套 ZiiCloud 正式环境 API 凭据。ZiiCloud 公开帮助中心未展示观远连接器所需 ZiiCloud Data API 凭据的标准自助申请页面；如客户后台没有 API / Integration / Developer / App Credentials 等入口，请通过 ZiiCloud 官方支持或项目实施渠道获取。

公开帮助中心可以作为 ZiiCloud 集成入口和凭据配置方式的参考：

• Tanda 集成文档说明：先从 Tanda 获取 Token，再进入 https://portal.ziicloud.com/integration/overview 选择 Tanda 并保存。
• Xero 集成文档说明：先从 Xero 获取 Client ID / Client Secret，再进入 ZiiCloud 门户的 Integration -> Xero 进行配置。

这些文档说明的是 ZiiCloud 与第三方系统之间的集成，不是观远连接器调用 ZiiCloud Data API 所需凭据的直接申请页面。填写观远连接器时，请以客户后台实际 API 凭据页或 ZiiCloud 官方支持提供的信息为准。

ZiiCloud 官方 Xero Integration Key 文档中的 Client ID / Client Secret 示例：

填写时请注意：

• clientId 和 clientSecret 必须配套使用。
• 不要把 Tanda、Uber Eats、DoorDash、Xero 等第三方集成的 Token 或 Client ID 填入 ZiiCloud 连接器字段。
• 复制到观远连接器时，请避免多余空格、换行、全角字符或漏字符。

4. 连接“ZiiCloud”数据账户

在“数据账户管理”页面点击“新增数据账户”，所属平台选择：

ZiiCloud

选择后，页面会展示该平台需要填写的连接字段。

填写说明：

填写完成后，点击“测试连接”。测试通过后，点击“确定”保存数据账户。

如果测试连接失败，优先检查：

• customer_id 是否已填写，且能区分当前 ZiiCloud 数据账户。
• clientId 与 clientSecret 是否配套，是否存在复制错误。
• ZiiCloud 侧 API 凭据是否已启用，并具备项目所需接口权限。
• 观远侧“ZiiCloud”平台是否已为当前客户开通。

5. 后续数据使用

数据账户保存成功后，可在后续数据集同步、任务配置或接口取数流程中选择该账户，用于同步 ZiiCloud 销售订单、取消订单、商品、会员、会员等级、积分、储值、礼品卡交易等数据。

6. 完整流程

1. 确认需要同步的 ZiiCloud 账号、环境和业务范围。
2. 为本次数据账户确定一个稳定的 customer_id。
3. 由客户管理员或项目技术联系人获取正式环境的 clientId 和 clientSecret。
4. 登录观远数据连接器，进入“数据账户管理”，新增数据账户并选择“ZiiCloud”。
5. 填写账户名称、customer_id、clientId 和 clientSecret。
6. 点击“测试连接”，测试通过后保存，并在后续同步流程中使用该数据账户。