BurtonSoftware01 1. 排查原则
遇到 API 问题时，先确认问题发生在哪一层：账号权限、渠道授权、SKU 映射、仓库库存、物流回传，还是平台接口限制。
排查时不要直接要求客户重新授权。先看连接状态、活动日志、最近同步时间和错误字段，避免打断正在运行的订单同步。
02 2. 快速检查顺序
- 确认客户账号是否已通过 Approvals。
- 确认用户在 Access Control 中有对应工作区和模块权限。
- 进入 Integrations，查看渠道是否 Connected。
- 查看 Activity Logs，确认是否有授权失败、同步失败或权限异常。
- 到 Orders、Products、Inventory Products 抽查数据是否同步。
- 如果涉及发货，检查 Carrier、Tracking、Ship Date 和平台要求字段。
Activity Logs 用于定位用户操作、授权异常、同步失败和权限问题。
03 3. 常见问题
| 问题 | 可能原因 | 处理建议 |
|---|---|---|
| 授权后没有订单 | 首次同步未完成、店铺范围不对、渠道未连接、时间筛选过窄。 | 检查 Connected 状态、最后同步时间、Orders 筛选条件和 Activity Logs。 |
| API 信息不正确 | Client ID、Secret、Token、Marketplace ID 来自错误账号或已过期。 | 让客户在平台后台重新确认凭证来源，不在公开渠道发送完整密钥。 |
| SKU 匹配失败 | SKU 大小写、空格、前后缀不一致，或组合商品未拆分。 | 先确认 Products，再建立 SKU 映射并重新抽查订单。 |
| 库存不同步 | SKU 未匹配、仓库范围不对、渠道库存权限不足。 | 检查 Inventory Products、仓库权限、渠道权限和同步日志。 |
| 物流渠道不可用 | Carrier 名称不符合平台要求，或物流方式未启用。 | 核对 Carrier、Shipping Method、平台服务代码和发货回传设置。 |
| 用户看不到渠道 | 用户未加入正确工作区或权限组。 | 管理员在 Access Control 中检查 Group、Workspace 和模块权限。 |
04 4. 报错处理模板
| 报错类型 | 优先检查 | 需要客户提供 |
|---|---|---|
| 授权失败 | 平台账号、授权范围、浏览器登录账号、回调结果。 | 平台名称、店铺名称、授权时间、错误提示截图。 |
| Token 失效 | Refresh Token 是否过期、是否被平台撤销。 | 平台后台授权状态，不提供完整 Token。 |
| SKU 不存在 | Products 是否有该 SKU、是否已建立映射。 | SKU 示例、平台订单号后 4 位或脱敏截图。 |
| 库存不同步 | Inventory Products 字段、仓库范围、渠道库存权限。 | SKU、仓库、期望库存口径。 |
| 发货回传失败 | Carrier、Tracking、Ship Date、平台服务代码。 | 订单脱敏截图、物流方式、平台错误提示。 |
05 5. 权限与安全
管理员应限制 Integrations、Setup Wizard、Access Control 的可操作人员。客服或运营可以查看同步状态，但不应拥有修改 API 凭证的权限。
Access Control 用于按用户组和工作区控制谁能查看、编辑或管理敏感功能。