# 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. 对接清单（客户侧）

1. 申请 AppKey 与沙箱密钥。
2. 在沙箱完成 BOM 上传 → 寻源 → 报价查询 → 下单 → 状态回写闭环。
3. 配置回调地址并验证签名。
4. 切换生产密钥，灰度 5% 流量观察 3 天。
5. 全量切换，保留沙箱用于回归。

## 7. 注意事项

1. 平台不代收代付，对账与开票数据按实际订单与合同执行。
2. 库存与产能数据以供应商维护值为准，接口返回带更新时间。
3. 报价有效期为供应商设定天数，过期需重新获取。
4. 所有接口返回 `trace_id`，问题排查需提供该值。