BurtonSoftwareBurtonSoftware.Ai
API Module Manual
Customer-facing API authorization, channel onboarding, credentials, sync checks, and troubleshooting.
API 接入总览与文档目录
面向三方电商客户的 API 接入路线图，说明该从哪里开始、谁负责什么、上线前要检查什么。
01 1. 适用范围
API 目录用于指导三方电商客户把店铺、ERP 或平台账号接入 Burton WMS Ai。接入完成后，订单、商品、库存、客户、发货状态和物流信息可以在销售渠道与仓库系统之间同步。
本文档不提供真实密钥、客户订单明细或平台后台截图中的敏感字段。运营人员在对外发送截图前，需要确认截图中没有 Token、Secret、客户邮箱、收货地址或订单号明细。
安全原则：API 凭证只用于授权配置，不进入公开文档，不通过群聊公开传播，也不写在截图备注里。
02 2. 文档目录
| 章节 | 适合对象 | 解决的问题 |
|---|---|---|
| API 接入总览与文档目录 | 客户负责人 / 实施 / 管理员 | 明确接入范围、角色分工、上线顺序和验收清单。 |
| API 授权操作指引 | 店铺管理员 / 实施 | 说明 OAuth、API Key、Token 授权入口和验证方式。 |
| API 同步规则 | 运营 / 仓库 / 客户成功 | 说明订单、商品、库存、发货回传如何流转。 |
| API 常见问题与报错排查 | 客服 / 实施 / 管理员 | 快速定位授权失败、无订单、SKU 不匹配、物流不可用等问题。 |
03 3. 接入生命周期
| 阶段 | 客户需要做什么 | Burton 团队检查什么 |
|---|---|---|
| 准备账号 | 确认登录账号、店铺管理员权限和 API 授权权限。 | Approvals、Access Control、工作区和角色权限。 |
| 连接渠道 | 选择 Shopify、TikTok Shop、Amazon、eBay、Wayfair、Walmart 等渠道。 | Integrations 或 Setup Wizard 的连接状态。 |
| 验证同步 | 检查 Orders、Products、Inventory Products 是否出现数据。 | 同步日志、SKU 映射、仓库范围和渠道范围。 |
| 履约回传 | 确认 Carrier、Tracking、Ship Date、Fulfillment Status 的回传规则。 | 发货回传开关、物流渠道、平台要求字段。 |
| 对账复盘 | 导出订单、商品、库存报表进行核对。 | Reports 导出、异常订单和活动日志。 |
04 4. 推荐角色分工
| 角色 | 建议权限 | 工作重点 |
|---|---|---|
| 客户店铺管理员 | Integrations 授权、店铺后台授权 | 提供合法授权，确认店铺范围和授权账号。 |
| 客户运营 | Orders、Products、Inventory、Reports | 核对订单、商品、SKU 和库存是否同步正确。 |
| 仓库团队 | Inventory、Receiving、Work Orders | 执行收货、拣货、打包、发货和库存调整。 |
| 实施顾问 | Integrations、Setup Wizard、Activity Logs | 连接渠道、检查日志、处理上线异常。 |
| 系统管理员 | Access Control、Approvals | 管理用户、权限、审批和敏感配置入口。 |
05 5. 上线验收清单
- 账号已审批，用户可以进入正确工作区。
- 渠道状态为 Connected 或已通过连接测试。
- 至少抽查 3 到 5 个 SKU，确认平台 SKU、仓库 SKU、系统 SKU 的映射一致。
- 至少抽查 3 到 5 个订单，确认订单状态、收货信息、商品明细和履约状态正确。
- 库存字段 On Hand、Committed、Incoming、Available 可以解释清楚，并与仓库口径一致。
- 发货回传字段和平台要求一致，尤其是 Carrier、Tracking、Ship Date。
- Reports 可以导出客户需要的订单、商品和库存 CSV。
Integrations 是渠道连接和授权管理的主要入口。
Access Control 用于限制哪些用户可以管理授权、凭证和后台设置。
API 授权操作指引：连接店铺与平台账号
说明三方电商客户如何在 Burton WMS Ai 中完成 OAuth、API Key 或 Token 授权，并验证渠道是否连接成功。
01 1. 操作场景
客户需要将自己的店铺、ERP 或平台账号授权到 Burton WMS Ai 后，系统才能自动同步订单、商品、库存、发货状态和物流信息。
授权完成后，Amazon、Shopify、TikTok Shop、eBay、Wayfair、Walmart 等渠道订单可以进入系统，由运营和仓库团队继续处理履约、库存更新和发货回传。
02 2. 授权前准备
| 准备项 | 说明 |
|---|---|
| 客户账号 | 客户需先获得 Burton WMS Ai 登录账号，并由管理员完成 Approvals 审批。 |
| 店铺权限 | 客户需要拥有对应平台的管理员权限或 API 授权权限。 |
| API 凭证 | API 模式通常需要 Seller ID、Client ID、Client Secret、Refresh Token、Marketplace ID 等信息。 |
| SKU 规则 | 店铺 SKU、仓库 SKU、系统 SKU 应尽量保持一致，避免后续订单和库存匹配失败。 |
| 物流口径 | 上线前确认默认仓库、发货方式、承运商名称和回传规则。 |
不建议把 Client Secret、Refresh Token、Access Token 放在聊天记录或公开截图里。需要临时共享时，应使用受控渠道，并在上线后按客户安全要求轮换。
03 3. 登录并进入授权入口
- 打开 Burton WMS Ai 系统。
- 使用已审批的客户账号登录。
- 进入 Dashboard 后，确认当前查看范围是 All Channels 还是指定店铺。
- 从左侧菜单进入 Integrations，或在首次上线时进入 Setup Wizard。
客户在 Integrations 页面选择对应平台，通过 Manage 或 Connect 进入授权。
04 4. OAuth 授权渠道
Shopify、TikTok Shop 等渠道通常建议使用 OAuth。客户点击 Connect 后，会跳转到平台官方授权页面；确认授权范围后，页面会返回 Burton WMS Ai。
操作要点：
- 确认浏览器已登录正确的店铺管理员账号。
- 点击对应渠道卡片的 Connect 或 Manage。
- 在平台授权页面确认权限范围。
- 返回系统后检查渠道状态是否变为 Connected。
- 打开 Orders 或 Products 抽查是否开始同步数据。
05 5. API Key / Token 授权渠道
Amazon SP-API、Wayfair、Walmart 等渠道通常需要填写 API 信息。客户应从对应平台后台获取凭证，并在 Setup Wizard 或渠道配置页中填写。
| 字段 | 用途 |
|---|---|
| Seller ID / Merchant ID | 平台卖家或商户身份标识。 |
| Marketplace ID | 平台站点或市场区域，例如 US、UK、DE。 |
| Client ID | API 应用或连接器的客户端编号。 |
| Client Secret | API 应用密钥，应由客户安全保存。 |
| Refresh Token | 用于系统持续拉取订单、库存和发货状态。 |
| Warehouse / Carrier | 用于后续库存、履约和物流回传映射。 |
首次上线时可以通过 Setup Wizard 填写渠道凭证并检查连接状态。
06 6. 授权后验证
| 页面 | 检查内容 |
|---|---|
| Orders | 是否出现平台订单、订单状态、收货信息和履约状态。 |
| Products | 是否出现商品标题、SKU、价格、重量和状态。 |
| Inventory Products | 是否出现 On Hand、Committed、Incoming、Available。 |
| Activity Logs | 是否有授权失败、同步失败或权限异常记录。 |
授权成功后，平台订单会进入 Orders 页面，由运营和仓库团队继续履约。
API 同步规则：订单、商品、库存与发货回传
说明授权成功后订单、商品、库存和物流回传如何同步，以及客户上线前需要统一哪些字段口径。
01 1. 数据同步范围
授权成功后，系统会按渠道能力同步订单、商品、客户、库存、发货状态和物流信息。不同平台开放的字段不同，实际同步范围以渠道授权权限和平台接口能力为准。
上线前不要只看连接是否成功，还要检查订单、商品、库存、发货回传四条链路是否都能解释清楚。
02 2. 同步对象与检查页面
| 同步对象 | 进入页面 | 重点字段 |
|---|---|---|
| 订单 | Orders | Order ID、Channel、Status、Recipient、Items、Fulfillment Status。 |
| 商品 | Products | SKU、Title、Status、Price、Weight、Category、Image。 |
| 库存 | Inventory Products | Warehouse、Bin、On Hand、Committed、Incoming、Available。 |
| 客户 | Customers | Name、Email、Channel、Orders、Last Order。 |
| 发货回传 | Orders / Activity Logs | Carrier、Tracking、Ship Date、Confirmation Status、API Result。 |
Orders 用于确认平台订单是否进入系统，并检查状态和履约信息。
03 3. SKU 与商品映射
SKU 是订单、库存和发货回传能否稳定运行的关键。推荐客户在上线前统一店铺 SKU、仓库 SKU 和系统 SKU 的命名规则。
| 场景 | 处理方式 |
|---|---|
| 三方 SKU 完全一致 | 优先自动匹配，实施人员抽查即可。 |
| 平台 SKU 与仓库 SKU 不一致 | 建立映射关系，再做订单和库存验证。 |
| SKU 大小写或空格不同 | 先清洗 SKU，再决定是否合并为同一商品。 |
| 组合商品 / 套装 | 确认是否需要拆分为多个仓库 SKU。 |
| 新品首次同步 | 先检查 Products，再检查 Inventory Products。 |
Products 用于查看商品标题、SKU、状态、价格、重量和图片完整性。
04 4. 库存同步口径
客户查看库存时，必须理解不同库存字段的业务含义。
| 字段 | 建议解释 |
|---|---|
| On Hand | 仓库当前实物库存。 |
| Committed | 已被订单占用但尚未完全出库的库存。 |
| Incoming | 已创建收货计划或在途的库存。 |
| Available | 可销售或可分配库存，通常需要扣除已占用数量。 |
| Status | 用于提示 In Stock、Low Stock、Out of Stock 等库存健康状态。 |
Inventory Products 用于核对 SKU、仓库、库位和可用库存。
05 5. 发货回传规则
订单完成履约后，系统需要根据平台要求回传 Tracking、Carrier、Ship Date、Fulfillment Status、ASN 或 Shipment Confirmation。
上线前建议确认：
- 平台要求的承运商名称是否和系统 Carrier 一致。
- 是否允许系统自动回传发货状态。
- 是否需要平台面单、ASN 或额外服务代码。
- 回传失败后由谁处理重试和客户通知。
06 6. 对账与复盘
授权和同步稳定后，客户可以通过 Reports 导出订单、商品和库存 CSV。建议每次上线后至少做一次订单、库存、物流三方复盘。
Reports 用于导出订单、商品和库存数据，支持客户对账和上线后复盘。
API 常见问题与报错排查
整理 API 授权和同步过程中最常见的问题，并给出客服、实施和管理员可执行的排查顺序。
01 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 用于按用户组和工作区控制谁能查看、编辑或管理敏感功能。