WMS_MAIN/methods/warehouse.json
liufumingren 948f600689 feat(inbox): 回调推送、出站文档、搜索增强、日志与推送状态完善
出站回调:
- 新增 warehouse_notify.json 文档(notify.ping/notify.reply),与 warehouse.json 互跳
- 回调体统一 { method, code, data },method 放 query,body 为业务数据
- MD5 签名: sign=MD5(appSecret+timestamp+bodyJson)
- 回调响应: {code:200} 成功,非200/非code:200 视为失败
- docs 页面支持模拟推送调试

搜索增强(searchStock/searchWarehouseStock):
- 直接查 stock_warehouse,不再依赖 stock_store
- 新增字段: gross_weight/box_spec/packing_requirements/prohibited_type
- 管理标识: is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt
- 条码关联: wms_stock_barcodes
- 图片: wms_file_reference(business_type=stock)+wms_file,返回数组
- id 修正为 stock_warehouse.id

推送状态完善:
- handleApiMessage 增加 push_status 更新(2成功/3失败)
- 未配回调地址 → push_status=3 + error 原因
- 回调异常 catch 也更新 push_status=3 + 写日志
- 出站日志写入 wms_warehouse_log 表(WN-前缀)

消息列表:
- keyword 兼容 content/keyword,支持数组
- keyword 搜索 content/group_name/user_name 三列
- 支持 where+operator 结构化查询(parseWhereConditions)
- storeId=-1 查询无货主消息; storeId=0→IS NULL
- 日期范围: startDate/endDate

其他:
- silent 动作: AI 识别无需回复时跳过回执
- ai_enabled 灰度开关(群级)
- bindCode 文档修正
- store_name 改用 StoreWarehouse.store_remask
2026-08-08 00:17:38 +08:00

331 lines
16 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"module": "warehouse",
"description": "仓库开放 API 统一入口(入站方向:外部 → WMS),供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 MD5 签名鉴权(interface_type_id=3)。出站通知请参阅 warehouse_notify.json。",
"version": "1.2.0",
"updatedAt": "2026-08-07",
"http": {
"path": "/warehouse",
"method": "POST"
},
"headers": [],
"methods": {
"groups": [
{
"groupName": "基础模块",
"module": "index",
"list": [
{
"method": "index.ping",
"description": "心跳接口,验证仓库 API 应用连通性,返回仓库上下文与应用信息",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [],
"response": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "当前仓库 ID"
},
{
"name": "app_key",
"type": "string",
"required": true,
"description": "当前请求的 AppKey"
},
{
"name": "server_time",
"type": "number",
"required": true,
"description": "服务器 Unix 时间戳(秒)"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "服务状态,正常时返回 ok"
}
],
"errors": [],
"notes": [
"模块:基础模块",
"方法部署位置:warehouseMethods/index.ping",
"无需 body 参数,GET query 参数满足 method/v/timestamp/app_key/sign 即可",
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
]
}
]
},
{
"groupName": "货主模块",
"module": "store",
"list": [
{
"method": "store.list",
"description": "查询当前仓库下已授权的货主列表,返回货主基本信息与授权状态(需 auth_status=2 已通过 + store.status=1 启用 + warehouse_use_status=1 可用)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码,默认 1",
"defaultValue": 1
},
{
"name": "pageSize",
"type": "number",
"required": false,
"source": "body",
"description": "每页数量,默认 20,最大 100",
"defaultValue": 20
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "货主列表",
"children": [
{
"name": "store_id",
"type": "number",
"required": true,
"description": "货主 ID(wms_store.id)"
},
{
"name": "company_name",
"type": "string",
"required": true,
"description": "公司全称"
},
{
"name": "contact_person",
"type": "string",
"required": true,
"description": "联系人"
},
{
"name": "contact_phone",
"type": "string",
"required": true,
"description": "联系电话"
},
{
"name": "contract_id",
"type": "number",
"required": true,
"description": "授权关系 ID(wms_store_warehouse.id)"
},
{
"name": "auth_status",
"type": "number",
"required": true,
"description": "授权状态:2=已通过"
},
{
"name": "auth_start",
"type": "string",
"required": false,
"description": "授权开始日期"
},
{
"name": "auth_end",
"type": "string",
"required": false,
"description": "授权结束日期"
},
{
"name": "store_remask",
"type": "string",
"required": false,
"description": "商家备注"
},
{
"name": "warehouse_remask",
"type": "string",
"required": false,
"description": "仓库备注"
}
]
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息",
"children": [
{
"name": "page",
"type": "number",
"required": true,
"description": "当前页码"
},
{
"name": "pageSize",
"type": "number",
"required": true,
"description": "每页数量"
},
{
"name": "total",
"type": "number",
"required": true,
"description": "总记录数"
},
{
"name": "totalPages",
"type": "number",
"required": true,
"description": "总页数"
}
]
}
],
"errors": [],
"notes": [
"模块:货主模块",
"方法部署位置:warehouseMethods/store.list",
"仓库隔离:自动使用当前 API 应用绑定的 warehouse_id",
"仅返回已通过授权(auth_status=2)、仓库侧可用(warehouse_use_status=1)、货主启用(store.status=1)的记录",
"分页查询:默认 20 条/页,最大 100 条/页"
]
}
]
},
{
"groupName": "站内信模块",
"module": "inbox",
"list": [
{
"method": "inbox.push",
"description": "外部系统将消息推入仓库站内信。warehouse_id 由验签后上下文注入,禁止外部传入。ext_id 由 appKey + requestId 自动组合,幂等去重。source_type 固定为 api,禁止外部传入。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "requestId",
"type": "string",
"required": true,
"source": "body",
"description": "来源请求唯一 ID,与 appKey 组合为 ext_id(api:{appKey}:{requestId}),用于幂等去重"
},
{
"name": "content",
"type": "string",
"required": false,
"source": "body",
"description": "消息正文/摘要"
},
{
"name": "groupId",
"type": "string",
"required": false,
"source": "body",
"description": "外部群 ID,用于关联群及自动查询货主路由"
},
{
"name": "groupName",
"type": "string",
"required": false,
"source": "body",
"description": "群名称(展示用)"
},
{
"name": "userId",
"type": "string",
"required": false,
"source": "body",
"description": "外部用户 ID"
},
{
"name": "userName",
"type": "string",
"required": false,
"source": "body",
"description": "用户名称(展示用)"
},
{
"name": "parentId",
"type": "number",
"required": false,
"source": "body",
"description": "关联消息 ID(回信时指向原消息,形成对话链)"
},
{
"name": "targetType",
"type": "string",
"required": false,
"source": "body",
"description": "目标类型:im / api / webhook,默认 im"
},
{
"name": "extData",
"type": "object",
"required": false,
"source": "body",
"description": "外部透传数据,任意 JSON,WMS 不解析,回信时原样返回"
},
{
"name": "flags",
"type": "object",
"required": false,
"source": "body",
"description": "处理标记(预留,当前未消费)"
}
],
"response": [
{
"name": "ok",
"type": "boolean",
"required": true,
"description": "操作是否成功"
},
{
"name": "id",
"type": "number",
"required": true,
"description": "站内信记录 ID"
},
{
"name": "ext_id",
"type": "string",
"required": true,
"description": "外部唯一消息主键(api:{appKey}:{requestId})"
}
],
"errors": [
{
"code": "400",
"message": "requestId 不能为空"
},
{
"code": "400",
"message": "缺少仓库信息"
},
{
"code": "400",
"message": "parent_id=XX 对应的消息不存在"
},
{
"code": "400",
"message": "消息体超过 64KB 限制"
},
{
"code": "500",
"message": "站内信入站失败"
}
]
}
]
}
]
}
}