做代理业务，核心就是“把上游的商品搬到自己的站上卖”。本文档拆解从上游获取 API 密钥，到下游配置供应商并同步商品的完整链路。无论上游是 V10 还是财务系统，逻辑是相通的。
1. 对接前准备
在开始之前，确认以下条件已满足：
- 你拥有一个上游账号：在上游的魔方系统（V10 或财务系统）中注册并登录。
- 上游已开启 API 总开关：部分上游默认关闭 API 对接功能，需要上游管理员在后台开启[citation:2]。
- 你的下游系统版本达标：如果是 V10 对接 V10，双方版本均需 V10.2.8 以上；如果是 V10 对接财务系统，财务系统需升级到 V3.5.2 以上[citation:4][citation:5]。
- 记下上游的网址：例如
https://upstream.example.com，后续添加上游时需要填写[citation:5]。
2. 上游申请 API 密钥
登录你在上游系统的用户中心（不是下游自己的后台），按以下步骤操作。
1进入 API 管理
在上游用户中心找到 安全中心（或账户管理） -> API 管理[citation:2][citation:4]。
2开启 API 并获取密钥
- 如果 API 功能未开启，勾选同意相关条款，点击 “立即开启”。
- 开启后，页面会显示一串 API 密钥（Token）和可能的 API 私钥。
- 立即复制并妥善保存。部分系统重置密钥后旧密钥立即失效，需要同步更新到下游[citation:2]。
区分上游类型： 如果上游是 V10 业务系统，你获取的是 Token 和私钥[citation:4]；如果上游是 魔方财务系统，你获取的是 API 密钥，且用户名/密码也可能需要一并提供[citation:5]。
3. 下游添加上游供应商
回到你自己的系统后台（下游 V10 或财务系统），添加上游供应商。
1进入供应商管理
在 V10 后台导航至 上下游管理 -> 供应商管理，点击 添加供应商[citation:4][citation:5]。
2填写连接信息
| 字段 | 填写内容 | 说明 |
|---|---|---|
| 名称 | 自定义 | 建议填上游品牌名，便于识别 |
| 接口类型 | 智简魔方（或对应类型） | 上游是魔方系选魔方，非魔方系选“手动”[citation:2] |
| 接口地址 | 上游系统的访问地址 | 如 https://upstream.example.com |
| 用户名 | 你在上游注册的账号 | 手机号或邮箱[citation:2] |
| API 密钥 | 上一步复制的密钥 | V10 对 V10 时可能需要同时填 Token 和私钥[citation:4] |
填写完成后点击保存。如果信息正确，供应商列表应显示连接状态正常，并可能展示上游账户余额[citation:2]。
4. 导入上游商品
供应商添加成功后，需要把上游的商品“搬”到你的系统中。
1进入上游商品管理
V10 后台导航至 上下游管理 -> 上游商品管理，点击 添加商品。如果还没有商品分组，可以先新建一个分组[citation:4][citation:5]。
2选择要代理的商品
- 选择你刚添加的供应商。
- 系统会拉取上游的商品列表，勾选你要代理的那一款。
- 点击 同步数据，系统会自动导入商品信息和定价[citation:2]。
同步完成后，去 商品管理 中确认商品是否已出现，并可以根据需要调整售价（比如在上游价格基础上加价 10%-20%）。
5. 余额检查（付费业务必看）
上游余额不足 = 你的用户无法开通机器。 代理商模式下，用户在你站上下单后，你的系统会用上游账户的余额去上游下单。上游没钱了，你的用户就开不了机，投诉和退款会接踵而来[citation:5][citation:9]。
V10 从 10.5.6 版本开始，供应商管理页面会展示上游账户余额，并支持余额不足告警通知[citation:15]。建议：
- 添加完供应商后，立即查看余额是否正常读取。
- 在供应商配置附近开启余额预警，阈值建议设为“预计月销量的 1.5 倍成本”。
- 养成每周检查一次上游余额的习惯，别等系统告警了才处理。
6. 常见报错
问题一：添加供应商后连接状态异常
- 检查 API 密钥是否复制完整（前后不要有空格）。
- 确认上游的 API 总开关已开启。
- 如果是 V10 对 V10，确认双方版本都 ≥ 10.2.8。
问题二：同步商品时提示“无法获取商品列表”
- 确认上游确实有上架的商品。
- 检查上游账号是否有权限访问这些商品（部分上游可能设置了白名单或分组权限）。
- 在 V10 后台的日志或上游商品管理页面查看具体错误返回。
问题三：用户下单后开通失败，但上游余额充足
- 去 供应商管理 检查连接状态是否变为“异常”。
- 确认上游的 API 密钥没有被上游管理员重置。
- 查看系统错误日志，通常会包含上游返回的具体原因（如“库存不足”、“产品已下架”等）。