{ "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": "sendTime", "type": "number", "required": false, "source": "body", "description": "消息原始发送时间(可选):毫秒时间戳、秒时间戳或 ISO 时间字符串。WMS 据此判断历史消息:发送时间距今超过阈值(默认 10 分钟,config.inbox.historyMessageMaxAgeMs 可调)的历史/补推消息将跳过 AI 处理,不自动回复、不创建工单;不传则按实时消息处理" }, { "name": "flags", "type": "object", "required": false, "source": "body", "description": "处理标记。支持:skipAi=true 显式跳过 AI 处理;send_time=毫秒时间戳(消息原始发送时间,用于历史消息过滤,与 sendTime 参数等价)" } ], "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": "站内信入站失败" } ] } ] } ] } }