出站回调:
- 新增 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
331 lines
16 KiB
JSON
331 lines
16 KiB
JSON
{
|
||
"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": "站内信入站失败"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|