332 lines
16 KiB
JSON
332 lines
16 KiB
JSON
{
|
||
"module": "warehouse",
|
||
"description": "仓库开放 API 统一入口,供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 MD5 签名鉴权(interface_type_id=3)",
|
||
"version": "1.0.0",
|
||
"updatedAt": "2026-08-03",
|
||
"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": "外部系统将消息推入仓库站内信,WMS 异步转发到目标渠道。warehouse_id 由验签后上下文注入,禁止外部传入。",
|
||
"isNeedAuth": false,
|
||
"isNeedLogin": false,
|
||
"headers": [],
|
||
"params": [
|
||
{
|
||
"name": "sourceType",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "来源类型:im / api,默认 api"
|
||
},
|
||
{
|
||
"name": "sourceChannel",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "来源渠道标识(IM 平台名称 / API 标识),将写入 source_extra"
|
||
},
|
||
{
|
||
"name": "requestId",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "body",
|
||
"description": "来源请求唯一 ID,与 appKey 组合为 ext_id(api:{appKey}:{requestId}),用于幂等去重"
|
||
},
|
||
{
|
||
"name": "targetType",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "目标类型:im / api / webhook,默认 im"
|
||
},
|
||
{
|
||
"name": "targetChannel",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "body",
|
||
"description": "目标渠道:wecom / dingtalk / feishu / warehouse_api / webhook"
|
||
},
|
||
{
|
||
"name": "extData",
|
||
"type": "object",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "外部透传数据,任意 JSON,WMS 不解析,回信时原样返回"
|
||
},
|
||
{
|
||
"name": "flags",
|
||
"type": "object",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "处理标记,可选:skip_ai_parse(跳过智能解析)、skip_auto_reply(跳过自动回复)、skip_forward(仅存档不转发)"
|
||
},
|
||
{
|
||
"name": "storeId",
|
||
"type": "number",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "关联货主 ID"
|
||
},
|
||
{
|
||
"name": "parentId",
|
||
"type": "number",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "关联消息 ID(回信时指向原消息,形成对话链)"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "ok",
|
||
"type": "boolean",
|
||
"required": true,
|
||
"description": "操作是否成功"
|
||
},
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "站内信记录 ID"
|
||
},
|
||
{
|
||
"name": "ext_id",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "外部唯一消息主键"
|
||
}
|
||
],
|
||
"errors": [
|
||
{
|
||
"code": "400",
|
||
"message": "requestId 不能为空"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "targetChannel 不能为空"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "targetUrl 不能为空"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "缺少仓库信息"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "target_url 仅允许 https:// 协议"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "target_url 不允许指向内网地址"
|
||
},
|
||
{
|
||
"code": "500",
|
||
"message": "站内信入站失败"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|