272 lines
15 KiB
JSON
272 lines
15 KiB
JSON
[
|
||
{
|
||
"version": "2026.06.04-openapi-04",
|
||
"date": "2026-06-04",
|
||
"summary": "文档结构优化:拆分 endpoints 为 methods.groups 多分组(基础模块 / 发货单模块)",
|
||
"methods": [],
|
||
"notes": [
|
||
"将单一 endpoints 数组重构为 methods.groups 多分组结构",
|
||
"基础模块:index.ping",
|
||
"发货单模块:deliveryorder.create、deliveryorder.query",
|
||
"移除顶层 groupName 字段,分组名改由各 group 独立声明"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-03",
|
||
"date": "2026-06-04",
|
||
"summary": "新增 deliveryorder.create 和 deliveryorder.query 方法文档",
|
||
"methods": [
|
||
"deliveryorder.create",
|
||
"deliveryorder.query"
|
||
],
|
||
"notes": [
|
||
"新增 deliveryorder.create:创建发货单接口,支持订单主信息、收件人信息、订单明细的完整入参;创建渠道为 API,平台/快递自动匹配",
|
||
"新增 deliveryorder.query:查询发货单接口,根据 deliveryOrderCode 查询订单详情",
|
||
"所有参数使用驼峰命名(camelCase),不做下划线兼容",
|
||
"requestBody 字段按 deliveryOrder.xxx、deliveryOrder.receiverInfo.xxx、orderLines.orderLine、[].orderLine.xxx 层级清晰标注"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-02",
|
||
"date": "2026-06-04",
|
||
"summary": "移除 ping.echo 和 index.health,只保留 index.ping",
|
||
"methods": [
|
||
"ping.echo",
|
||
"index.health"
|
||
],
|
||
"notes": [
|
||
"移除 ping.echo:回显接口暂不对外开放",
|
||
"移除 index.health:健康检查接口暂不对外开放",
|
||
"当前仅保留 index.ping 心跳接口"
|
||
],
|
||
"type": "removed"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-01",
|
||
"date": "2026-06-04",
|
||
"summary": "移除入口方法 openapi.index,新增 index.health 和 ping.echo 方法文档",
|
||
"methods": [
|
||
"openapi.index",
|
||
"index.health",
|
||
"ping.echo"
|
||
],
|
||
"notes": [
|
||
"移除 openapi.index:该方法是 POST /openapi 的入口端点,非业务方法,从文档中移除",
|
||
"新增 index.health:基础模块健康检查接口,返回 openapiMethods 模块状态",
|
||
"新增 ping.echo:ping 模块回显接口,将请求体原样返回,用于调试连通性和签名验证"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.04.26-openapi-01",
|
||
"date": "2026-04-26",
|
||
"summary": "新增 openapi 入口文档骨架(/openapi),包含请求体解析、app_key 与签名校验规则",
|
||
"methods": [
|
||
"openapi.index"
|
||
],
|
||
"notes": [
|
||
"新增 methods/openapi.json:记录 /openapi 入口的文档骨架与校验约定(JSON body 解析、统一错误格式、app_key 校验、签名规则)。",
|
||
"核心校验规则:1) body 使用 JSON 解析,优先 rawBody;2) 错误对外格式使用 toFailure(flag/code/message/data/timestamp);3) app_key 仅当数据库记录的 interface_type_id=2 且 is_enabled=1 时视为有效;4) 签名按 query 字段字母序排序(排除 sign/signature)+ selfAppSecret + bodySign(md5(stableSerialize(body))),对拼接字符串取 md5。"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.04.26-openapi-02",
|
||
"date": "2026-04-26",
|
||
"summary": "说明:/openapi 入口不校验请求头,补充签名别名与 app_key 有效性说明",
|
||
"methods": [
|
||
"openapi.index"
|
||
],
|
||
"notes": [
|
||
"修正:明确 /openapi 入口不对请求头进行强制校验(与 qimen 一致),headers 字段仅作为参考。",
|
||
"确认:body JSON 解析(rawBody 优先)与错误消息保持为 'json数据为空' / 'json数据解析错误';app_key 校验仅当 wms_api_app.interface_type_id=2 且 is_enabled=1 时有效。",
|
||
"补充:签名字段别名说明(sign/signature)与 app_key 别名(app_key/appkey/self_app_key);签名算法与实现参见 app/lib/api_sign.js。"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.04.26-openapi-03",
|
||
"date": "2026-04-26",
|
||
"summary": "新增 openapi 方法 index.ping(基础模块,心跳接口)",
|
||
"methods": [
|
||
"index.ping"
|
||
],
|
||
"notes": [
|
||
"新增 openapi 可用性检测接口 index.ping,返回与系统成功结构一致(包含 code/message/data)。"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.04.26-openapi-04",
|
||
"date": "2026-04-26",
|
||
"summary": "规范化 /openapi 文档:独立链路、移除请求头校验、返回风格改为 code/message/data、明确签名与 app_key 校验、指向 openapiMethods 分发。",
|
||
"methods": [
|
||
"openapi.index",
|
||
"index.ping"
|
||
],
|
||
"notes": [
|
||
"本次变更:",
|
||
"1) 明确 /openapi 为独立链路,不复用 system/qimen 的请求头校验;",
|
||
"2) 移除 platform/project 等请求头的强校验说明;",
|
||
"3) 返回结构与 system 风格对齐(使用 code/message/data,移除额外 flag 字段);",
|
||
"4) 保持 body 为 JSON(rawBody 优先),并明确错误文案为 'json数据为空' / 'json数据解析错误';",
|
||
"5) 明确 app_key 仅当 wms_api_app.interface_type_id=2 且 is_enabled=1 时视为有效;",
|
||
"6) 明确签名算法:query 按字母序排序 + self_app_secret + bodySign(md5(stableSerialize(body))),支持别名 sign/signature 与 app_key/appkey/self_app_key;",
|
||
"7) 说明 method 分发走 openapiMethods 专用目录,示例方法 index.ping(基础模块)。"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-05",
|
||
"date": "2026-06-04",
|
||
"summary": "新增订单模块 order.cancel 方法",
|
||
"methods": [
|
||
"order.cancel"
|
||
],
|
||
"notes": [
|
||
"新增 order.cancel:取消发货单接口,支持直接取消未拣货/未打印的订单;已拣货或已打印的改为拦截状态",
|
||
"当前支持 JYCK(一般交易出库)、HHCK(换货出库)、BFCK(补发出库)三种出库单类型",
|
||
"取消操作为不可逆操作"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-06",
|
||
"date": "2026-06-04",
|
||
"summary": "补齐 deliveryorder.create、deliveryorder.query、order.cancel 的 params 入参文档",
|
||
"methods": [
|
||
"deliveryorder.create",
|
||
"deliveryorder.query",
|
||
"order.cancel"
|
||
],
|
||
"notes": [
|
||
"为三个方法的 params 数组补充标准 OpenAPI query 参数:method、v、timestamp、app_key、sign"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-07",
|
||
"date": "2026-06-04",
|
||
"summary": "修正 params 字段:从 query 签名参数改为 POST body 业务参数(与 requestBody 保持一致)",
|
||
"methods": [
|
||
"deliveryorder.create",
|
||
"deliveryorder.query",
|
||
"order.cancel"
|
||
],
|
||
"notes": [
|
||
"params 现包含 POST body 的业务入参(与 requestBody 一致),query 签名参数已通过页面顶部签名说明覆盖"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-08",
|
||
"date": "2026-06-04",
|
||
"summary": "新增商品模块 singleitem.synchronize 和 singleitem.query 方法",
|
||
"methods": [
|
||
"singleitem.synchronize",
|
||
"singleitem.query"
|
||
],
|
||
"notes": [
|
||
"新增 singleitem.synchronize:商品同步接口,按 itemCode 唯一约束创建或更新商品信息,联动库存表",
|
||
"新增 singleitem.query:商品查询接口,按 itemId 返回完整商品信息",
|
||
"所有参数使用驼峰命名(camelCase)"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-09",
|
||
"date": "2026-06-04",
|
||
"summary": "singleitem.synchronize 的 warehouseCode 改为从 app_key 自动解析,不再要求调用方必传",
|
||
"methods": [
|
||
"singleitem.synchronize"
|
||
],
|
||
"notes": [
|
||
"warehouseCode 改为可选参数,默认从 app_key 绑定的仓库(api_app.qimen_warehouse_code)自动解析",
|
||
"ownerCode 同步改为可选参数"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-10",
|
||
"date": "2026-06-04",
|
||
"summary": "安全加固:移除 singleitem.synchronize 的 warehouseCode 和 ownerCode 入参,完全由 app_key 自动解析",
|
||
"methods": [
|
||
"singleitem.synchronize"
|
||
],
|
||
"notes": [
|
||
"warehouseCode 和 ownerCode 从 params 中移除,调用方不可传入或覆盖",
|
||
"两个字段完全由服务端根据 app_key 自动解析,确保仓库/货主绑定关系不可被篡改"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-11",
|
||
"date": "2026-06-04",
|
||
"summary": "新增库存模块 inventory.query 方法",
|
||
"methods": [
|
||
"inventory.query"
|
||
],
|
||
"notes": [
|
||
"新增 inventory.query:批量库存查询接口,按商品 ID 列表返回可用量和锁定量",
|
||
"支持批量查询,减少请求次数",
|
||
"库存不足的商品不会出现在返回结果中"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-12",
|
||
"date": "2026-06-04",
|
||
"summary": "新增回调模块 callback.test 方法及统一回调通知系统",
|
||
"methods": [
|
||
"callback.test"
|
||
],
|
||
"notes": [
|
||
"新增 callback.test:模拟回调测试接口,向 callback_url 发送签名回调",
|
||
"新增 app/service/openapi/callback.js:统一回调服务,支持签名+重试+日志",
|
||
"订单同步完成时自动触发 API 渠道回调(fire-and-forget,不影响主流程)",
|
||
"回调签名算法与 OpenAPI 入口完全一致"
|
||
],
|
||
"type": "added"
|
||
},
|
||
{
|
||
"version": "2026.06.04-openapi-13",
|
||
"date": "2026-06-04",
|
||
"summary": "移除回调模块(回调测试改为独立页面 /docs/api/openapi/callback-test)",
|
||
"methods": [
|
||
"callback.test"
|
||
],
|
||
"notes": [
|
||
"回调测试不再作为 OpenAPI method,改为独立路由页面 /docs/api/openapi/callback-test",
|
||
"页面支持下拉选择注册事件、填入测试 URL、前端计算签名、模拟回调推送",
|
||
"回调事件注册表位于 app/service/openapi/callbackRegistry.js"
|
||
],
|
||
"type": "removed"
|
||
},
|
||
{
|
||
"version": "2026.06.05-openapi-14",
|
||
"date": "2026-06-05",
|
||
"summary": "增加 timestamp 时效校验(±10分钟),超时返回 400",
|
||
"methods": [],
|
||
"notes": [
|
||
"所有 OpenAPI 方法增加 timestamp 与服务器时间差校验,超过 ±10 分钟返回 400",
|
||
"docs.js 签名说明区同步更新注意事项"
|
||
],
|
||
"type": "modified"
|
||
},
|
||
{
|
||
"version": "2026.06.05-openapi-15",
|
||
"date": "2026-06-05",
|
||
"summary": "deliveryorder.create 收件人信息改为必填(name/mobile/province/city/area/detailAddress)",
|
||
"methods": [
|
||
"deliveryorder.create"
|
||
],
|
||
"notes": [
|
||
"receiverInfo 6个字段改为必填,避免快递取号时因地址缺失失败",
|
||
"mobile 和 tel 二选一必填"
|
||
],
|
||
"type": "modified"
|
||
}
|
||
]
|