Mall 开放 API 与 ERP / MES / WMS 集成说明
> 版本:v1.0 交付日期:2026-11-15 说明:字段与路径为设计稿,正式开放需平台开通 API 权限并分配 AppKey。
1. 认证
| 项 | 说明 |
|---|---|
| 认证方式 | AppKey + AppSecret 签名,Header 携带 X-App-Key、X-Timestamp、X-Nonce、X-Sign |
| 签名算法 | 对 method + path + timestamp + nonce + body 做 HMAC-SHA256,取十六进制 |
| 时效 | 请求时间与服务器时间偏差超过 300 秒拒绝;同一 nonce 5 分钟内不可重复 |
| 密钥管理 | 支持多密钥并存,可单独禁用;密钥变更不影响历史调用日志 |
| 权限范围 | 每个密钥绑定 scopes,如 quote:read、order:write、bom:upload |
| 限流 | 按密钥维度限流,默认 60 次/分钟,可申请提升 |
| 环境 | 沙箱与生产两套密钥,沙箱数据每日清理 |
2. 客户侧接口
| 方法 | 路径 | 说明 | Scope |
|---|---|---|---|
| POST | /open/v1/bom/upload | 上传 BOM 文件并解析 | bom:upload |
| GET | /open/v1/bom/{id} | 查询解析结果与缺料 | bom:read |
| POST | /open/v1/sourcing | 发起寻源 | sourcing:write |
| GET | /open/v1/quotes?rfq_id= | 查询报价 | quote:read |
| POST | /open/v1/orders | 创建订单 | order:write |
| GET | /open/v1/orders/{id} | 订单详情与进度 | order:read |
| GET | /open/v1/logistics/{order_id} | 物流信息 | logistics:read |
| GET | /open/v1/invoices?month= | 对账与发票数据 | finance:read |
| GET | /open/v1/stock?sku= | 自营物料库存 | stock:read |
| GET | /open/v1/cases?order_id= | 客诉与整改状态 | case:read |
3. 供应商侧接口
| 方法 | 路径 | 说明 | Scope |
|---|---|---|---|
| GET | /open/v1/supplier/rfqs | 接收寻源需求 | rfq:read |
| POST | /open/v1/supplier/quotes | 回传报价 | quote:write |
| POST | /open/v1/supplier/orders/{id}/accept | 接单 | order:accept |
| POST | /open/v1/supplier/orders/{id}/status | 状态变更 | order:write |
| POST | /open/v1/supplier/orders/{id}/progress | 生产进度上报 | progress:write |
| POST | /open/v1/supplier/shipments | 出货单与物流单号 | logistics:write |
| POST | /open/v1/supplier/cases/{id}/reply | 整改与来料不良回执 | case:write |
| GET | /open/v1/supplier/settlements | 结算账单 | finance:read |
4. Webhook 回调
| 事件 | 触发时机 | 载荷要点 |
|---|---|---|
quote.created | 供应商回传报价 | rfq_id、供应商、金额、交期 |
order.status_changed | 订单状态变更 | order_id、旧状态、新状态、时间 |
order.progress | 生产节点上报 | order_id、工序、完成率 |
case.created | 客诉新建 | case_id、订单、问题类型 |
shipment.created | 出货 | 单号、承运商、预计到达 |
回调规则:HMAC 签名头、3 次重试(间隔 10 秒 / 60 秒 / 5 分钟)、失败落库可手动重放。
5. 错误码
| 码 | 含义 | 处理建议 |
|---|---|---|
| 40101 | 签名不匹配 | 检查签名串拼接与编码 |
| 40102 | 时间戳过期 | 校准服务器时间 |
| 40103 | nonce 重放 | 每次请求使用新随机串 |
| 40301 | scope 不足 | 申请对应权限 |
| 42901 | 触发限流 | 降频或申请提升额度 |
| 50001 | 平台内部错误 | 记录 trace_id 后重试 |
6. 对接清单(客户侧)
- 申请 AppKey 与沙箱密钥。
- 在沙箱完成 BOM 上传 → 寻源 → 报价查询 → 下单 → 状态回写闭环。
- 配置回调地址并验证签名。
- 切换生产密钥,灰度 5% 流量观察 3 天。
- 全量切换,保留沙箱用于回归。
7. 注意事项
- 平台不代收代付,对账与开票数据按实际订单与合同执行。
- 库存与产能数据以供应商维护值为准,接口返回带更新时间。
- 报价有效期为供应商设定天数,过期需重新获取。
- 所有接口返回
trace_id,问题排查需提供该值。

