WMS_MAIN/methods/system.json
liufumingren 99367e5043 1
2026-06-06 05:15:46 +08:00

21081 lines
1.0 MiB
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": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.4.0",
"updatedAt": "2026-06-05",
"headers": [
{
"name": "platform",
"type": "string",
"required": true,
"description": "客户端平台标识,如 web/pda/app",
"list": [
{
"value": "web",
"name": "网页端"
},
{
"value": "pda",
"name": "PDA端"
},
{
"value": "app",
"name": "APP端"
},
{
"value": "wx",
"name": "微信端"
},
{
"value": "miniProgram",
"name": "小程序端"
},
{
"value": "other",
"name": "其他"
},
{
"value": "workerstation",
"name": "工作台"
}
]
},
{
"type": "string",
"required": true,
"name": "project",
"description": "项目标识,如 all/warehouse/store/tms/wms/scm/other",
"list": [
{
"value": "all",
"name": "全部"
},
{
"value": "warehouse",
"name": "仓库"
},
{
"value": "store",
"name": "货主"
},
{
"value": "tms",
"name": "物流"
},
{
"value": "wms",
"name": "WMS"
},
{
"value": "scm",
"name": "SCM"
},
{
"value": "other",
"name": "其他"
}
]
}
],
"methods": {
"groups": [
{
"groupName": "配置模块",
"module": "config",
"list": [
{
"method": "config.list",
"description": "config.list 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "要批量修改的仓库商品记录 ID 数组(stock_warehouse.id)",
"children": [
{
"name": "id",
"type": "number",
"description": "单个记录 ID"
}
]
},
{
"name": "method",
"type": "string",
"required": true,
"source": "body",
"description": "要修改的字段名,可选值:brand_name、prohibited_id、gross_weight、packing_requirements、managementFlags、stock_unit"
},
{
"name": "value",
"type": "string|number|object",
"required": true,
"source": "body",
"description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正数,可含小数);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'"
},
{
"name": "values",
"type": "any",
"required": false,
"source": "body",
"description": "兼容字段:当前实现以 `value` 为准,不使用 `values`。若客户端历史使用 `values`,请切换为 `value`。"
}
],
"response": [
{
"name": "code",
"type": "number",
"description": "业务状态码,200 表示成功;405 表示参数/权限校验不通过;500 表示服务器错误"
},
{
"name": "message",
"type": "string",
"description": "业务提示信息"
},
{
"name": "data",
"type": "object",
"description": "成功时返回的结果对象",
"children": [
{
"name": "affectedRows",
"type": "number",
"description": "被更新的记录数"
},
{
"name": "ids",
"type": "array",
"description": "请求中传入的 ids 数组"
}
]
}
],
"errors": [
{
"code": "405",
"description": "请选择要修改的商品(缺少 ids 或 ids 为空)"
},
{
"code": "405",
"description": "不支持修改的字段: {method}"
},
{
"code": "405",
"description": "修改值不能为空"
},
{
"code": "405",
"description": "违禁品类型必须是数字"
},
{
"code": "405",
"description": "毛重必须是有效的正数"
},
{
"code": "405",
"description": "管理标识必须是对象格式 / 管理标识缺少字段 / 管理标识字段值必须是 'Y' 或 'N'"
},
{
"code": "405",
"description": "部分商品不存在或无权修改: <ids>"
},
{
"code": "405",
"description": "缺少仓库信息"
},
{
"code": "500",
"description": "内部错误:批量修改失败"
}
]
}
]
},
{
"groupName": "看板模块",
"module": "dashboard",
"list": [
{
"method": "dashboard.storeStats",
"description": "dashboard.storeStats 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "dashboard.warehouseStats",
"description": "dashboard.warehouseStats 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "dashboard.hot_order_rank",
"description": "dashboard.hot_order_rank 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "dashboard.express_ratio",
"description": "dashboard.express_ratio 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "dashboard.platform_distribution",
"description": "dashboard.platform_distribution 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "dashboard.order_trend",
"description": "dashboard.order_trend 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
}
]
},
{
"groupName": "基础模块",
"module": "index",
"list": [
{
"method": "index.fastWhereTree",
"description": "index.fastWhereTree 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "type",
"type": "string",
"required": false,
"source": "body",
"description": "type 参数"
}
],
"response": [],
"errors": []
},
{
"method": "index.loadStores",
"description": "index.loadStores 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "index.getCOSUploadConfig",
"description": "index.getCOSUploadConfig 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "data",
"type": "object",
"required": false,
"source": "body",
"description": "data 参数"
}
],
"response": [],
"errors": []
},
{
"method": "index.getImages",
"description": "index.getImages 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "index.uploadSuccessNotify",
"description": "index.uploadSuccessNotify 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "index.ReferenceFile",
"description": "index.ReferenceFile 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "index.getMessageDetail",
"description": "index.getMessageDetail 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "index.test",
"description": "后台专用的拼多多开放平台测试接口,用于传入请求参数并发起真实请求,返回签名后的请求体和接口响应",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "type",
"type": "string",
"required": true,
"source": "body",
"description": "拼多多接口名,例如 pdd.order.number.list.get"
},
{
"name": "bizParams",
"type": "object",
"required": false,
"source": "body",
"description": "业务参数对象,会参与签名和请求"
},
{
"name": "request",
"type": "object",
"required": false,
"source": "body",
"description": "bizParams 兼容字段"
},
{
"name": "accessToken",
"type": "string",
"required": false,
"source": "body",
"description": "用户授权令牌"
},
{
"name": "access_token",
"type": "string",
"required": false,
"source": "body",
"description": "accessToken 的下划线命名兼容字段"
},
{
"name": "dataType",
"type": "string",
"required": false,
"source": "body",
"description": "返回格式,默认 JSON"
},
{
"name": "version",
"type": "string",
"required": false,
"source": "body",
"description": "API 版本"
},
{
"name": "timestamp",
"type": "string|number",
"required": false,
"source": "body",
"description": "时间戳,不传则使用当前秒级时间戳"
},
{
"name": "clientId",
"type": "string",
"required": false,
"source": "body",
"description": "覆盖配置中的 client_id"
},
{
"name": "clientSecret",
"type": "string",
"required": false,
"source": "body",
"description": "覆盖配置中的 client_secret"
},
{
"name": "baseUrl",
"type": "string",
"required": false,
"source": "body",
"description": "请求地址,默认拼多多开放平台网关"
},
{
"name": "headers",
"type": "object",
"required": false,
"source": "body",
"description": "额外请求头"
},
{
"name": "timeout",
"type": "number",
"required": false,
"source": "body",
"description": "请求超时时间(毫秒)"
}
],
"response": [
{
"name": "requestBody",
"type": "object",
"description": "实际发送到 PDD 网关的请求体,已包含 sign"
},
{
"name": "response",
"type": "any",
"description": "拼多多接口返回内容"
},
{
"name": "baseUrl",
"type": "string",
"description": "实际请求地址"
}
],
"errors": [
{
"code": "400",
"description": "type 不能为空"
},
{
"code": "500",
"description": "PDD 接口调用失败"
}
]
},
{
"method": "index.recognizeLicensePlate",
"description": "识别车牌号码(通过 base64 图片)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "base64",
"type": "string",
"required": true,
"source": "body",
"description": "base64 图片,支持 data URL 前缀(data:image/...;base64,)或纯 base64 字符串"
},
{
"name": "imageBase64",
"type": "string",
"required": false,
"source": "body",
"description": "兼容字段(同 base64)"
},
{
"name": "image_base64",
"type": "string",
"required": false,
"source": "body",
"description": "兼容字段(同 base64)"
}
],
"response": [
{
"name": "licensePlate",
"type": "string",
"description": "识别到的车牌号(对外契约,仅返回该字段)"
}
],
"errors": [
{
"code": "400",
"description": "base64 图片不能为空 / base64 图片格式不正确 / 图片大小不能超过 7MB"
},
{
"code": "500",
"description": "第三方 OCR 服务调用失败或腾讯云配置未设置"
}
]
},
{
"method": "index.getI18nMessage",
"description": "index.getI18nMessage 接口",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "language",
"type": "string",
"required": false,
"source": "body|query",
"description": "language 参数"
}
],
"response": [],
"errors": []
},
{
"method": "index.putI18nCollect",
"description": "index.putI18nCollect 接口",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "keys",
"type": "array",
"required": false,
"source": "body",
"description": "keys 参数"
},
{
"name": "locale",
"type": "string",
"required": false,
"source": "body",
"description": "locale 参数"
},
{
"name": "project",
"type": "string",
"required": false,
"source": "body",
"description": "project 参数"
},
{
"name": "source",
"type": "string",
"required": false,
"source": "body",
"description": "source 参数"
}
],
"response": [],
"errors": []
},
{
"method": "index.tryAutoTranslateNewKeys",
"description": "index.tryAutoTranslateNewKeys 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "index.searchSpace",
"description": "按当前仓库上下文搜索库位(使用 ctx.user.store_id;仅在 location_space 表中按 space_code/custom_barcode 搜索)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "keyword",
"type": "string",
"required": false,
"source": "body",
"description": "搜索关键字,对 space_code 和 custom_barcode 做模糊匹配(%keyword%);为空时返回当前仓库下前 50 条"
}
],
"response": [
{
"name": "flag",
"type": "string",
"description": "全局调用结果标识,成功时为 success"
},
{
"name": "code",
"type": "number",
"description": "业务状态码,200 表示成功"
},
{
"name": "message",
"type": "string",
"description": "返回信息"
},
{
"name": "data",
"type": "array",
"description": "库位数组(最多 50 条),每项包含以下字段",
"children": [
{
"name": "id",
"type": "number",
"description": "库位 ID"
},
{
"name": "space_code",
"type": "string",
"description": "库位编码"
},
{
"name": "custom_barcode",
"type": "string",
"description": "库位自定义条码"
},
{
"name": "custom_name",
"type": "string",
"description": "库位自定义名称"
}
]
},
{
"name": "total",
"type": "number",
"description": "本次返回的记录条数(等于 data.length,≤50)"
}
],
"errors": []
},
{
"method": "index.listInterfaceTypes",
"description": "查询可用的接口类型列表(如奇门仓储、开放接口等)",
"isNeedAuth": false,
"isNeedLogin": true,
"params": []
},
{
"method": "index.getLocationTypeList",
"description": "查询库位类型基础列表,优先返回当前仓库下启用的库位类型,同时合并系统公共类型;结果带 300 秒缓存",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "list",
"type": "array",
"description": "库位类型列表",
"children": [
{
"name": "id",
"type": "number",
"description": "库位类型 ID"
},
{
"name": "type_code",
"type": "string",
"description": "库位类型编码"
},
{
"name": "type_name",
"type": "string",
"description": "库位类型名称"
},
{
"name": "temperature_zone",
"type": "string",
"description": "温区"
},
{
"name": "allow_allocation",
"type": "boolean",
"description": "是否允许分配储位"
},
{
"name": "allow_transfer_out",
"type": "boolean",
"description": "是否允许移出"
},
{
"name": "description",
"type": "string",
"description": "描述"
},
{
"name": "warehouse_id",
"type": "number",
"description": "所属仓库 ID,null 表示系统公共类型"
}
]
},
{
"name": "total",
"type": "number",
"description": "返回总数"
}
],
"errors": []
},
{
"method": "index.getPlatformOauthLink",
"description": "获取平台授权链接。入参支持 code / platform_code / platformCode,服务端按首个非空值标准化为大写平台编码;会从当前登录上下文读取仓库 ID(ctx.user.store_id),再从 wms_platform.auth_base_url 读取授权基础地址。接口会优先复用当前仓库与平台下 status=0 的未授权记录;若历史 auth_random_code 带有当前配置前缀,则会先去前缀后以裸码回写,当前数据库最终保存的 auth_random_code 为裸码。若无可复用记录则生成新的裸码并写入 wms_shops。返回的 oauth_link 会从配置 platformOauthReservationCodePrefix 读取前缀(本地示例为 xxxxx_),按“前缀 + 平台编码 + '_' + 裸码”生成 state,并将 URL 编码后的 state 直接拼接到平台基础授权链接后,例如 xxxxx_PDD_<rawCode>。当前仅支持已按上述模式配置好的基础授权链接。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": false,
"source": "body",
"description": "平台编码主字段;与 platform_code / platformCode 三选一即可,服务端按 code -> platform_code -> platformCode 顺序取首个非空值并转为大写"
},
{
"name": "platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "平台编码下划线别名"
},
{
"name": "platformCode",
"type": "string",
"required": false,
"source": "body",
"description": "平台编码驼峰别名"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200"
},
{
"name": "data.platform_code",
"type": "string",
"required": true,
"description": "标准化后的平台编码"
},
{
"name": "data.oauth_link",
"type": "string",
"required": true,
"description": "基于 wms_platform.auth_base_url 构造的授权链接;实际拼接值为 encodeURIComponent(prefix + platform_code + '_' + rawCode),其中 prefix 来自 platformOauthReservationCodePrefix,rawCode 为数据库 auth_random_code 中保存的裸码。基础授权链接需预先配置为可直接追加 state 值的模式。"
}
],
"errors": [
{
"code": 400,
"message": "平台编码不能为空"
},
{
"code": 400,
"message": "未识别到当前仓库"
},
{
"code": 400,
"message": "平台不存在"
},
{
"code": 400,
"message": "平台授权基础地址未配置"
},
{
"code": 500,
"message": "创建平台授权预占记录失败"
},
{
"code": 500,
"message": "生成唯一授权码失败,请稍后重试"
}
]
},
{
"method": "index.getShopList",
"description": "获取当前登录仓库下的已授权店铺列表,支持按平台编码可选过滤。仓库上下文来自 ctx.user.store_id;服务端兼容读取 body.platform_code 与 body.platformCode,按该顺序取首个 trim 后非空值作为平台过滤条件。未传平台参数时返回当前登录仓库下全部已授权店铺;传入非空平台编码时仅返回该平台的已授权店铺。结果按 status DESC、updated_at DESC、id DESC 排序,并对敏感字段完成脱敏后返回 data.list。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "平台编码过滤条件;兼容 platformCode。服务端按 platform_code、platformCode 的顺序读取首个值,trim 后非空时仅返回该平台的已授权店铺;未传或为空时返回当前登录仓库下全部已授权店铺。"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "业务提示信息,成功时返回 ok"
},
{
"name": "data.list",
"type": "array",
"required": true,
"description": "当前登录仓库下按条件过滤后的已授权店铺列表数组;未传平台参数时返回当前仓库全部已授权店铺,传入非空 platform_code/platformCode 时仅返回对应平台店铺。结果按 status DESC、updated_at DESC、id DESC 排序,且 owner_id、access_token、refresh_token、auth_random_code 已按实现规则脱敏。",
"children": [
{
"name": "id",
"type": "number",
"description": "店铺主键 ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "所属仓库 ID(来自当前登录仓库上下文)"
},
{
"name": "platform_code",
"type": "string",
"description": "平台编码"
},
{
"name": "shop_name",
"type": "string",
"description": "店铺名称"
},
{
"name": "custom_name",
"type": "string|null",
"description": "店铺自定义名称;wms_shops 当前真实字段,未设置时返回 null"
},
{
"name": "status",
"type": "number",
"description": "授权状态:0=未授权,1=已授权"
},
{
"name": "auth_expire_at",
"type": "string|null",
"description": "授权到期时间,未设置时返回 null"
},
{
"name": "token_expires_at",
"type": "string|null",
"description": "访问令牌过期时间,未设置时返回 null"
},
{
"name": "refresh_token_expires_at",
"type": "string|null",
"description": "刷新令牌过期时间,未设置时返回 null"
},
{
"name": "scope",
"type": "object|array|null",
"description": "授权范围;直接返回数据库 JSON 字段内容,可能为对象、数组或 null"
},
{
"name": "created_at",
"type": "string",
"description": "创建时间"
},
{
"name": "updated_at",
"type": "string",
"description": "更新时间"
},
{
"name": "owner_id",
"type": "string|null",
"description": "平台店铺/主体 ID;非空且长度大于 5 时返回前 3 位 + *** + 后 2 位,长度小于等于 5 时返回 ***,空值返回 null"
},
{
"name": "access_token",
"type": "string|null",
"description": "访问令牌;非空固定返回 ***,空值返回 null"
},
{
"name": "refresh_token",
"type": "string|null",
"description": "刷新令牌;非空固定返回 ***,空值返回 null"
},
{
"name": "auth_random_code",
"type": "string|null",
"description": "授权随机码;非空固定返回 ***,空值返回 null"
}
]
}
],
"errors": [
{
"code": 400,
"message": "未识别到当前仓库"
}
]
},
{
"method": "index.getShopExpressList",
"description": "获取指定店铺的快递签约/电子面单可用列表。接口依赖当前登录仓库上下文 ctx.user.store_id 校验店铺归属;服务端会按店铺所属平台拉取并收敛可用快递列表,统一返回前端消费结构;未接入的平台当前返回空列表。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "shop_id",
"type": "string|number",
"required": false,
"source": "body",
"description": "店铺 ID;与 shopId 兼容,二选一至少传一个。服务端按 shop_id、shopId 的顺序读取首个非空值。"
},
{
"name": "shopId",
"type": "string|number",
"required": false,
"source": "body",
"description": "店铺 ID 的驼峰兼容字段;当 shop_id 为空时读取该值。"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200。"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "业务提示信息,成功时返回 ok。"
},
{
"name": "data.shop_id",
"type": "number",
"required": true,
"description": "当前店铺 ID。"
},
{
"name": "data.platform_code",
"type": "string",
"required": true,
"description": "店铺所属平台编码,返回值按服务端实现转为大写。"
},
{
"name": "data.list",
"type": "array",
"required": true,
"description": "服务端按店铺所属平台拉取并统一收敛后的快递签约/电子面单可用列表;未接入的平台返回空数组。",
"children": [
{
"name": "wp_code",
"type": "string",
"required": true,
"description": "快递/面单服务编码。"
},
{
"name": "wp_name",
"type": "string",
"required": true,
"description": "系统快递名称;由系统快递基础表根据平台快递编码 wp_code 映射得到,未匹配到时返回空字符串。"
},
{
"name": "sys_express_code",
"type": "string",
"required": true,
"description": "系统快递编码;由平台快递编码 wp_code 映射得到,未匹配到时返回空字符串。"
},
{
"name": "wp_type",
"type": "string",
"required": true,
"description": "快递/面单类型标识。"
},
{
"name": "accounts",
"type": "array",
"required": true,
"description": "当前快递服务下的签约账号列表;无签约账号时返回空数组。",
"children": [
{
"name": "branch_code",
"type": "string",
"required": true,
"description": "网点/签约账号编码。"
},
{
"name": "branch_name",
"type": "string",
"required": true,
"description": "网点/签约账号名称。"
},
{
"name": "quantity",
"type": "number",
"required": true,
"description": "当前可用单量。"
},
{
"name": "cancel_quantity",
"type": "number",
"required": true,
"description": "已取消单量。"
},
{
"name": "recycled_quantity",
"type": "number",
"required": true,
"description": "已回收单量。"
},
{
"name": "allocated_quantity",
"type": "number",
"required": true,
"description": "已分配单量。"
},
{
"name": "ship_addresses",
"type": "array",
"required": true,
"description": "发货地址列表;无可用地址时返回空数组。",
"children": [
{
"name": "country",
"type": "string",
"required": true,
"description": "国家。"
},
{
"name": "province",
"type": "string",
"required": true,
"description": "省。"
},
{
"name": "city",
"type": "string",
"required": true,
"description": "市。"
},
{
"name": "district",
"type": "string",
"required": true,
"description": "区/县。"
},
{
"name": "detail",
"type": "string",
"required": true,
"description": "详细地址。"
},
{
"name": "full_address",
"type": "string",
"required": true,
"description": "完整地址。"
}
]
},
{
"name": "services",
"type": "array",
"required": true,
"description": "当前签约账号可用的附加服务列表;无可用服务时返回空数组。",
"children": [
{
"name": "service_code",
"type": "string",
"required": true,
"description": "服务编码。"
},
{
"name": "service_name",
"type": "string",
"required": true,
"description": "服务名称。"
},
{
"name": "service_desc",
"type": "string",
"required": true,
"description": "服务说明。"
},
{
"name": "required",
"type": "boolean",
"required": true,
"description": "是否为必选服务。"
},
{
"name": "attributes",
"type": "array",
"required": true,
"description": "服务属性列表;无属性时返回空数组。",
"children": [
{
"name": "attribute_code",
"type": "string",
"required": true,
"description": "属性编码。"
},
{
"name": "attribute_name",
"type": "string",
"required": true,
"description": "属性名称。"
},
{
"name": "attribute_type",
"type": "string",
"required": true,
"description": "属性类型编码。"
},
{
"name": "type_desc",
"type": "string",
"required": true,
"description": "属性类型说明。"
}
]
}
]
}
]
}
]
}
],
"errors": [
{
"code": 400,
"message": "shop_id 不能为空"
},
{
"code": 400,
"message": "未识别到当前仓库"
},
{
"code": 404,
"message": "店铺不存在"
},
{
"code": 400,
"message": "店铺未授权"
}
]
},
{
"method": "index.getCainiaoStfTemplates",
"description": "公共无参查询淘宝菜鸟标准模板列表;服务端调用淘宝开放平台 cainiao.cloudprint.stdtemplates.get,请求地址为 https://eco.taobao.com/router/rest,使用 TOP 公共签名参数。不需要用户授权,不下发 session,不依赖登录态、当前仓库或店铺授权。成功返回 data.platform_code='TB' 与标准模板数组,模板项统一字段为 template_id/template_name/template_url/cp_code/wp_code。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200。"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "业务提示信息,成功时返回 ok。"
},
{
"name": "data.platform_code",
"type": "string",
"required": true,
"description": "平台编码,固定返回 TB。"
},
{
"name": "data.list",
"type": "array",
"required": true,
"description": "菜鸟标准模板列表;来源于 cainiao_cloudprint_stdtemplates_get_response.result.datas[*].standard_templates[*] 的宽松兼容解析结果,按统一字段 template_id/template_name/template_url/cp_code/wp_code 返回。",
"children": [
{
"name": "template_id",
"type": "string",
"required": true,
"description": "模板唯一标识;缺失时返回空字符串。"
},
{
"name": "template_name",
"type": "string",
"required": true,
"description": "模板名称;缺失时返回空字符串。"
},
{
"name": "template_url",
"type": "string",
"required": true,
"description": "模板预览或打印地址;缺失时返回空字符串。"
},
{
"name": "cp_code",
"type": "string",
"required": true,
"description": "快递公司编码;结合 datas 节点与模板项宽松提取,缺失时返回空字符串。"
},
{
"name": "wp_code",
"type": "string",
"required": true,
"description": "快递面单服务编码;结合 datas 节点的 brand_code/cp_code 与模板项宽松提取,缺失时返回空字符串。"
}
]
}
],
"errors": [
{
"code": 500,
"message": "淘宝菜鸟标准模板查询失败"
}
]
},
{
"method": "index.getPrintPlatformTemplateList",
"description": "按打印平台与快递编码查询模板列表。express_code 为必填;接口会先按 platform_code(默认 CAINIAO)定位 wms_express 对应打印平台字段,再以 express_code 过滤可用模板后返回。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "打印平台编码(如 CAINIAO);不传默认 CAINIAO,服务端会转为大写。"
},
{
"name": "express_code",
"type": "string",
"required": true,
"source": "body",
"description": "快递编码(必填);服务端会转为大写,并用于按 wms_express 中对应打印平台字段筛选模板。"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局结果标识;成功为 success,失败为 failure。"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码;成功时为 200。"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息;成功时为 ok。"
},
{
"name": "data",
"type": "object",
"required": true,
"description": "返回数据对象。",
"children": [
{
"name": "platform_code",
"type": "string",
"required": true,
"description": "规范化后的平台编码(大写);未传时默认 CAINIAO。"
},
{
"name": "express_code",
"type": "string",
"required": true,
"description": "规范化后的快递编码(大写)。"
},
{
"name": "responseData",
"type": "object",
"required": true,
"description": "平台模板响应数据;CAINIAO 场景下会按 platform_code 对应字段 + express_code 过滤 cainiao_cloudprint_stdtemplates_get_response.result.datas 后返回,未实现平台返回空对象。"
}
]
}
],
"errors": [
{
"code": 400,
"message": "express_code 不能为空"
},
{
"code": 500,
"message": "获取打印平台模板列表失败"
}
]
},
{
"method": "index.polyapiAuthorizeUrl",
"description": "生成菠萝派授权链接。该接口不接收请求参数,服务端会固定调用 Differ.JH.BuildeAuthorizeUrl,并以内置配置 this.app.config.poloApi.appKey / this.app.config.poloApi.secret 以及当前代码中写死的 callbackUrl=http://39.100.57.68/、state=123456、itemcode=test001 作为上游请求参数,最终将菠萝派接口原始响应包裹后返回。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200。"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "业务提示信息,成功时返回 ok。"
},
{
"name": "data.respone",
"type": "object",
"required": true,
"description": "菠萝派接口 Differ.JH.BuildeAuthorizeUrl 的原始响应对象。字段名按当前实现保持为 respone。"
}
],
"errors": []
}
]
},
{
"groupName": "订单工作台入口模块",
"module": "order.index",
"list": [
{
"method": "order.list",
"description": "订单工作台总列表入口,查询当前登录用户仓库上下文下的订单总列表,支持 pagination / where / sort。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会自动标准化;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "缺少仓库上下文或 where 参数格式错误"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "order.manualOutboundOrder",
"description": "手动触发出库迁移,将当前仓库内已出库订单同步到配送表。请求体直接透传给 orderDeliveryMigration.syncOutboundOrdersToDelivery。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouseId",
"type": "number",
"required": false,
"source": "body",
"description": "单仓库ID,兼容 warehouse_id"
},
{
"name": "warehouseIds",
"type": "array",
"required": false,
"source": "body",
"description": "仓库ID 数组"
},
{
"name": "queryTimeoutMs",
"type": "number",
"required": false,
"source": "body",
"description": "查询超时时间(毫秒)"
},
{
"name": "executionTimeoutMs",
"type": "number",
"required": false,
"source": "body",
"description": "执行超时时间(毫秒)"
}
],
"response": [
{
"name": "warehouseIds",
"type": "array",
"required": true,
"description": "参与迁移的仓库ID列表"
},
{
"name": "batchSize",
"type": "number",
"required": true,
"description": "单批处理上限,当前固定为 1000"
},
{
"name": "outboundStatuses",
"type": "array",
"required": true,
"description": "本次迁移匹配的出库状态"
},
{
"name": "totalSelected",
"type": "number",
"required": true,
"description": "命中的源订单数量"
},
{
"name": "totalCreated",
"type": "number",
"required": true,
"description": "实际创建到配送表的订单数量"
},
{
"name": "totalSkipped",
"type": "number",
"required": true,
"description": "本次跳过的源订单数量"
},
{
"name": "totalTimeout",
"type": "number",
"required": true,
"description": "被标记为出库超时的订单数量"
},
{
"name": "results",
"type": "array",
"required": true,
"description": "按仓库维度返回的批次结果数组,元素包含 selectedCount、createdCount、skippedCount、timeoutCount、retryableFailure 等字段"
}
],
"errors": [
{
"code": "400",
"description": "仓库ID为空或请求参数格式错误"
},
{
"code": "500",
"description": "迁移失败或数据库错误"
}
]
},
{
"method": "order.badgeCount",
"description": "订单工作台各标签页角标计数,基于当前仓库上下文返回。配送、配送异常与归档标签固定返回 99+。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "reviewOrder",
"type": "number|string",
"required": true,
"description": "待审核角标"
},
{
"name": "pendingOrder",
"type": "number|string",
"required": true,
"description": "待处理角标"
},
{
"name": "outboundOrder",
"type": "number|string",
"required": true,
"description": "待出库角标"
},
{
"name": "expectionOrder",
"type": "number|string",
"required": true,
"description": "待处理异常角标"
},
{
"name": "entrustOrder",
"type": "number|string",
"required": true,
"description": "委托外仓角标"
},
{
"name": "deliveryOrder",
"type": "string",
"required": true,
"description": "配送角标,固定返回 99+"
},
{
"name": "deliveryExpectionOrder",
"type": "string",
"required": true,
"description": "配送异常角标,固定返回 99+"
},
{
"name": "archiveOrder",
"type": "string",
"required": true,
"description": "归档角标,固定返回 99+"
}
],
"errors": [
{
"code": "400",
"description": "缺少当前仓库上下文 store_id"
}
]
},
{
"method": "order.queryOrderLogs",
"description": "查询当前仓库下订单操作日志,底层复用通用日志查询分页结构,按订单ID筛选。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "string",
"required": true,
"source": "body",
"description": "订单ID"
},
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码"
},
{
"name": "pageSize",
"type": "number",
"required": false,
"source": "body",
"description": "每页数量"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "日志列表,字段与 stock.warehouse.queryStockLogs 保持一致"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息,包含 page、pageSize、total、totalPages"
}
],
"errors": [
{
"code": "400",
"description": "订单ID为空或仓库上下文缺失"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.queryOrderLogList",
"description": "按 order_id 查询订单操作日志,返回全量日志(不分页)。接口按当前登录用户的仓库上下文过滤(method 层从 ctx.user.store_id 获取 warehouse_id),以防跨仓越界。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_id / id / orderId",
"type": "string|number",
"required": true,
"source": "body",
"description": "订单ID;支持别名 id 与 orderId,接口会兼容解析。"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "日志列表(全量返回,无分页)。每项字段与 stock.warehouse.queryStockLogs 保持一致,典型字段包括 id、action、message、actor、created_at、warehouse_id 等。"
}
],
"errors": [
{
"code": "400",
"description": "order_id 为空或格式不合法"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "order.updateExpressWeighingWeight",
"description": "更新订单运单称重重量。规则:订单仅一个运单时,直接写入该运单重量;多运单时,必须传 waybill_code 并按运单写入。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_id",
"type": "number|string",
"required": true,
"source": "body",
"description": "订单ID,必填且必须为正整数。"
},
{
"name": "waybill_code",
"type": "string",
"required": false,
"source": "body",
"description": "运单号;订单仅一个运单时可不传且会被忽略,多运单时必填并需匹配订单下运单。"
},
{
"name": "weighing_weight",
"type": "number|string",
"required": true,
"source": "body",
"description": "称重重量(kg),必填,必须大于 0,最多支持 3 位小数。"
}
],
"response": [
{
"name": "order_id",
"type": "number",
"required": true,
"description": "订单ID(成功时返回于 data 对象中)。"
},
{
"name": "waybill_code",
"type": "string",
"required": true,
"description": "写入重量的运单号(成功时返回于 data 对象中)。"
},
{
"name": "weighing_weight",
"type": "number",
"required": true,
"description": "已写入的称重重量(kg,成功时返回于 data 对象中)。"
}
],
"errors": [
{
"code": 400,
"message": "order_id 必填且必须为正整数"
},
{
"code": 400,
"message": "weighing_weight 必填"
},
{
"code": 400,
"message": "weighing_weight 格式非法,最多支持 3 位小数"
},
{
"code": 400,
"message": "weighing_weight 必须大于 0"
},
{
"code": 400,
"message": "多运单订单必须传入 waybill_code"
},
{
"code": 404,
"message": "未找到有效的订单运单记录"
},
{
"code": 404,
"message": "waybill_code 未匹配到该订单下的运单记录"
},
{
"code": 500,
"message": "订单快递模型未初始化"
},
{
"code": 500,
"message": "更新称重重量失败"
}
]
},
{
"method": "order.bindExpressPackageMaterial",
"description": "按订单ID+运单号匹配 wms_order_express,按包材编码匹配包材,并将 package_material_id 与 package_material_name_snapshot 绑定到订单运单记录。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_id",
"type": "number|string",
"required": true,
"source": "body",
"description": "订单ID,必填。"
},
{
"name": "waybill_code",
"type": "string",
"required": true,
"source": "body",
"description": "运单号,必填。"
},
{
"name": "package_material_code",
"type": "string",
"required": true,
"source": "body",
"description": "包材编码,必填。"
}
],
"response": [
{
"name": "order_id",
"type": "number",
"required": true,
"description": "订单ID(成功时返回于 data 对象中)。"
},
{
"name": "waybill_code",
"type": "string",
"required": true,
"description": "运单号(成功时返回于 data 对象中)。"
},
{
"name": "package_material_id",
"type": "number",
"required": true,
"description": "绑定后的包材ID(成功时返回于 data 对象中)。"
},
{
"name": "package_material_name_snapshot",
"type": "string",
"required": true,
"description": "绑定时写入的包材名称快照(成功时返回于 data 对象中)。"
},
{
"name": "package_material_code",
"type": "string",
"required": true,
"description": "绑定成功的包材编码(成功时返回于 data 对象中)。"
}
],
"errors": [
{
"code": 400,
"message": "参数错误"
},
{
"code": 404,
"message": "包材编码不存在"
},
{
"code": 404,
"message": "订单运单记录不存在"
},
{
"code": 500,
"message": "绑定包材失败"
}
]
},
{
"method": "order.export",
"description": "提交订单导出任务(异步)。入参支持 table_type/tableType 与 module/module_name;where 与 sort 语义与 order.list 一致。提交后立即返回 task_id,后台异步执行,导出进度/下载请通过 order.exportTaskProgress 查询。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "table_type / tableType",
"type": "string",
"required": false,
"source": "body",
"description": "导出表类型,枚举:current/history/dispatch/outsourced;兼容订单模块别名(order/reviewOrder/pendingOrder 等);支持 table_type 与 tableType 两种写法"
},
{
"name": "module / module_name",
"type": "string",
"required": false,
"source": "body",
"description": "订单模块名,兼容 module(驼峰)与 module_name(下划线)两种写法"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "查询条件,语义与 order.list 的 where 一致(推荐使用 { operator, value, type } 标准结构);禁止传入 warehouse_id/warehouseId"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,语义与 order.list 的 sort 一致"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"description": "任务 ID(后端生成)",
"required": true
},
{
"name": "status",
"type": "string",
"description": "任务状态,枚举:submitted/running/success/failed/not_found",
"required": true
},
{
"name": "progress",
"type": "number",
"description": "当前进度百分比(0-100)",
"required": true
},
{
"name": "current_count",
"type": "number",
"description": "当前已处理记录数",
"required": true
},
{
"name": "total_count",
"type": "number",
"description": "总记录数(若有)",
"required": true
},
{
"name": "message",
"type": "string",
"description": "任务提示信息",
"required": true
},
{
"name": "result",
"type": "object",
"description": "任务执行结果(可选,可能包含文件 url/fileKey 等)",
"required": true
},
{
"name": "error",
"type": "string",
"description": "失败时的错误信息(可选)",
"required": true
},
{
"name": "update_time",
"type": "string",
"description": "任务更新时间(Unix ms 或 ISO 字符串)",
"required": true
}
],
"errors": [
{
"code": 400,
"message": "参数格式不正确或 where 条件非法"
},
{
"code": 500,
"message": "导出任务提交失败"
}
]
},
{
"method": "order.exportTaskProgress",
"description": "按 task_id 查询订单导出任务进度,返回 task_id、status、progress、current_count、total_count、message、error、download_url、update_time;上传完成后 download_url 返回下载链接;未找到时 status=not_found。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID,兼容 taskId"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"description": "任务 ID",
"required": true
},
{
"name": "status",
"type": "string",
"description": "任务状态:submitted/running/success/failed/not_found",
"required": true
},
{
"name": "progress",
"type": "number",
"description": "进度百分比(0-100)",
"required": true
},
{
"name": "current_count",
"type": "number",
"description": "当前已处理记录数",
"required": true
},
{
"name": "total_count",
"type": "number",
"description": "总记录数",
"required": true
},
{
"name": "message",
"type": "string",
"description": "额外提示信息",
"required": true
},
{
"name": "error",
"type": "string",
"description": "失败信息(可选)",
"required": true
},
{
"name": "download_url",
"type": "string",
"description": "任务完成后下载链接(若有)",
"required": true
},
{
"name": "update_time",
"type": "string",
"description": "最近一次状态更新时间(Unix ms 或 ISO 字符串)",
"required": true
}
],
"errors": [
{
"code": 400,
"message": "task_id 参数不能为空"
},
{
"code": 500,
"message": "查询失败或内部错误"
}
]
}
]
},
{
"groupName": "订单待审核模块",
"module": "order.reviewOrder",
"list": [
{
"method": "order.reviewOrder.list",
"description": "待审核订单列表,默认仅查询 step=0 的订单。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.reviewOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "order.reviewOrder.reviewOrder",
"description": "批量审核通过订单并进入待处理。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "订单 ID 数组;仅允许 ids 字段,建议传数组,也兼容逗号字符串或单值"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "首条更新记录 ID"
},
{
"name": "inspection_status",
"type": "string",
"required": true,
"description": "新的审核状态"
},
{
"name": "step",
"type": "number",
"required": true,
"description": "新的流程步骤"
},
{
"name": "updated_at",
"type": "string",
"required": true,
"description": "更新时间"
},
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "受影响行数"
},
{
"name": "ids",
"type": "array",
"required": true,
"description": "实际更新的订单 ID 列表"
}
],
"errors": [
{
"code": "400",
"description": "ids 不能为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
}
]
}
]
},
{
"groupName": "订单待处理模块",
"module": "order.pendingOrder",
"list": [
{
"method": "order.pendingOrder.list",
"description": "待处理订单列表,默认筛选 outbound_status != padding 且 step in [1,2]。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.pendingOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "order.pendingOrder.reverseReviewOrder",
"description": "将待处理订单反审回待审核状态。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": false,
"source": "body",
"description": "订单 ID 列表;兼容 ids / id / order_id,建议传 ids"
},
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "兼容单个订单 ID"
},
{
"name": "order_id",
"type": "number",
"required": false,
"source": "body",
"description": "兼容单个订单 ID"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "首条更新记录 ID"
},
{
"name": "inspection_status",
"type": "string",
"required": true,
"description": "新的审核状态"
},
{
"name": "step",
"type": "number",
"required": true,
"description": "新的流程步骤"
},
{
"name": "updated_at",
"type": "string",
"required": true,
"description": "更新时间"
},
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "受影响行数"
},
{
"name": "ids",
"type": "array",
"required": true,
"description": "实际更新的订单 ID 列表"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 不能为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
}
]
},
{
"method": "order.pendingOrder.markPendingOutboundOrder",
"description": "将待处理订单批量标记为待出库。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "订单 ID 正整数数组;不支持 id、order_id 或逗号字符串"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "首条更新记录 ID"
},
{
"name": "outbound_status",
"type": "string",
"required": true,
"description": "新的出库状态"
},
{
"name": "updated_at",
"type": "string",
"required": true,
"description": "更新时间"
},
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "受影响行数"
},
{
"name": "ids",
"type": "array",
"required": true,
"description": "实际更新的订单 ID 列表"
}
],
"errors": [
{
"code": "400",
"description": "ids 必须为正整数数组"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
}
]
},
{
"method": "order.pendingOrder.cancelOrder",
"description": "将待处理订单批量取消,仅允许当前状态可取消的订单。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "订单 ID 正整数数组;不支持 id、order_id 或逗号字符串"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "首条更新记录 ID"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "新的订单状态"
},
{
"name": "step",
"type": "number",
"required": true,
"description": "新的流程步骤"
},
{
"name": "updated_at",
"type": "string",
"required": true,
"description": "更新时间"
},
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "受影响行数"
},
{
"name": "ids",
"type": "array",
"required": true,
"description": "实际更新的订单 ID 列表"
}
],
"errors": [
{
"code": "400",
"description": "ids 必填或当前状态不允许取消"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
}
]
},
{
"method": "order.pendingOrder.allocateExpressCode",
"description": "批量分配待处理订单的快递号,接收订单对象数组,复用 express.createWaybillCodePipeline。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "orders",
"type": "array",
"required": true,
"source": "body",
"description": "订单对象数组;每个对象应为待处理订单列表或详情中获取的原始订单对象。每个订单对象必须包含 order_id 与 business_key;sys_platform_code 与 logistics_code 为订单对象自带字段,前端无需额外拼装或从外部构造,直接原样回传订单对象即可。其余字段会原样透传给运单创建链路。business_key 说明:business_key 是运单创建的序号键数组(例如:新分配 1 个运单号时传 [1];订单拆单时可能传 [2,3]),该字段会在 createWaybillCodePipeline 的返回 data 中原样返回,便于前端关联订单与运单创建结果。"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功时为 success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,200 表示成功"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "返回信息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "createWaybillCodePipeline 返回的运单创建结果,包含 success/failed 列表与 summary 等字段"
}
],
"errors": [
{
"code": "400",
"message": "入参格式错误或必填字段缺失"
},
{
"code": "500",
"message": "运单创建链路或第三方快递接口调用失败"
}
]
},
{
"method": "order.pendingOrder.allocateStorage",
"description": "按订单批量分配储位(迁移自 order.storageAllocation.allocateStorage)。这是一个异步提交接口:调用后接口立即返回受理信息(包含 request_id),后端异步执行实际的储位分配与锁定操作;仓库上下文由当前登录用户提供(ctx.user.store_id)。接口不会在同步响应中返回分配明细(如 requested_order_ids、allocated_order_ids 等),客户端可通过请求 ID 或事件/查询链路获取最终结果。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "allow_storage_location / allowStorageLocation / is_allow_storage / isAllowStorage",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否允许使用存储储位,支持多种字段别名。"
},
{
"name": "order_ids / orderIds / ids / order_id / orderId / id",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单 ID 列表,支持数组、逗号分隔字符串或单个 ID(兼容多种别名)。"
}
],
"response": [
{
"name": "request_id",
"type": "string",
"required": true,
"description": "请求 ID(后端生成的唯一标识),用于查询任务状态或结果"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "生效的仓库 ID(来自当前用户 store_id)"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "受理提示信息,通常为 '请求已受理,后端异步处理中' 或错误说明"
}
],
"errors": [
{
"code": 400,
"message": "缺少仓库上下文(用户登录上下文无 store_id)"
},
{
"code": 400,
"message": "订单ID 不能为空(请求中未包含有效 order_ids)"
},
{
"code": 409,
"message": "存在并发锁定或数据库约束导致的冲突(场景少见,视底层实现抛出)"
},
{
"code": 500,
"message": "内部错误:模型不可用或数据库/锁定操作失败"
}
]
},
{
"method": "order.pendingOrder.allocateStorageProgress",
"description": "按 request_id 查询储位分配异步任务状态/结果(由 allocateStorage 提交)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "request_id / requestId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务请求 ID,兼容字段 requestId"
}
],
"response": [
{
"name": "request_id",
"type": "string",
"required": true,
"description": "请求 ID(后端生成的唯一标识)"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)"
},
{
"name": "result",
"type": "object",
"required": false,
"description": "成功时返回底层分配结果,结构视实现而定"
},
{
"name": "error",
"type": "string",
"required": false,
"description": "失败时返回的错误信息"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "关联仓库 ID(若任务关联仓库时返回)"
},
{
"name": "update_time",
"type": "string",
"required": false,
"description": "最近一次状态更新时间,ISO8601 字符串"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "额外提示信息"
}
],
"errors": [
{
"code": 400,
"message": "request_id 为空或格式不合法"
},
{
"code": 500,
"message": "内部错误"
}
]
},
{
"method": "order.pendingOrder.syncOrderIds",
"description": "同步待处理订单入口,支持批量传入 order_ids。服务端会按 create_channel 分组派发同步任务;若命中 SN 管理订单(is_sn_mgmt=Y),该订单会被拦截并标记失败,不允许走批量回传,需改用单订单回传。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_ids / orderIds / ids / order_id / orderId / id",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单 ID 列表,支持数组、逗号分隔字符串或单个 ID。服务端会校验订单状态并执行批量同步拦截规则(含 SN 订单限制)。"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功为 success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,200 表示成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回信息,当前仅做受理提示"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "服务层返回值,当前仅透传 order_ids"
}
],
"errors": [
{
"code": 400,
"message": "order_ids 不能为空或格式错误"
},
{
"code": 400,
"message": "SN订单不支持批量回传,请改用单订单回传"
},
{
"code": 500,
"message": "内部错误:服务层同步失败"
}
]
},
{
"method": "order.pendingOrder.cancelAllocateStorage",
"description": "待处理模块的取消分配储位入口,直接对接 system service 的 cancelAllocateStorage。仅接受订单ID(order_ids)作为入参,不接受 allow_storage_location 或 warehouse_id/warehouseId;仓库上下文来自当前登录用户的 store_id。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_ids / orderIds / ids / order_id / orderId / id",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单 ID 列表;支持数组、逗号字符串或单个 ID(兼容多种别名)。"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功为 success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,200 表示成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回信息,成功或部分成功时给出摘要"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "取消分配汇总结果,包含下列字段",
"children": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "生效的仓库 ID(来自当前用户 store_id)"
},
{
"name": "requested_order_ids",
"type": "array",
"required": true,
"description": "请求中传入的订单 ID 列表(规范化后)"
},
{
"name": "cancellable_order_ids",
"type": "array",
"required": true,
"description": "实际可以取消分配的订单 ID 列表"
},
{
"name": "skipped_orders",
"type": "array",
"required": true,
"description": "被跳过的订单数组,每项至少包含 order_id 与 skipped_reason(如 not_found / not_allocated / no_allocation)"
},
{
"name": "orders",
"type": "array",
"required": true,
"description": "每个订单的取消分配结果数组,包含成功与跳过记录(合并 skipped_orders 与成功结果)"
},
{
"name": "picking_count",
"type": "number",
"required": true,
"description": "本次被取消的 picking 行数"
},
{
"name": "storage_unlock_summary",
"type": "array",
"required": true,
"description": "按 storage_id 汇总的解锁数量数组({storage_id, unlocked_quantity})"
},
{
"name": "stock_unlock_summary",
"type": "array",
"required": true,
"description": "按 stock_id 汇总的解锁数量数组({stock_id, unlocked_quantity})"
}
]
}
],
"errors": [
{
"code": 400,
"message": "缺少仓库上下文"
},
{
"code": 400,
"message": "订单ID不能为空"
},
{
"code": 500,
"message": "内部错误:模型不可用或数据库/回滚失败"
}
]
},
{
"method": "order.pendingOrder.updateOrderPlatform",
"description": "批量修改待处理订单的平台信息。用 code 查找 wms_platform 表,若平台存在则将订单的 sys_platform_code 和 sys_platform_name 更新为该平台的 code/name;若平台不存在则返回错误。只操作当前仓库的当前订单表,不处理其他订单表。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_ids",
"type": "number[]",
"required": true,
"source": "body",
"description": "订单ID 正整数数组,不能为空"
},
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "平台编码,对应 wms_platform.code"
}
],
"response": [
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "实际更新行数"
},
{
"name": "sys_platform_code",
"type": "string",
"required": true,
"description": "更新后的平台编码"
},
{
"name": "sys_platform_name",
"type": "string",
"required": true,
"description": "更新后的平台名称"
}
],
"errors": [
{
"code": 400,
"message": "order_ids 不能为空"
},
{
"code": 400,
"message": "code 不能为空"
},
{
"code": 404,
"message": "平台不存在:<code>"
},
{
"code": 400,
"message": "缺少仓库上下文"
}
]
},
{
"method": "order.pendingOrder.updateOrderExpress",
"description": "批量修改待处理订单的快递信息。用 express_code 从当前仓库快递列表(带缓存)中查找对应项:若为自定义映射(is_system_setting=true),sys_logistics_code/name 写系统快递编码和名称,logistics_code/name 写自定义编码和名称;若为系统快递(is_system_setting=false),四个字段均写系统快递的 code/name;未找到则报错。只操作当前仓库的当前订单表,不处理其他订单表。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_ids",
"type": "number[]",
"required": true,
"source": "body",
"description": "订单ID 正整数数组,不能为空"
},
{
"name": "express_code",
"type": "string",
"required": true,
"source": "body",
"description": "快递编码,可为系统编码或仓库自定义编码"
}
],
"response": [
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "实际更新行数"
},
{
"name": "sys_logistics_code",
"type": "string",
"required": true,
"description": "写入的系统快递编码"
},
{
"name": "sys_logistics_name",
"type": "string",
"required": true,
"description": "写入的系统快递名称"
},
{
"name": "logistics_code",
"type": "string",
"required": true,
"description": "写入的快递编码(自定义或系统)"
},
{
"name": "logistics_name",
"type": "string",
"required": true,
"description": "写入的快递名称(自定义或系统)"
}
],
"errors": [
{
"code": 400,
"message": "order_ids 不能为空"
},
{
"code": 400,
"message": "order_ids 仅支持正整数数组"
},
{
"code": 400,
"message": "express_code 不能为空"
},
{
"code": 404,
"message": "快递编码 <express_code> 不存在"
}
]
},
{
"method": "order.pendingOrder.cloneOrder",
"description": "克隆待处理订单。完整流程:1. 查找原订单,校验可取消状态(step 0/1/2/3);2. 若原订单已分配储位(storage_status='fin'),先清除已分配库存;3. 取消原订单(step→9, status→cancel),记录克隆日志;4. 以原订单业务数据创建新订单,所有流程状态字段重置为初始落库状态;5. 克隆订单明细(含 stock_id),重置 order_id 为新订单 ID;6. 对新订单记录克隆创建日志。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_id",
"type": "number",
"required": true,
"source": "body",
"description": "原订单ID,正整数"
}
],
"response": [
{
"name": "source_order_id",
"type": "number",
"required": true,
"description": "原订单ID(已取消)"
},
{
"name": "new_order_id",
"type": "number",
"required": true,
"description": "新订单ID(克隆生成)"
}
],
"errors": [
{
"code": 400,
"message": "order_id 不能为空"
},
{
"code": 400,
"message": "order_id 仅支持正整数"
},
{
"code": 404,
"message": "订单不存在"
},
{
"code": 400,
"message": "订单状态不允许克隆(仅支持 step 0/1/2/3)"
}
]
},
{
"method": "order.pendingOrder.createOrder",
"description": "手动创建待处理订单。根据货主策略(need_order_approval)决定初始步骤:need_order_approval=1 进待审核(step=0),need_order_approval=0 直接进待处理(step=1)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "store_id",
"type": "number",
"required": true,
"source": "body",
"description": "货主ID(正整数)"
},
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "收件人姓名"
},
{
"name": "mobile",
"type": "string",
"required": false,
"source": "body",
"description": "收件人手机号,mobile 与 tel 至少填一项"
},
{
"name": "tel",
"type": "string",
"required": false,
"source": "body",
"description": "收件人电话,mobile 与 tel 至少填一项"
},
{
"name": "detail_address",
"type": "string",
"required": true,
"source": "body",
"description": "详细地址"
},
{
"name": "province",
"type": "string",
"required": true,
"source": "body",
"description": "省份(必填,空值返回 400)"
},
{
"name": "city",
"type": "string",
"required": true,
"source": "body",
"description": "城市(必填,空值返回 400)"
},
{
"name": "area",
"type": "string",
"required": true,
"source": "body",
"description": "区/县(必填,空值返回 400)"
},
{
"name": "town",
"type": "string",
"required": false,
"source": "body",
"description": "镇/街道"
},
{
"name": "zip_code",
"type": "string",
"required": false,
"source": "body",
"description": "邮编"
},
{
"name": "items",
"type": "array",
"required": true,
"source": "body",
"description": "订单明细数组,每项含 item_id(商品主键,必填,正整数)和 plan_qty(计划数量,正整数);item_name(优先外部传入,其次从 StockStore 缓存获取,最后兜底'商品')、order_line_no、actual_price 为可选"
},
{
"name": "delivery_order_code",
"type": "string",
"required": false,
"source": "body",
"description": "订单号,不填则自动生成(SYS + 时间戳 + 随机4位)"
},
{
"name": "logistics_code",
"type": "string",
"required": false,
"source": "body",
"description": "快递编码,不填则读货主默认快递策略(policy_config.default_express_code)"
},
{
"name": "logistics_name",
"type": "string",
"required": false,
"source": "body",
"description": "快递名称"
},
{
"name": "sys_platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "系统平台编码,不填则读货主默认平台策略(policy_config.default_platform_code)"
},
{
"name": "source_platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台编码"
},
{
"name": "source_order_codes",
"type": "string",
"required": false,
"source": "body",
"description": "来源订单号"
},
{
"name": "order_type",
"type": "string",
"required": false,
"source": "body",
"description": "订单类型"
},
{
"name": "is_urgency",
"type": "string",
"required": false,
"source": "body",
"description": "是否紧急:Y/N,默认 N"
},
{
"name": "invoice_flag",
"type": "string",
"required": false,
"source": "body",
"description": "是否需要发票:Y/N,默认 N"
}
],
"response": [
{
"name": "order_id",
"type": "number",
"required": true,
"description": "新创建的订单 ID"
},
{
"name": "delivery_order_code",
"type": "string",
"required": true,
"description": "订单号(传入值或自动生成值)"
},
{
"name": "step",
"type": "number",
"required": true,
"description": "初始步骤:0=待审核,1=待处理"
},
{
"name": "step_label",
"type": "string",
"required": true,
"description": "步骤说明:待审核 / 待处理"
},
{
"name": "items_count",
"type": "number",
"required": true,
"description": "商品种类数"
},
{
"name": "items_total",
"type": "number",
"required": true,
"description": "商品总件数"
}
],
"errors": [
{
"code": 400,
"message": "必填字段缺失(含 province/city/area)、items 格式错误(item_id 须为正整数)或 delivery_order_code 重复"
},
{
"code": 404,
"message": "货主与仓库无有效合约关系(getContractConfig 返回 null 时降级为需审核)"
}
],
"notes": [
"使用 item_id 直接匹配商品主键,不依赖外部系统商品同步;item_id 可通过 singleitem.synchronize 返回的 itemId 获取",
"province/city/area 为必填项,空值返回 400"
]
},
{
"method": "order.pendingOrder.downloadCreateTemplate",
"description": "下载创建订单的 Excel 导入模板。返回 base64 编码的 xlsx 文件,前端解码后作为附件下载。表头中标注 * 的列为必填项,多行相同订单号的行组成一个完整订单。(已作废)",
"status": "deprecated",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "base64",
"type": "string",
"required": true,
"description": "base64 编码的 xlsx 文件内容"
},
{
"name": "filename",
"type": "string",
"required": true,
"description": "建议保存的文件名"
},
{
"name": "mime",
"type": "string",
"required": true,
"description": "文件 MIME 类型"
}
],
"errors": []
},
{
"method": "order.pendingOrder.importOrdersFromExcel",
"description": "通过 Excel 文件批量创建订单。接受 base64 编码的 xlsx 内容,按订单号分组,每组创建一个订单(step 由货主策略决定)。每行代表一条商品明细;同一订单号的多行组成一个完整订单,头信息取每组第一行。(已作废)",
"status": "deprecated",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "file_base64",
"type": "string",
"required": true,
"source": "body",
"description": "base64 编码的 .xlsx 文件内容"
}
],
"response": [
{
"name": "total",
"type": "number",
"required": true,
"description": "解析到的订单总数"
},
{
"name": "success_count",
"type": "number",
"required": true,
"description": "创建成功的订单数"
},
{
"name": "fail_count",
"type": "number",
"required": true,
"description": "创建失败的订单数"
},
{
"name": "success_orders",
"type": "array",
"required": true,
"description": "成功订单列表,每项含 delivery_order_code、order_id、step、step_label"
},
{
"name": "fail_orders",
"type": "array",
"required": true,
"description": "失败订单列表,每项含 delivery_order_code、error(失败原因)"
}
],
"errors": [
{
"code": "400",
"message": "file_base64 为空、Excel 格式无效或无有效数据行"
}
]
},
{
"method": "order.pendingOrder.parseAddress",
"description": "智能地址解析:使用 AI 将非结构化地址字符串解析为省/市/区/详细地址/收件人/手机号",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "address",
"type": "string",
"required": true,
"source": "body",
"description": "原始地址字符串(必填),如\"张三 13800138000 广东省广州市天河区体育西路100号\""
}
],
"requestBody": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "1=成功,0=失败"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "解析成功时返回 province/city/area/detailAddress/name/mobile"
},
{
"name": "data.province",
"type": "string",
"required": false,
"description": "省份,如 广东省"
},
{
"name": "data.city",
"type": "string",
"required": false,
"description": "城市,如 广州市"
},
{
"name": "data.area",
"type": "string",
"required": false,
"description": "区/县,如 天河区"
},
{
"name": "data.town",
"type": "string",
"required": false,
"description": "乡镇/街道,如 员村街道"
},
{
"name": "data.detailAddress",
"type": "string",
"required": false,
"description": "详细地址,如 体育西路100号"
},
{
"name": "data.name",
"type": "string",
"required": false,
"description": "收件人姓名,如 张三"
},
{
"name": "data.mobile",
"type": "string",
"required": false,
"description": "收件人手机号,如 13800138000"
}
],
"errors": [
{
"code": 400,
"message": "地址字符串不能为空"
},
{
"code": 500,
"message": "地址解析失败(AI服务异常或密钥未配置)"
}
],
"notes": [
"方法部署位置:systemMethods/order/pendingOrder/parseAddress",
"使用 DeepSeek AI 模型进行智能解析",
"解析结果可直接回填到 createOrder 的收件人信息字段",
"未识别到的字段返回空字符串"
]
}
]
},
{
"groupName": "订单复核模块",
"module": "order.recheckOrder",
"list": [
{
"method": "order.recheckOrder.scanOrder",
"description": "扫码查询订单(支持运单号与车号)并返回订单详情。车号命中时按 pick_mode 返回语义化结构。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "keyword / value / waybill_no / waybillCode / waybill_code / cart_code / cartCode",
"type": "string",
"required": true,
"source": "body|query",
"description": "扫描关键词;优先按运单号匹配,未命中时回退到 wms_wave_pick_task.current_cart_code_snapshot / wms_wave_pick_task_order.cart_code_snapshot 车号匹配,支持别名 waybillCode/waybill_code/cart_code/cartCode"
}
],
"response": [
{
"name": "match_type",
"type": "string",
"required": true,
"description": "命中类型:waybill(运单号命中)/ cart(车号命中)"
},
{
"name": "cart_match_view",
"type": "object|null",
"required": true,
"description": "仅 cart 命中返回对象,waybill 命中返回 null"
},
{
"name": "cart_match_view.mode_code",
"type": "number",
"required": false,
"description": "波次类型编码(pick_mode)"
},
{
"name": "cart_match_view.mode_name",
"type": "string",
"required": false,
"description": "波次类型名称"
},
{
"name": "cart_match_view.view_type",
"type": "string",
"required": false,
"description": "语义化视图类型:groups/orders/pick_groups/box_groups"
},
{
"name": "cart_match_view.task",
"type": "object",
"required": false,
"description": "任务摘要信息"
},
{
"name": "cart_match_view.groups",
"type": "array",
"required": false,
"description": "仅 mode_code=1/5 返回,按 wave 分组"
},
{
"name": "cart_match_view.orders",
"type": "array",
"required": false,
"description": "仅 mode_code=2 返回,直接返回订单列表"
},
{
"name": "cart_match_view.pick_groups",
"type": "array",
"required": false,
"description": "仅 mode_code=3 返回,按 pick_status 分组"
},
{
"name": "cart_match_view.box_groups",
"type": "array",
"required": false,
"description": "仅 mode_code=4 返回,按 box_no 分组"
},
{
"name": "order_id",
"type": "number",
"required": true,
"description": "准确的订单 ID(供 confirmRecheck 使用)"
},
{
"name": "waybill_no",
"type": "string",
"required": true,
"description": "匹配到的运单号"
},
{
"name": "order",
"type": "object",
"required": true,
"description": "订单头对象"
},
{
"name": "items",
"type": "array",
"required": true,
"description": "订单商品明细"
},
{
"name": "expresses",
"type": "array",
"required": true,
"description": "运单信息数组"
},
{
"name": "logs",
"type": "array",
"required": true,
"description": "相关操作日志"
}
],
"errors": [
{
"code": "400",
"message": "扫描关键词不能为空",
"description": "扫描关键词不能为空"
},
{
"code": "404",
"message": "未找到对应订单",
"description": "未找到对应订单"
},
{
"code": "400",
"message": "订单未拣货,不允许复核。",
"description": "订单未拣货,不允许复核。"
}
]
},
{
"method": "order.recheckOrder.confirmRecheck",
"description": "按订单 ID 确认复核并记录复核任务到 wms_recheck_task(入参兼容 id/orderId)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_id / id / orderId",
"type": "string|number",
"required": true,
"source": "body|query",
"description": "订单 ID;优先使用 order_id,兼容别名 id 与 orderId"
}
],
"response": [
{
"name": "order_id",
"type": "number",
"description": "订单 ID"
},
{
"name": "waybill_no",
"type": "string",
"description": "运单号"
},
{
"name": "recheck_status",
"type": "string",
"description": "复核结果状态"
},
{
"name": "recheck_time",
"type": "string",
"description": "复核时间(ISO 字符串)"
},
{
"name": "review_no",
"type": "string",
"description": "复核任务编号"
}
],
"errors": [
{
"code": "400",
"description": "订单ID不能为空"
},
{
"code": "404",
"description": "未找到对应订单"
},
{
"code": "400",
"description": "订单未拣货,不允许复核。"
}
]
}
]
},
{
"groupName": "订单波次模块",
"module": "order.wave",
"list": [
{
"method": "order.wave.waveStrategyList",
"description": "查询当前仓库波次策略列表。仅查询当前登录仓库在 wms_wave_strategy 中的数据,返回标准 list/pagination 结构。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "strategy_type",
"type": "number",
"required": false,
"source": "body",
"description": "仅支持 1=散单、2=团购;与 where.strategy_type 同时存在时以顶层 strategy_type 为准。"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "当前仅支持 where.strategy_type(1/2);其余 where 字段暂不支持。"
},
{
"name": "calculate_next_fetch_order_count / calculateNextFetchOrderCount",
"type": "number",
"required": false,
"source": "body",
"description": "0-不计算(默认),1-计算并返回每条策略的 next_fetch_order_count;支持别名 calculateNextFetchOrderCount"
},
{
"name": "debug",
"type": "number",
"required": false,
"source": "body",
"description": "0-不启用(默认),1-启用调试输出,返回每条策略的 next_fetch_order_list(含结构/快递/货主ID等指标明细)"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "策略列表,每项为波次策略记录",
"children": [
{
"name": "id",
"type": "number",
"description": "策略ID"
},
{
"name": "strategy_name",
"type": "string",
"description": "策略名称"
},
{
"name": "warehouse_id",
"type": "number",
"description": "仓库ID"
},
{
"name": "strategy_type",
"type": "number",
"description": "策略类型:1-散单 2-团购"
},
{
"name": "status",
"type": "number",
"description": "状态:1-启用 0-停用"
},
{
"name": "order_min_sku",
"type": "number",
"description": "订单最小 SKU 种类数(可为空)"
},
{
"name": "order_max_sku",
"type": "number",
"description": "订单最大 SKU 种类数(可为空)"
},
{
"name": "order_min_qty",
"type": "number",
"description": "订单最小商品总数(可为空)"
},
{
"name": "order_max_qty",
"type": "number",
"description": "订单最大商品总数(可为空)"
},
{
"name": "min_same_structure",
"type": "number",
"description": "最小相同结构订单数(可为空)"
},
{
"name": "max_same_structure",
"type": "number",
"description": "最大相同结构订单数(可为空)"
},
{
"name": "require_same_express",
"type": "boolean",
"description": "是否要求相同快递"
},
{
"name": "allow_cross_owner",
"type": "boolean",
"description": "是否允许跨货主"
},
{
"name": "batch_mode",
"type": "number",
"description": "拣货模式"
},
{
"name": "batch_max_orders",
"type": "number",
"description": "批次最大订单数(可为空)"
},
{
"name": "batch_max_skus",
"type": "number",
"description": "批次最大 SKU 总数(可为空)"
},
{
"name": "group_batch_max_orders",
"type": "number",
"description": "团购批次最大订单数(可为空)"
},
{
"name": "allowed_owners",
"type": "array",
"description": "允许的货主 ID 列表(数组或 null)"
},
{
"name": "allowed_expresses",
"type": "array",
"description": "允许的快递编码列表(数组或 null)"
},
{
"name": "allowed_provinces",
"type": "array",
"description": "允许的省份列表(数组或 null)"
},
{
"name": "allowed_platforms",
"type": "array",
"description": "允许的平台列表(数组或 null)"
},
{
"name": "description",
"type": "string",
"description": "策略描述"
},
{
"name": "creator_name",
"type": "string",
"description": "创建人"
},
{
"name": "create_time",
"type": "string",
"description": "创建时间(ISO 字符串)"
},
{
"name": "update_time",
"type": "string",
"description": "更新时间(ISO 字符串)"
},
{
"name": "matched_order_count_filtered",
"type": "number",
"description": "按当前仓库且仅统计未在波次(step!=0)并满足同结构区间后的命中订单数"
},
{
"name": "next_fetch_order_count",
"type": "number",
"description": "按当前策略口径预演一次自动抓取时,预计会选中的订单数量;未开启计算时返回 0"
},
{
"name": "next_fetch_order_list",
"type": "object",
"description": "调试字段,仅 debug=1 时返回。包含候选订单明细及指标(结构、快递、货主ID 等)",
"children": [
{
"name": "candidate_count",
"type": "number",
"description": "当前策略匹配的候选订单总数"
},
{
"name": "candidates",
"type": "array",
"description": "候选订单明细列表(最多 500 条)",
"children": [
{
"name": "order_id",
"type": "number",
"description": "订单ID"
},
{
"name": "structure",
"type": "object",
"description": "商品结构(items_hash / items)"
},
{
"name": "express",
"type": "object",
"description": "快递信息(sys_logistics_code / logistics_code / logistics_name)"
},
{
"name": "store_id",
"type": "string",
"description": "货主ID"
},
{
"name": "items_count",
"type": "number",
"description": "SKU 种类数"
},
{
"name": "items_total",
"type": "number",
"description": "商品总件数"
},
{
"name": "wave_id",
"type": "number",
"description": "当前波次ID(0=未入波次)"
},
{
"name": "status",
"type": "string",
"description": "订单状态"
},
{
"name": "outbound_status",
"type": "string",
"description": "出库状态"
},
{
"name": "post_status",
"type": "string",
"description": "快递分配状态"
},
{
"name": "storage_status",
"type": "string",
"description": "储位分配状态"
}
]
}
]
}
]
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
}
],
"errors": [
{
"code": "400",
"description": "缺少仓库上下文或分页参数不合法"
},
{
"code": "400",
"description": "strategy_type 非法(仅支持 1/2)"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.wave.waveStrategyCreate",
"description": "新增波次策略。warehouse_id 与 creator_name 强制使用当前上下文,不接受外部覆盖。创建成功后会推进仓库的 wave_strategy_version 并失效相关缓存。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "strategy_name",
"type": "string",
"required": true,
"source": "body",
"description": "策略名称(必填)"
},
{
"name": "strategy_type",
"type": "number",
"required": true,
"source": "body",
"description": "策略类型(必填,正整数):1-散单 2-团购"
},
{
"name": "batch_mode",
"type": "number",
"required": true,
"source": "body",
"description": "拣货模式(必填,正整数)"
},
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "状态:1-启用 0-停用(可选)"
},
{
"name": "order_min_sku",
"type": "number",
"required": false,
"source": "body",
"description": "订单最小 SKU 种类数(可选,正整数或 null)"
},
{
"name": "order_max_sku",
"type": "number",
"required": false,
"source": "body",
"description": "订单最大 SKU 种类数(可选,正整数或 null)"
},
{
"name": "order_min_qty",
"type": "number",
"required": false,
"source": "body",
"description": "订单最小商品总数(可选,正整数或 null)"
},
{
"name": "order_max_qty",
"type": "number",
"required": false,
"source": "body",
"description": "订单最大商品总数(可选,正整数或 null)"
},
{
"name": "min_same_structure",
"type": "number",
"required": false,
"source": "body",
"description": "最小相同结构订单数(可选,正整数或 null)"
},
{
"name": "max_same_structure",
"type": "number",
"required": false,
"source": "body",
"description": "最大相同结构订单数(可选,正整数或 null)。注意:若传入值 >= 仓库配置的 min_group_order_fetch_quantity,则会被下调为 min_group_order_fetch_quantity - 1,最小为 1。"
},
{
"name": "batch_max_orders",
"type": "number",
"required": false,
"source": "body",
"description": "批次最大订单数(可选)"
},
{
"name": "batch_max_skus",
"type": "number",
"required": false,
"source": "body",
"description": "批次最大 SKU 总数(可选)"
},
{
"name": "group_batch_max_orders",
"type": "number",
"required": false,
"source": "body",
"description": "团购批次最大订单数(可选)"
},
{
"name": "require_same_express",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否要求相同快递(可选,布尔)"
},
{
"name": "allow_cross_owner",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否允许跨货主(可选,布尔)"
},
{
"name": "description",
"type": "string",
"required": false,
"source": "body",
"description": "策略描述(可选)"
},
{
"name": "allowed_provinces",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的省份列表(可选,支持数组、JSON 字符串或逗号分隔字符串)"
},
{
"name": "allowed_platforms",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的平台列表(可选,支持数组、JSON 字符串或逗号分隔字符串)"
},
{
"name": "allowed_owners",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的货主列表(可选,支持数组/JSON/逗号分隔);系统会校验所传货主是否在仓库可用货主范围内,非法值将导致 400 错误。"
},
{
"name": "allowed_expresses",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的快递编码列表(可选,支持数组/JSON/逗号分隔);系统会校验所传编码是否在可用快递列表内,非法值将导致 400 错误。"
},
{
"name": "wave_prefix",
"type": "string",
"required": false,
"source": "body",
"description": "波次编号前缀(可选),最多 5 个字符,如 D、B、A;不传则保持原值"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "创建的策略对象,字段同 order.wave.waveStrategyList.list[*] 所示"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "HTTP-like 状态码,成功时返回 200"
}
],
"errors": [
{
"code": "400",
"message": "缺少必填参数或参数校验失败(包括 allowed_owners/allowed_expresses 非法)"
},
{
"code": "500",
"message": "创建失败或内部错误"
}
]
},
{
"method": "order.wave.waveStrategyUpdate",
"description": "修改波次策略。warehouse_id 与 creator_name 强制使用当前上下文,不接受外部覆盖。id(或 strategy_id/strategyId)为必填主键,其他字段为可选更新;更新成功后会推进仓库的 wave_strategy_version 并失效相关缓存。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id / strategy_id / strategyId",
"type": "number",
"required": true,
"source": "body",
"description": "策略主键,兼容 id / strategy_id / strategyId(必填)"
},
{
"name": "strategy_name",
"type": "string",
"required": false,
"source": "body",
"description": "策略名称(可选)"
},
{
"name": "strategy_type",
"type": "number",
"required": false,
"source": "body",
"description": "策略类型(可选,正整数)"
},
{
"name": "batch_mode",
"type": "number",
"required": false,
"source": "body",
"description": "拣货模式(可选,正整数)"
},
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "状态:1-启用 0-停用(可选)"
},
{
"name": "order_min_sku",
"type": "number",
"required": false,
"source": "body",
"description": "订单最小 SKU 种类数(可选,正整数或 null)"
},
{
"name": "order_max_sku",
"type": "number",
"required": false,
"source": "body",
"description": "订单最大 SKU 种类数(可选,正整数或 null)"
},
{
"name": "order_min_qty",
"type": "number",
"required": false,
"source": "body",
"description": "订单最小商品总数(可选,正整数或 null)"
},
{
"name": "order_max_qty",
"type": "number",
"required": false,
"source": "body",
"description": "订单最大商品总数(可选,正整数或 null)"
},
{
"name": "min_same_structure",
"type": "number",
"required": false,
"source": "body",
"description": "最小相同结构订单数(可选,正整数或 null)"
},
{
"name": "max_same_structure",
"type": "number",
"required": false,
"source": "body",
"description": "最大相同结构订单数(可选,正整数或 null)。会受仓库 min_group_order_fetch_quantity 约束,接口会自动调整。"
},
{
"name": "batch_max_orders",
"type": "number",
"required": false,
"source": "body",
"description": "批次最大订单数(可选)"
},
{
"name": "batch_max_skus",
"type": "number",
"required": false,
"source": "body",
"description": "批次最大 SKU 总数(可选)"
},
{
"name": "group_batch_max_orders",
"type": "number",
"required": false,
"source": "body",
"description": "团购批次最大订单数(可选)"
},
{
"name": "require_same_express",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否要求相同快递(可选,布尔)"
},
{
"name": "allow_cross_owner",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否允许跨货主(可选,布尔)"
},
{
"name": "description",
"type": "string",
"required": false,
"source": "body",
"description": "策略描述(可选)"
},
{
"name": "allowed_provinces",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的省份列表(可选,支持数组/JSON/逗号分隔)"
},
{
"name": "allowed_platforms",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的平台列表(可选,支持数组/JSON/逗号分隔)"
},
{
"name": "allowed_owners",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的货主列表(可选,支持数组/JSON/逗号分隔);系统会校验所传货主是否在仓库可用货主范围内,非法值将导致 400 错误。"
},
{
"name": "allowed_expresses",
"type": "array|string",
"required": false,
"source": "body",
"description": "允许的快递编码列表(可选,支持数组/JSON/逗号分隔);系统会校验所传编码是否在可用快递列表内,非法值将导致 400 错误。"
},
{
"name": "wave_prefix",
"type": "string",
"required": false,
"source": "body",
"description": "波次编号前缀(可选),最多 5 个字符,如 D、B、A;不传则保持原值"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "更新后的策略对象,字段同 order.wave.waveStrategyList.list[*] 所示"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "HTTP-like 状态码,成功时返回 200"
}
],
"errors": [
{
"code": "400",
"message": "缺少 id 或无可更新字段或参数校验失败"
},
{
"code": "404",
"message": "波次策略不存在"
},
{
"code": "500",
"message": "更新失败或内部错误"
}
]
},
{
"method": "order.wave.waveStrategyQuickScan",
"description": "提交波次策略快速扫描异步任务。无外部参数,使用当前仓库上下文;同一仓库同一时刻仅允许一个任务运行,若已有运行任务直接返回已有 task_id。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "status",
"type": "string",
"required": true,
"description": "提交状态,固定 success"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(用于后续查询进度)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "仓库 ID(来自当前上下文)"
},
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态(一般为 submitted 或 running)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "可选提示信息"
},
{
"name": "accepted_at",
"type": "string",
"required": false,
"description": "任务受理时间(ISO 字符串)"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "500",
"description": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.waveStrategyFetchPda",
"description": "按策略提交并创建抓取主流程任务(PDA)。当前为最小主流程:进行入参校验并创建任务记录,返回创建结果与计划预览;后续扫描/执行阶段将扩展为完整执行流。 注意:当存在未完成任务时,接口返回 fetch_state=3 且同时返回 existing task_id/task_no,前端可直接进入拣货流程。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "strategy_id / strategyId",
"type": "number",
"required": true,
"source": "body",
"description": "策略ID(正整数,支持下划线/驼峰)"
},
{
"name": "cart_id / cartId",
"type": "string|number",
"required": false,
"source": "body",
"description": "可选,关联拣货车/作业车ID,支持字符串或数字,用于记录作业上下文"
},
{
"name": "source / operation_source",
"type": "string",
"required": false,
"source": "body",
"description": "可选,操作来源标识(例如 pda/admin/manual/auto),用于审计与分流策略"
},
{
"name": "strategy_params / strategyParams",
"type": "object",
"required": false,
"source": "body",
"description": "可选,策略参数透传对象(如 order_min_qty/order_max_qty/allow_cross_owner 等),在创建任务时作为策略覆盖或附加参数使用"
}
],
"response": [
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态:created(已创建主流程任务),后续可能为 running/success/failed"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务唯一 ID(用于后续查询或关联)"
},
{
"name": "task_no",
"type": "string",
"required": true,
"description": "任务业务编号(便于展示与关联)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "生效的仓库 ID(来自当前上下文,如可用则返回)"
},
{
"name": "strategy_id",
"type": "number",
"required": false,
"description": "生效的策略 ID(与入参保持一致,兼容回传)"
},
{
"name": "plan",
"type": "object",
"required": true,
"description": "任务计划/执行预览对象,描述本次任务预估的执行计划",
"children": [
{
"name": "estimated_wave_count",
"type": "number",
"description": "预估将创建的波次数量(若适用)"
},
{
"name": "estimated_order_count",
"type": "number",
"description": "预估涉及的订单数量"
},
{
"name": "estimated_items_total",
"type": "number",
"description": "预估涉及的商品总件数"
},
{
"name": "preview_orders",
"type": "array",
"description": "可选:示例性订单 ID 列表或摘要(仅为预览,实际执行结果以最终任务为准)"
}
]
},
{
"name": "plan_summary",
"type": "string",
"required": true,
"description": "计划摘要字符串,便于前端在受理后快速展示(例如:'创建 3 个波次,涉及 120 单,约 450 件')"
},
{
"name": "validation_errors",
"type": "array",
"required": false,
"description": "当入参校验失败时返回的数组,每项为 { field, message } 对象,供前端展示或定位问题"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "可选提示信息或错误说明(创建失败时返回简短说明)"
},
{
"name": "fetch_state",
"type": "number",
"required": true,
"description": "抓取结果三态:1=成功创建任务(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可进入拣货流程)"
},
{
"name": "tip",
"type": "string",
"required": false,
"description": "简短提示,用于向前端展示简要原因或下一步建议"
},
{
"name": "can_enter_pick_flow",
"type": "boolean",
"required": false,
"description": "仅当 fetch_state=3 时为 true,表示前端可直接进入拣货流程"
}
],
"errors": [
{
"code": "400",
"description": "参数校验失败(详见 validation_errors)"
},
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "500",
"description": "创建任务失败或内部错误,message 字段含简短说明"
}
]
},
{
"method": "order.wave.waveStrategyFetchAdmin",
"description": "按策略提交并创建抓取主流程任务(后台管理)。当前为最小主流程:执行入参校验并创建任务记录,返回创建结果与计划预览;后续将扩展完整扫描/执行链路。 注意:当存在未完成任务时,接口返回 fetch_state=3 且同时返回 existing task_id/task_no,前端可直接进入拣货流程。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "strategy_id / strategyId",
"type": "number",
"required": true,
"source": "body",
"description": "策略ID(正整数,支持下划线/驼峰)"
},
{
"name": "cart_id / cartId",
"type": "string|number",
"required": false,
"source": "body",
"description": "可选,关联拣货车/作业车ID,用于记录作业上下文或幂等识别"
},
{
"name": "source / operation_source",
"type": "string",
"required": false,
"source": "body",
"description": "可选,操作来源标识(例如 admin/pda/manual/auto),用于审计与分流策略"
},
{
"name": "strategy_params / strategyParams",
"type": "object",
"required": false,
"source": "body",
"description": "可选,策略参数透传对象(如 order_min_qty/order_max_qty/allow_cross_owner 等),在创建任务时作为策略覆盖或附加参数使用"
}
],
"response": [
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态:created(已创建主流程任务),后续可能为 running/success/failed"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务唯一 ID(用于后续查询或关联)"
},
{
"name": "task_no",
"type": "string",
"required": true,
"description": "任务业务编号(便于展示与关联)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "生效的仓库 ID(来自当前上下文,如可用则返回)"
},
{
"name": "strategy_id",
"type": "number",
"required": false,
"description": "生效的策略 ID(与入参保持一致,兼容回传)"
},
{
"name": "plan",
"type": "object",
"required": true,
"description": "任务计划/执行预览对象,描述本次任务预估的执行计划",
"children": [
{
"name": "estimated_wave_count",
"type": "number",
"description": "预估将创建的波次数量(若适用)"
},
{
"name": "estimated_order_count",
"type": "number",
"description": "预估涉及的订单数量"
},
{
"name": "estimated_items_total",
"type": "number",
"description": "预估涉及的商品总件数"
},
{
"name": "preview_orders",
"type": "array",
"description": "可选:示例性订单 ID 列表或摘要(仅为预览,实际执行结果以最终任务为准)"
}
]
},
{
"name": "plan_summary",
"type": "string",
"required": true,
"description": "计划摘要字符串,便于前端在受理后快速展示(例如:'创建 3 个波次,涉及 120 单,约 450 件')"
},
{
"name": "validation_errors",
"type": "array",
"required": false,
"description": "当入参校验失败时返回的数组,每项为 { field, message } 对象,供前端展示或定位问题"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "可选提示信息或错误说明(创建失败时返回简短说明)"
},
{
"name": "fetch_state",
"type": "number",
"required": true,
"description": "抓取结果三态:1=成功创建任务(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可进入拣货流程)"
},
{
"name": "tip",
"type": "string",
"required": false,
"description": "简短提示,用于向前端展示简要原因或下一步建议"
},
{
"name": "can_enter_pick_flow",
"type": "boolean",
"required": false,
"description": "仅当 fetch_state=3 时为 true,表示前端可直接进入拣货流程"
}
],
"errors": [
{
"code": "400",
"description": "参数校验失败(详见 validation_errors)"
},
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "500",
"description": "创建任务失败或内部错误,message 字段含简短说明"
}
]
},
{
"method": "order.wave.waveStrategyQuickScanTaskProgress",
"description": "查询波次策略快速扫描任务进度。接受 task_id / taskId,若未找到返回 state='not_found'。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body",
"description": "任务 ID(下划线或驼峰兼容,必填)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID"
},
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态:submitted/running/success/failed/not_found"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "仓库 ID"
},
{
"name": "total_order_count",
"type": "number",
"required": false,
"description": "扫描订单总数"
},
{
"name": "processed_order_count",
"type": "number",
"required": false,
"description": "已处理订单数"
},
{
"name": "matched_order_count",
"type": "number",
"required": false,
"description": "命中策略的订单数"
},
{
"name": "unmatched_order_count",
"type": "number",
"required": false,
"description": "未命中策略的订单数"
},
{
"name": "progress_percent",
"type": "number",
"required": false,
"description": "进度百分比(0-100)"
},
{
"name": "submitted_at",
"type": "string",
"required": false,
"description": "提交时间(timestamp 或 ISO)"
},
{
"name": "start_time",
"type": "string",
"required": false,
"description": "实际开始时间(ISO)"
},
{
"name": "end_time",
"type": "string",
"required": false,
"description": "结束时间(ISO)"
},
{
"name": "error_message",
"type": "string",
"required": false,
"description": "错误信息(若失败)"
},
{
"name": "error_code",
"type": "string",
"required": false,
"description": "错误码(若失败)"
},
{
"name": "duration_ms",
"type": "number",
"required": false,
"description": "耗时,毫秒"
}
],
"errors": [
{
"code": "400",
"description": "task_id 参数不能为空"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "order.wave.groupOrderFetchList",
"description": "按机器结构分组的可抓取列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "distinguish_express",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否区分快递(影响分组粒度)"
},
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID(仅作为筛选条件)"
},
{
"name": "same_order_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "最小同组订单数量阈值(>=)。若显式传入有效数值则按传入值使用;未传入时使用仓库配置 min_group_order_fetch_quantity(默认 13)。"
},
{
"name": "shop_name",
"type": "string",
"required": false,
"source": "body",
"description": "店铺名称(模糊匹配)"
},
{
"name": "include_sku",
"type": "string",
"required": false,
"source": "body",
"description": "仅保留包含该 SKU 的分组(页内过滤)"
},
{
"name": "return_order_ids",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否在结果中返回组内订单ID列表"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "分组列表,items 示例见实现:包含 item_detail_machine/item_snapshot/group_count 等字段"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
}
],
"errors": [
{
"code": "400",
"description": "缺少仓库上下文或参数格式错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.wave.singleFetchByIds",
"description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / order_ids / orderIds",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单 ID 列表;支持数组、逗号分隔字符串或单个 ID。入参会被去重并转换为正整数。字段解析优先顺序:ids -> order_ids -> orderIds。"
}
],
"response": [
{
"name": "ids",
"type": "array",
"required": true,
"description": "请求归一化后的 ids 列表(去重且为正整数)"
},
{
"name": "wave_id",
"type": "number",
"required": true,
"description": "创建的波次 ID;若无可抓取订单返回 0"
},
{
"name": "wave_no",
"type": "string",
"required": true,
"description": "创建的波次号;无可抓取时为空字符串"
},
{
"name": "fetched_order_ids",
"type": "array",
"required": true,
"description": "实际被抓取并成功分配到波次的订单 ID 列表(为归一化后的 ids 的子集)"
},
{
"name": "fetched_order_count",
"type": "number",
"required": true,
"description": "实际被抓取的订单数量(等于 fetched_order_ids.length)"
},
{
"name": "excluded_existing_wave_order_ids",
"type": "array",
"required": false,
"description": "原始入参中已在其它波次中的订单 ID(被排除,不会被抓取)"
},
{
"name": "skipped_order_ids",
"type": "array",
"required": false,
"description": "因订单状态不符、正在出库或其他业务原因被跳过的订单 ID(不会被抓取)"
},
{
"name": "not_found_order_ids",
"type": "array",
"required": false,
"description": "入参中未在数据库中找到的订单 ID"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文或 ids 参数不能为空或格式错误;当入参包含非法字段或别名冲突时也会返回 400"
},
{
"code": "500",
"description": "抓取失败或内部错误"
}
]
},
{
"method": "order.wave.waveStrategyFallbackOrderList",
"description": "基于波次策略的回退候选订单列表。该接口内置固定筛选条件:step != 0、wave_id = 0、wave_scan_result = 2。用于展示策略未命中但需回退处理的订单候选。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选白名单字段(object)。仅支持下列字段,且禁止传入 warehouse_id / warehouseId:\n- id(等值)\n- delivery_no / deliveryNo(模糊)\n- tracking_no / trackingNo(模糊)\n- items_count_min / items_count_max(范围)\n- items_total_min / items_total_max(范围)\n- sys_logistics_name(模糊)\n- store_name(模糊)\n- owner_name(等值)\n- province(模糊)\n- sys_platform_name(模糊)\n说明:若传入未列出的字段或禁止字段(如 warehouse_id)接口会返回 400。"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "回退候选订单简要列表。数组内对象字段说明见 children。",
"children": [
{
"name": "id",
"type": "number",
"description": "订单 ID"
},
{
"name": "delivery_no",
"type": "string",
"description": "配送单号"
},
{
"name": "tracking_no",
"type": "string",
"description": "运单号"
},
{
"name": "items_count",
"type": "number",
"description": "SKU 种类数"
},
{
"name": "items_total",
"type": "number",
"description": "总件数"
},
{
"name": "sys_logistics_name",
"type": "string",
"description": "系统快递名称"
},
{
"name": "store_name",
"type": "string",
"description": "货主名称"
},
{
"name": "province",
"type": "string",
"description": "省/直辖市"
},
{
"name": "sys_platform_name",
"type": "string",
"description": "平台名称"
},
{
"name": "item_snapshot",
"type": "string",
"description": "商品快照,格式示例:苹果*2|香蕉*3"
}
]
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文或 where 中包含非法/禁止字段(如 warehouse_id)或存在别名冲突"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "order.wave.singleOrderFetchList",
"description": "按机器结构分组的散单候选列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。与 order.wave.groupOrderFetchList 不同:groupOrderFetchList 返回满足同组订单数量 >= same_order_quantity(或仓库配置 min_group_order_fetch_quantity)的团购命中分组;singleOrderFetchList 则排除这些团购命中分组,仅返回同组订单数量小于该阈值的散单候选分组(即 < same_order_quantity)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "distinguish_express",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否区分快递(影响分组粒度)"
},
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID(仅作为筛选条件)"
},
{
"name": "same_order_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "最小同组订单数量阈值(用于判定团购命中);本接口返回同组订单数量小于该阈值的分组。若显式传入有效数值则按传入值使用;未传入时使用仓库配置 min_group_order_fetch_quantity(默认 13)。"
},
{
"name": "shop_name",
"type": "string",
"required": false,
"source": "body",
"description": "店铺名称(模糊匹配)"
},
{
"name": "include_sku",
"type": "string",
"required": false,
"source": "body",
"description": "仅保留包含该 SKU 的分组(页内过滤)"
},
{
"name": "return_order_ids",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否在结果中返回组内订单ID列表"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "散单候选分组列表,items 示例见实现:包含 item_detail_machine/item_snapshot/group_count 等字段;返回的 group_count 均小于 same_order_quantity(或仓库配置的 min_group_order_fetch_quantity)。"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
}
],
"errors": [
{
"code": "400",
"description": "缺少仓库上下文或参数格式错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.wave.wavePickTaskList",
"description": "按当前仓库分页查询拣货任务列表。支持顶层分页参数 `page_no`/`page_size`(兼容 `pagination` 对象与 `current/size`),支持 `status` 单值或数组;兼容历史 `where` 结构,顶层参数优先。默认按 create_time desc 排序。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "仓库ID(必填)"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize,兼容 current / size(兼容旧客户端)"
},
{
"name": "page_no",
"type": "number",
"required": false,
"source": "body",
"description": "页码(优先于 pagination.page/current)"
},
{
"name": "page_size",
"type": "number",
"required": false,
"source": "body",
"description": "每页大小(优先于 pagination.pageSize/size)"
},
{
"name": "status",
"type": "array",
"required": false,
"source": "body",
"description": "拣货任务状态过滤;建议传数组,也兼容单值或逗号分隔字符串,兼容 where.status;顶层参数优先"
},
{
"name": "review_status",
"type": "number",
"required": false,
"source": "body",
"description": "复核状态过滤"
},
{
"name": "pick_mode",
"type": "number",
"required": false,
"source": "body",
"description": "拣货模式(如批量/逐单等)"
},
{
"name": "source",
"type": "string",
"required": false,
"source": "body",
"description": "任务来源标识(业务端语义)"
},
{
"name": "pick_user_id",
"type": "number",
"required": false,
"source": "body",
"description": "拣货执行人ID(兼容旧字段)"
},
{
"name": "review_user_id",
"type": "number",
"required": false,
"source": "body",
"description": "复核人ID"
},
{
"name": "task_no",
"type": "string",
"required": false,
"source": "body",
"description": "任务编号(支持模糊匹配)"
},
{
"name": "cart_id",
"type": "number",
"required": false,
"source": "body",
"description": "拣货车/作业车ID"
},
{
"name": "keyword",
"type": "string",
"required": false,
"source": "body",
"description": "关键字搜索:支持 task_no / batch_no / current_cart_code_snapshot 等字段的模糊匹配"
},
{
"name": "start_time_start",
"type": "string",
"required": false,
"source": "body",
"description": "开始时间(ISO 字符串),与 start_time_end 一起用于时间范围过滤"
},
{
"name": "start_time_end",
"type": "string",
"required": false,
"source": "body",
"description": "结束时间(ISO 字符串),与 start_time_start 一起用于时间范围过滤"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "兼容历史 where 结构(可包含 status 等字段);当存在顶层同名参数时,顶层参数优先"
},
{
"name": "strategy_id",
"type": "number",
"required": false,
"source": "body",
"description": "策略ID(当前主表未存,该接口会忽略此过滤,建议勿使用)"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "拣货任务列表(数组),每项字段如下",
"children": [
{
"name": "task_id",
"type": "number",
"description": "任务ID"
},
{
"name": "task_no",
"type": "string",
"description": "任务编号"
},
{
"name": "status",
"type": "number",
"description": "任务状态"
},
{
"name": "source",
"type": "string",
"description": "来源"
},
{
"name": "pick_mode",
"type": "number",
"description": "拣货模式"
},
{
"name": "wave_count",
"type": "number",
"description": "关联波次数"
},
{
"name": "order_count",
"type": "number",
"description": "订单数量"
},
{
"name": "box_count",
"type": "number",
"description": "箱数"
},
{
"name": "operator_id",
"type": "number",
"description": "操作人ID(兼容旧字段 pick_user_id)"
},
{
"name": "operator_name",
"type": "string",
"description": "操作人名称(兼容旧字段 pick_user_name)"
},
{
"name": "pick_user_id",
"type": "number",
"description": "拣货人ID(兼容字段,旧客户端可能使用)"
},
{
"name": "pick_user_name",
"type": "string",
"description": "拣货人名称(兼容字段,旧客户端可能使用)"
},
{
"name": "start_at",
"type": "string",
"description": "开始时间(ISO 字符串,兼容 start_time)"
},
{
"name": "finish_at",
"type": "string",
"description": "完成时间(ISO 字符串,兼容 finish_time)"
},
{
"name": "start_time",
"type": "string",
"description": "开始时间(ISO 字符串,兼容字段)"
},
{
"name": "finish_time",
"type": "string",
"description": "完成时间(ISO 字符串,兼容字段)"
},
{
"name": "created_at",
"type": "string",
"description": "创建时间(ISO 字符串,兼容 create_time)"
},
{
"name": "create_time",
"type": "string",
"description": "创建时间(ISO 字符串,兼容字段)"
}
]
},
{
"name": "total",
"type": "number",
"description": "总记录数"
},
{
"name": "page",
"type": "number",
"description": "当前页码"
},
{
"name": "page_size",
"type": "number",
"description": "每页大小"
}
],
"errors": [
{
"code": "400",
"description": "缺少仓库上下文或参数格式错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.wave.wavePickTaskCancel",
"description": "取消拣货任务(批量),同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。入参仅支持 task_ids(数组,必填),不再支持单个 task_id。操作人与仓库从请求上下文获取(例如当前登录用户上下文 ctx.user),若上下文缺失接口将返回错误。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_ids",
"type": "array",
"required": true,
"source": "body",
"description": "任务ID数组,例如 [123,124];仅支持批量处理,不再支持单个 task_id。"
}
],
"response": [
{
"name": "cancelled_count",
"type": "number",
"description": "成功取消的任务数量"
},
{
"name": "task_ids",
"type": "array",
"description": "处理的任务ID数组(若后端返回)"
},
{
"name": "task_nos",
"type": "array",
"description": "处理的任务编号数组(若后端返回)"
},
{
"name": "task_id",
"type": "number",
"description": "任务ID(历史兼容,若后端仍返回)"
},
{
"name": "task_no",
"type": "string",
"description": "任务编号(历史兼容,若后端仍返回)"
}
],
"errors": [
{
"code": "400",
"description": "任务状态不允许取消或入参缺失"
},
{
"code": "404",
"description": "任务不存在"
},
{
"code": "500",
"description": "内部错误或事务回滚失败"
}
]
},
{
"method": "order.wave.wavePickTaskCancelSelf",
"description": "取消单个拣货任务(仅允许取消当前操作人本人创建的任务;仅支持单个 task_id,明确不支持 task_ids)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id",
"type": "number",
"required": true,
"source": "body",
"description": "要取消的单个任务 ID(仅支持单个,不支持 task_ids)"
}
],
"response": [
{
"name": "cancelled_count",
"type": "number",
"description": "成功取消的任务数量(0 或 1)"
},
{
"name": "task_id",
"type": "number",
"description": "被处理的任务ID"
},
{
"name": "task_no",
"type": "string",
"description": "被处理的任务编号(若后端返回)"
}
],
"errors": [
{
"code": "400",
"description": "参数不合法(task_id 缺失或同时传入 task_ids)"
},
{
"code": "400",
"description": "仅允许取消本人创建任务"
},
{
"code": "500",
"description": "取消失败"
}
]
},
{
"method": "order.wave.batchCancel",
"description": "提交批量解除波次异步任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理波次并执行解除操作;可通过 order.wave.batchCancelTaskProgress 查询进度与结果。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "wave_ids / waveIds / ids",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "波次ID列表;支持数组、逗号分隔字符串或单个ID"
},
{
"name": "task_id / taskId",
"type": "string",
"required": false,
"source": "body",
"description": "可选外部任务ID,用于幂等提交"
}
],
"response": [
{
"name": "status",
"type": "string",
"required": true,
"description": "提交状态,固定 success"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(用于查询任务进度)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "当前仓库ID"
},
{
"name": "accepted_at",
"type": "string",
"required": true,
"description": "任务受理时间(ISO8601)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理提示信息"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "400",
"description": "wave_ids 参数不能为空或格式错误"
},
{
"code": "500",
"description": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.batchCancelTaskProgress",
"description": "查询批量解除波次任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。响应包含 state、progress_percent、processed_wave_count、total_wave_count;当 state 为 success/failed 时返回额外字段说明。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID(后端生成或提交时传入)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID"
},
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)"
},
{
"name": "progress_percent",
"type": "number",
"required": false,
"description": "进度百分比(0-100)"
},
{
"name": "processed_wave_count",
"type": "number",
"required": false,
"description": "已处理的波次数量"
},
{
"name": "total_wave_count",
"type": "number",
"required": false,
"description": "总波次数量"
},
{
"name": "duration_ms",
"type": "number",
"required": false,
"description": "任务耗时(毫秒)"
},
{
"name": "error_message",
"type": "string",
"required": false,
"description": "失败时的错误信息(仅在 state=failed 时返回)"
},
{
"name": "error_code",
"type": "string",
"required": false,
"description": "失败时的错误码(仅在 state=failed 时返回)"
},
{
"name": "result",
"type": "object",
"required": false,
"description": "成功时返回的汇总结果(仅在 state=success 时返回),例如 { \"processed_wave_count\": number, \"canceled_wave_count\": number }"
}
],
"errors": [
{
"code": "400",
"description": "task_id 参数不能为空"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "order.wave.batchAllocateExpress",
"description": "提交批次分配快递号任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到快递号分配流水线。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "wave_ids / waveIds / ids",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "波次ID列表;支持数组、逗号分隔字符串或单个ID"
},
{
"name": "task_id / taskId",
"type": "string",
"required": false,
"source": "body",
"description": "可选外部任务ID,用于幂等提交"
}
],
"response": [
{
"name": "status",
"type": "string",
"required": true,
"description": "提交状态,固定 success"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(用于查询任务进度)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "当前仓库ID"
},
{
"name": "accepted_at",
"type": "string",
"required": true,
"description": "任务受理时间(ISO8601)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理提示信息"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "400",
"description": "wave_ids 参数不能为空或格式错误"
},
{
"code": "500",
"description": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.batchAllocateExpressTaskProgress",
"description": "查询批次分配快递号任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID(后端生成或提交时传入)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID"
},
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "任务关联仓库ID"
},
{
"name": "total_wave_count",
"type": "number",
"required": false,
"description": "波次数量"
},
{
"name": "total_order_count",
"type": "number",
"required": false,
"description": "参与分配的订单数量"
},
{
"name": "processed_order_count",
"type": "number",
"required": false,
"description": "已处理订单数量"
},
{
"name": "success_order_count",
"type": "number",
"required": false,
"description": "成功提交分配的订单数量"
},
{
"name": "failed_order_count",
"type": "number",
"required": false,
"description": "提交分配失败的订单数量"
},
{
"name": "progress_percent",
"type": "number",
"required": false,
"description": "进度百分比(0-100)"
},
{
"name": "duration_ms",
"type": "number",
"required": false,
"description": "任务耗时(毫秒)"
},
{
"name": "error_message",
"type": "string",
"required": false,
"description": "失败时的错误信息"
},
{
"name": "error_code",
"type": "string",
"required": false,
"description": "失败时的错误码"
}
],
"errors": [
{
"code": "400",
"description": "task_id 参数不能为空"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "order.wave.batchRemoveExceptionOrders",
"description": "提交批次移除异常订单任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取异常订单并移出波次。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "wave_ids / waveIds / ids",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "波次ID列表;支持数组、逗号分隔字符串或单个ID"
},
{
"name": "task_id / taskId",
"type": "string",
"required": false,
"source": "body",
"description": "可选外部任务ID,用于幂等提交"
}
],
"response": [
{
"name": "status",
"type": "string",
"required": true,
"description": "提交状态,固定 success"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(用于查询任务进度)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "当前仓库ID"
},
{
"name": "accepted_at",
"type": "string",
"required": true,
"description": "任务受理时间(ISO8601)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理提示信息"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "400",
"description": "wave_ids 参数不能为空或格式错误"
},
{
"code": "500",
"description": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.batchRemoveExceptionOrdersTaskProgress",
"description": "查询批次移除异常订单任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID(后端生成或提交时传入)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID"
},
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "任务关联仓库ID"
},
{
"name": "total_wave_count",
"type": "number",
"required": false,
"description": "波次数量"
},
{
"name": "total_order_count",
"type": "number",
"required": false,
"description": "参与处理的订单数量"
},
{
"name": "processed_order_count",
"type": "number",
"required": false,
"description": "已处理订单数量"
},
{
"name": "removed_order_count",
"type": "number",
"required": false,
"description": "已成功移出波次的订单数量"
},
{
"name": "failed_order_count",
"type": "number",
"required": false,
"description": "处理失败的订单数量"
},
{
"name": "progress_percent",
"type": "number",
"required": false,
"description": "进度百分比(0-100)"
},
{
"name": "duration_ms",
"type": "number",
"required": false,
"description": "任务耗时(毫秒)"
},
{
"name": "error_message",
"type": "string",
"required": false,
"description": "失败时的错误信息"
},
{
"name": "error_code",
"type": "string",
"required": false,
"description": "失败时的错误码"
}
],
"errors": [
{
"code": "400",
"description": "task_id 参数不能为空"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "order.wave.batchAllocateStorage",
"description": "提交批次分配储位任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到储位分配流水线。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "wave_ids / waveIds / ids",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "波次ID列表;支持数组、逗号分隔字符串或单个ID"
},
{
"name": "task_id / taskId",
"type": "string",
"required": false,
"source": "body",
"description": "可选外部任务ID,用于幂等提交"
}
],
"response": [
{
"name": "status",
"type": "string",
"required": true,
"description": "提交状态,固定 success"
},
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(用于查询任务进度)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "当前仓库ID"
},
{
"name": "accepted_at",
"type": "string",
"required": true,
"description": "任务受理时间(ISO8601)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理提示信息"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "400",
"description": "wave_ids 参数不能为空或格式错误"
},
{
"code": "500",
"description": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.batchAllocateStorageTaskProgress",
"description": "查询批次分配储位任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID(后端生成或提交时传入)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID"
},
{
"name": "state",
"type": "string",
"required": true,
"description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "任务关联仓库ID"
},
{
"name": "total_wave_count",
"type": "number",
"required": false,
"description": "波次数量"
},
{
"name": "total_order_count",
"type": "number",
"required": false,
"description": "参与分配的订单数量"
},
{
"name": "processed_order_count",
"type": "number",
"required": false,
"description": "已处理订单数量"
},
{
"name": "success_order_count",
"type": "number",
"required": false,
"description": "成功提交分配的订单数量"
},
{
"name": "failed_order_count",
"type": "number",
"required": false,
"description": "提交分配失败的订单数量"
},
{
"name": "progress_percent",
"type": "number",
"required": false,
"description": "进度百分比(0-100)"
},
{
"name": "duration_ms",
"type": "number",
"required": false,
"description": "任务耗时(毫秒)"
},
{
"name": "error_message",
"type": "string",
"required": false,
"description": "失败时的错误信息"
},
{
"name": "error_code",
"type": "string",
"required": false,
"description": "失败时的错误码"
}
],
"errors": [
{
"code": "400",
"description": "task_id 参数不能为空"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "order.wave.groupFetch",
"description": "抓取团购接口(异步任务提交)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "structure_list",
"type": "array",
"required": true,
"source": "body",
"description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识),可选 quantity(未传入时使用仓库默认或全局默认)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "生效的仓库 ID"
},
{
"name": "structure_count",
"type": "number",
"required": true,
"description": "本次入参的结构数量(structure_list 长度)"
},
{
"name": "default_quantity",
"type": "number",
"required": true,
"description": "仓库默认抓取数量或全局默认值"
},
{
"name": "auto_fetch_disabled_marker",
"type": "string",
"required": true,
"description": "手动抓取标记;值为 'wave_manual_fetch' 表示手动抓取"
},
{
"name": "fetch_mode",
"type": "string",
"required": false,
"description": "抓取模式,值为 'group'(团购)或 'single'(散单)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明"
}
],
"errors": [
{
"code": 400,
"message": "structure_list 必须是非空数组或结构项参数不合法"
},
{
"code": 500,
"message": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.singleFetch",
"description": "抓取散单接口(异步任务提交)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "structure_list",
"type": "array",
"required": true,
"source": "body",
"description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识)并包含必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数);可选 quantity(未传入时使用仓库默认或全局默认)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "生效的仓库 ID"
},
{
"name": "structure_count",
"type": "number",
"required": true,
"description": "本次入参的结构数量(structure_list 长度)"
},
{
"name": "default_quantity",
"type": "number",
"required": true,
"description": "仓库默认抓取数量或全局默认值"
},
{
"name": "auto_fetch_disabled_marker",
"type": "string",
"required": true,
"description": "手动抓取标记;值为 'wave_manual_fetch' 表示手动抓取"
},
{
"name": "fetch_mode",
"type": "string",
"required": false,
"description": "抓取模式,值为 'group'(团购)或 'single'(散单)"
},
{
"name": "max_fetch_quantity",
"type": "number",
"required": false,
"description": "提交时生效的最大抓取上限(订单数,正整数)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明"
}
],
"errors": [
{
"code": 400,
"message": "structure_list 必须是非空数组或结构项参数不合法;max_fetch_quantity 必填且为正整数"
},
{
"code": 500,
"message": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.fetch",
"description": "兼容别名(等同 groupFetch)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "structure_list",
"type": "array",
"required": true,
"source": "body",
"description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识),可选 quantity(未传入时使用仓库默认或全局默认)"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "生效的仓库 ID"
},
{
"name": "structure_count",
"type": "number",
"required": true,
"description": "本次入参的结构数量(structure_list 长度)"
},
{
"name": "default_quantity",
"type": "number",
"required": true,
"description": "仓库默认抓取数量或全局默认值"
},
{
"name": "auto_fetch_disabled_marker",
"type": "string",
"required": true,
"description": "手动抓取标记;值为 'wave_manual_fetch' 表示手动抓取"
},
{
"name": "fetch_mode",
"type": "string",
"required": false,
"description": "抓取模式,值为 'group'(团购)或 'single'(散单)"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明"
}
],
"errors": [
{
"code": 400,
"message": "structure_list 必须是非空数组或结构项参数不合法"
},
{
"code": 500,
"message": "任务提交失败或内部错误"
}
]
},
{
"method": "order.wave.fetchTaskProgress",
"description": "查询波次抓取任务进度:按 task_id 查询任务状态与进度;兼容 taskId 参数名。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID(后端生成的唯一标识),兼容旧参数名 taskId,可从 order.wave.fetch 的返回值中获取"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "任务 ID"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"description": "生效的仓库 ID(若任务关联仓库时返回)"
},
{
"name": "structure_count",
"type": "number",
"required": false,
"description": "本次任务的结构数量(structure_list 长度)"
},
{
"name": "finished_structure_count",
"type": "number",
"required": false,
"description": "已完成抓取的结构数量"
},
{
"name": "progress_percent",
"type": "number",
"required": false,
"description": "进度百分比(0-100,可能为小数)"
},
{
"name": "total_fetched_quantity",
"type": "number",
"required": false,
"description": "已抓取的总件数"
},
{
"name": "duration_ms",
"type": "number",
"required": false,
"description": "任务已运行时长,毫秒级"
},
{
"name": "error",
"type": "string",
"required": false,
"description": "错误信息,仅当 status=failed 时返回"
},
{
"name": "fetch_mode",
"type": "string",
"required": false,
"description": "抓取模式,值为 'group'(团购)或 'single'(散单);single 模式时可能返回下列额外字段"
},
{
"name": "max_fetch_quantity",
"type": "number",
"required": false,
"description": "当 fetch_mode=single 时返回的最大抓取上限(订单数,正整数)"
},
{
"name": "limit_reached",
"type": "boolean",
"required": false,
"description": "当 fetch_mode=single 时指示是否已达到 max_fetch_quantity 限制"
},
{
"name": "stop_reason",
"type": "string",
"required": false,
"description": "任务停止原因(如达到上限、人工停止或其他失败原因)"
},
{
"name": "update_time",
"type": "string",
"required": false,
"description": "最近一次状态更新时间,ISO8601 字符串"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "额外提示信息"
}
],
"errors": [
{
"code": 400,
"message": "task_id 为空或格式不合法"
},
{
"code": 500,
"message": "内部错误"
}
]
},
{
"method": "order.wave.batchAutoGrouping",
"description": "批量将波次状态修改为 0(自动加团中),仅作用当前登录仓库命中的波次。限制条件:\n- 跳过已打印及之后状态的波次(wave_status >= 2);\n- 跳过 total_orders >= 仓库配置 max_wave_quantity 的波次。被跳过的波次不会被修改为自动加团中。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "波次ID 列表;支持数组、逗号分隔字符串或单个ID"
}
],
"response": [
{
"name": "ids",
"type": "array",
"description": "归一化后的请求ID"
},
{
"name": "affected_wave_ids",
"type": "array",
"description": "实际命中的波次ID"
},
{
"name": "updated_wave_count",
"type": "number",
"description": "实际更新数量"
},
{
"name": "skipped_wave_ids",
"type": "array",
"description": "被跳过的波次ID数组(不修改状态)"
},
{
"name": "skipped_wave_count",
"type": "number",
"description": "被跳过的波次数量"
},
{
"name": "skipped_details",
"type": "array",
"description": "被跳过的波次明细數組,元素包含 wave_id 与 reason,reason 枚举 printed_or_after_printed / reach_max_wave_quantity",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次 ID"
},
{
"name": "reason",
"type": "string",
"description": "跳过原因,枚举: printed_or_after_printed / reach_max_wave_quantity"
}
]
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "400",
"description": "ids 参数不能为空或格式错误"
},
{
"code": "500",
"description": "批量修改波次状态失败或内部错误"
}
]
},
{
"method": "order.wave.batchFinishAutoGrouping",
"description": "批量结束自动加团,将当前仓库命中且 wave_status=0 的波次改为 1(已就绪)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "波次ID 列表;支持数组、逗号分隔字符串或单个ID"
}
],
"response": [
{
"name": "ids",
"type": "array",
"description": "归一化后的请求ID"
},
{
"name": "affected_wave_ids",
"type": "array",
"description": "实际命中的波次ID"
},
{
"name": "updated_wave_ids",
"type": "array",
"description": "实际更新为已就绪的波次ID"
},
{
"name": "updated_wave_count",
"type": "number",
"description": "实际更新数量"
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "400",
"description": "ids 参数不能为空或格式错误"
},
{
"code": "500",
"description": "批量结束自动加团失败或内部错误"
}
]
},
{
"method": "order.wave.batchRemoveOrders",
"description": "按订单ID批量移出波次;仅处理当前仓库的待处理订单表中非待审核订单(step in [1,2,3])。操作会清空订单的 wave_id/wave_no,并在同一事务内回写 wms_wave_batch 表:重算 total_orders,若波次被清空则将 wave_status 置为 -1。仓库上下文来自当前登录用户(ctx.user.store_id)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / order_ids / orderIds / order_id / orderId / id",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单 ID 列表;支持数组、逗号分隔字符串或单个 ID,以上别名均可用(ids、order_ids、orderIds、order_id、orderId、id)"
}
],
"response": [
{
"name": "ids",
"type": "array",
"required": true,
"description": "归一化后的请求 ID 列表"
},
{
"name": "removed_order_ids",
"type": "array",
"required": true,
"description": "实际被移出波次的订单 ID 列表"
},
{
"name": "removed_order_count",
"type": "number",
"required": true,
"description": "被移出波次的订单数量"
},
{
"name": "affected_wave_ids",
"type": "array",
"required": true,
"description": "本次操作涉及的波次 ID 列表"
},
{
"name": "updated_wave_ids",
"type": "array",
"required": true,
"description": "实际更新了 total_orders 的波次 ID 列表"
},
{
"name": "emptied_wave_ids",
"type": "array",
"required": true,
"description": "被清空且已置为 wave_status=-1 的波次 ID 列表"
}
],
"errors": [
{
"code": "400",
"message": "缺少仓库上下文(用户登录信息无 store_id)或 ids 参数为空/格式错误"
},
{
"code": "500",
"message": "内部错误"
}
]
}
]
},
{
"groupName": "订单待出库模块",
"module": "order.outboundOrder",
"list": [
{
"method": "order.outboundOrder.list",
"description": "待出库订单列表,默认筛选 outbound_status in [none,padding] 且 step in [1,2]。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.outboundOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "order.outboundOrder.manualOutboundOrder",
"description": "待出库模块的手动出库入口,行为与 order.manualOutboundOrder 一致。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouseId",
"type": "number",
"required": false,
"source": "body",
"description": "单仓库ID,兼容 warehouse_id"
},
{
"name": "warehouseIds",
"type": "array",
"required": false,
"source": "body",
"description": "仓库ID 数组"
},
{
"name": "queryTimeoutMs",
"type": "number",
"required": false,
"source": "body",
"description": "查询超时时间(毫秒)"
},
{
"name": "executionTimeoutMs",
"type": "number",
"required": false,
"source": "body",
"description": "执行超时时间(毫秒)"
}
],
"response": [
{
"name": "warehouseIds",
"type": "array",
"required": true,
"description": "参与迁移的仓库ID列表"
},
{
"name": "batchSize",
"type": "number",
"required": true,
"description": "单批处理上限,当前固定为 1000"
},
{
"name": "outboundStatuses",
"type": "array",
"required": true,
"description": "本次迁移匹配的出库状态"
},
{
"name": "totalSelected",
"type": "number",
"required": true,
"description": "命中的源订单数量"
},
{
"name": "totalCreated",
"type": "number",
"required": true,
"description": "实际创建到配送表的订单数量"
},
{
"name": "totalSkipped",
"type": "number",
"required": true,
"description": "本次跳过的源订单数量"
},
{
"name": "totalTimeout",
"type": "number",
"required": true,
"description": "被标记为出库超时的订单数量"
},
{
"name": "results",
"type": "array",
"required": true,
"description": "按仓库维度返回的批次结果数组,元素包含 selectedCount、createdCount、skippedCount、timeoutCount、retryableFailure 等字段"
}
],
"errors": [
{
"code": "400",
"description": "仓库ID为空或请求参数格式错误"
},
{
"code": "500",
"description": "迁移失败或数据库错误"
}
]
}
]
},
{
"groupName": "订单异常模块",
"module": "order.expectionOrder",
"list": [
{
"method": "order.expectionOrder.list",
"description": "待处理异常订单列表,默认仅查询 step=3 的订单。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.expectionOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "order.expectionOrder.resolveException",
"description": "将待处理异常订单转回正常待处理状态(step 3 → 2)。只操作当前仓库的当前订单表,且仅对 step=3 的订单生效。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "number[]",
"required": true,
"source": "body",
"description": "订单ID 正整数数组,不能为空"
}
],
"response": [
{
"name": "updated_count",
"type": "number",
"required": true,
"description": "实际更新行数"
},
{
"name": "ids",
"type": "number[]",
"required": true,
"description": "本次操作的订单ID 列表"
}
],
"errors": [
{
"code": "400",
"message": "ids 为空或格式非法"
},
{
"code": "500",
"message": "更新失败"
}
]
}
]
},
{
"groupName": "订单委托外仓模块",
"module": "order.entrustOrder",
"list": [
{
"method": "order.entrustOrder.list",
"description": "委托外仓订单列表,使用 outsourced 模型。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.entrustOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
}
]
},
{
"groupName": "订单配送模块",
"module": "order.deliveryOrder",
"list": [
{
"method": "order.deliveryOrder.list",
"description": "配送订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m4。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.deliveryOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
}
]
},
{
"groupName": "订单配送异常模块",
"module": "order.deliveryExpectionOrder",
"list": [
{
"method": "order.deliveryExpectionOrder.list",
"description": "配送异常订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m5。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.deliveryExpectionOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
}
]
},
{
"groupName": "订单归档模块",
"module": "order.archiveOrder",
"list": [
{
"method": "order.archiveOrder.list",
"description": "归档订单列表,使用 history 模型。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField / sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据)"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息"
},
{
"name": "recheck_status",
"type": "string",
"required": false,
"description": "复核状态:none=未复核,fin=已复核"
}
],
"errors": [
{
"code": "400",
"message": "参数格式错误或缺少仓库上下文"
},
{
"code": "500",
"message": "查询失败"
}
]
},
{
"method": "order.archiveOrder.detail",
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids / id / order_id / orderId",
"type": "array|string|number",
"required": true,
"source": "body",
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
},
{
"name": "tableType / tablePosition / type / moduleName",
"type": "string",
"required": false,
"source": "body",
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
}
],
"response": [
{
"name": "order",
"type": "object",
"description": "订单头对象(raw 行数据)"
},
{
"name": "detail",
"type": "object",
"description": "等同于 order"
},
{
"name": "orderItems / items",
"type": "array",
"description": "商品明细数组"
},
{
"name": "expresses",
"type": "array",
"description": "运单信息数组"
},
{
"name": "waybill_codes",
"type": "array",
"description": "去重后的运单号字符串数组"
}
],
"errors": [
{
"code": "400",
"description": "订单ID 为空或格式错误"
},
{
"code": "404",
"description": "订单不存在或不属于当前仓库"
},
{
"code": "500",
"description": "内部错误"
}
]
}
]
},
{
"groupName": "订单打印模块",
"module": "order.print",
"list": [
{
"method": "order.print.getWavePrintData",
"description": "按波次 IDs 获取订单打印数据,自动过滤快递未完全分配的波次,返回通过过滤的波次订单明细,按波次号分组",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "仓库ID"
},
{
"name": "wave_ids",
"type": "array",
"required": true,
"source": "body",
"description": "波次ID列表(支持数字或字符串,内部自动去重与归一化)"
}
],
"response": [
{
"name": "summary",
"type": "object",
"description": "汇总信息",
"children": [
{
"name": "total_waves",
"type": "number",
"description": "通过过滤的波次总数"
},
{
"name": "total_orders",
"type": "number",
"description": "通过过滤的波次下订单总数"
}
]
},
{
"name": "wave_list",
"type": "array",
"description": "波次列表(按 wave_no 排序)",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次ID"
},
{
"name": "wave_no",
"type": "string",
"description": "波次号"
},
{
"name": "order_count",
"type": "number",
"description": "该波次订单数"
},
{
"name": "orders",
"type": "array",
"description": "订单明细列表(含 order_id、order_no、收件信息等字段)",
"children": [
{
"name": "order_id",
"type": "number",
"description": "订单ID"
},
{
"name": "order_no",
"type": "string",
"description": "订单号(delivery_order_code 或 source_order_codes)"
},
{
"name": "receiver",
"type": "object",
"description": "收件信息",
"children": [
{
"name": "name",
"type": "string",
"description": "收件人姓名"
},
{
"name": "mobile",
"type": "string",
"description": "手机号"
},
{
"name": "tel",
"type": "string",
"description": "电话"
},
{
"name": "province",
"type": "string",
"description": "省"
},
{
"name": "city",
"type": "string",
"description": "市"
},
{
"name": "area",
"type": "string",
"description": "区/县"
},
{
"name": "town",
"type": "string",
"description": "镇/街道"
},
{
"name": "detail_address",
"type": "string",
"description": "详细地址"
}
]
},
{
"name": "channel",
"type": "object",
"description": "渠道信息",
"children": [
{
"name": "sys_platform_code",
"type": "string",
"description": "平台编码"
},
{
"name": "sys_platform_name",
"type": "string",
"description": "平台名称"
},
{
"name": "logistics_name",
"type": "string",
"description": "快递名称"
}
]
},
{
"name": "status",
"type": "object",
"description": "订单状态简要",
"children": [
{
"name": "order_status",
"type": "string",
"description": "订单状态"
},
{
"name": "outbound_status",
"type": "string",
"description": "出库状态"
},
{
"name": "print_status",
"type": "string",
"description": "打印状态"
}
]
},
{
"name": "metrics",
"type": "object",
"description": "数量度量",
"children": [
{
"name": "items_count",
"type": "number",
"description": "商品种类数"
},
{
"name": "items_total",
"type": "number",
"description": "商品总件数"
},
{
"name": "items_weight",
"type": "number",
"description": "重量"
}
]
},
{
"name": "times",
"type": "object",
"description": "时间字段",
"children": [
{
"name": "create_at",
"type": "string",
"description": "创建时间"
},
{
"name": "pay_time",
"type": "string",
"description": "支付时间"
}
]
}
]
}
]
},
{
"name": "ext",
"type": "object",
"description": "扩展字段",
"children": [
{
"name": "missing_wave_ids",
"type": "array",
"description": "传入但不存在的 wave_id 列表"
},
{
"name": "filtered_wave_ids",
"type": "array",
"description": "被过滤掉的波次(快递未完全分配),每项含 wave_id、wave_no、reason"
}
]
}
],
"errors": [
{
"code": "400",
"description": "warehouse_id 或 wave_ids 缺失或格式错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.print.getWavePlatformPrintData",
"description": "按波次 IDs 获取平台打印中间态数据,自动过滤快递未完全分配的波次,返回 waveGroups(波次 -> 平台 -> 订单)结构",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "仓库ID(必须与当前用户上下文 store_id 一致)"
},
{
"name": "wave_ids",
"type": "array",
"required": true,
"source": "body",
"description": "波次ID列表(支持数字或字符串,内部自动去重与归一化)"
}
],
"response": [
{
"name": "summary",
"type": "object",
"description": "汇总信息",
"children": [
{
"name": "total_waves",
"type": "number",
"description": "通过过滤的波次总数"
},
{
"name": "total_orders",
"type": "number",
"description": "所有平台下订单总数"
},
{
"name": "total_platforms",
"type": "number",
"description": "所有波次内平台分组总数(累加)"
}
]
},
{
"name": "wave_ids",
"type": "array",
"description": "通过过滤的波次ID数组"
},
{
"name": "waveGroups",
"type": "array",
"description": "主返回结构:按波次分组(波次 -> 平台 -> 订单)",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次ID"
},
{
"name": "wave_no",
"type": "string",
"description": "波次号"
},
{
"name": "order_count",
"type": "number",
"description": "该波次下订单总数"
},
{
"name": "platforms",
"type": "array",
"description": "按平台和系统快递分组后的订单列表",
"children": [
{
"name": "platform",
"type": "string",
"description": "平台编码"
},
{
"name": "platform_name",
"type": "string",
"description": "平台名称"
},
{
"name": "order_count",
"type": "number",
"description": "该平台+系统快递分组的订单数"
},
{
"name": "sys_logistics_code",
"type": "string",
"description": "系统快递编码"
},
{
"name": "sys_logistics_name",
"type": "string",
"description": "系统快递名称"
},
{
"name": "orders",
"type": "array",
"description": "该分组内的订单列表(逐单中间态,字段同平台层 orders 中元素)",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次ID"
},
{
"name": "wave_no",
"type": "string",
"description": "波次号"
},
{
"name": "order_id",
"type": "number",
"description": "订单ID"
},
{
"name": "order_no",
"type": "string",
"description": "订单号(delivery_order_code 或 source_order_codes)"
},
{
"name": "store_id",
"type": "number",
"description": "货主ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "仓库ID"
},
{
"name": "platform",
"type": "string",
"description": "平台编码"
},
{
"name": "platform_name",
"type": "string",
"description": "平台名称"
},
{
"name": "waybill_code",
"type": "string",
"description": "运单号"
},
{
"name": "print_data",
"type": "object",
"description": "打印中间态(详见 printer_data_builder.buildPlatformRequestSkeleton 输出)"
}
]
}
]
}
]
},
{
"name": "platform_groups",
"type": "array",
"description": "兼容字段:按平台分组结果(保留以兼容旧客户端)",
"children": [
{
"name": "platform",
"type": "string",
"description": "平台编码"
},
{
"name": "platform_name",
"type": "string",
"description": "平台名称"
},
{
"name": "order_count",
"type": "number",
"description": "该平台订单数"
},
{
"name": "orders",
"type": "array",
"description": "逐单中间态(字段同 order_list 元素)"
}
]
},
{
"name": "order_list",
"type": "array",
"description": "兼容字段:逐单平台打印中间态明细(保留以兼容旧客户端)",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次ID"
},
{
"name": "wave_no",
"type": "string",
"description": "波次号"
},
{
"name": "order_id",
"type": "number",
"description": "订单ID"
},
{
"name": "order_no",
"type": "string",
"description": "订单号(delivery_order_code 或 source_order_codes)"
},
{
"name": "store_id",
"type": "number",
"description": "货主ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "仓库ID"
},
{
"name": "platform",
"type": "string",
"description": "平台编码"
},
{
"name": "platform_name",
"type": "string",
"description": "平台名称"
},
{
"name": "waybill_code",
"type": "string",
"description": "运单号"
},
{
"name": "print_data",
"type": "object",
"description": "打印中间态(详见 printer_data_builder.buildPlatformRequestSkeleton 输出)"
}
]
},
{
"name": "ext",
"type": "object",
"description": "扩展字段",
"children": [
{
"name": "missing_wave_ids",
"type": "array",
"description": "传入但不存在的 wave_id 列表"
},
{
"name": "filtered_wave_ids",
"type": "array",
"description": "被过滤掉的波次,每项含 wave_id、reason"
}
]
}
],
"errors": [
{
"code": "400",
"description": "warehouse_id 或 wave_ids 缺失或格式错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "order.print.unlockWavePlatformPrintDataByGroup",
"description": "按分组解锁波次平台打印锁:按传入的 groups 条件匹配已锁定订单并将其 print_lock_status 置为 none,返回解锁统计与解锁订单列表。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "仓库ID(必须与当前用户上下文 store_id 一致)"
},
{
"name": "wave_ids",
"type": "array",
"required": true,
"source": "body",
"description": "波次ID列表(支持数字或字符串,内部自动去重与归一化)"
},
{
"name": "group_type",
"type": "string",
"required": false,
"source": "body",
"description": "分组类型,支持 platform、platform_express、order;默认 platform_express"
},
{
"name": "unlock_scope",
"type": "string",
"required": false,
"source": "body",
"description": "解锁范围,支持 group、wave;默认 group"
},
{
"name": "groups",
"type": "array",
"required": true,
"source": "body",
"description": "分组条件列表。元素为对象,可包含字段:wave_id(必填)、platform(平台编码)、sys_logistics_code(系统快递编码)、order_ids(订单ID数组)",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次ID(单个规则指定的波次)"
},
{
"name": "platform",
"type": "string",
"description": "平台编码(当 group_type 为 platform/platform_express 时可能必需)"
},
{
"name": "sys_logistics_code",
"type": "string",
"description": "系统快递编码(当 group_type 为 platform_express 时可能必需)"
},
{
"name": "order_ids",
"type": "array",
"description": "订单ID列表(当 group_type 为 order 时必需)"
}
]
}
],
"response": [
{
"name": "summary",
"type": "object",
"required": true,
"description": "解锁操作的汇总统计",
"children": [
{
"name": "total_waves",
"type": "number",
"description": "有效波次数(通过过滤的波次数)"
},
{
"name": "total_locked_orders",
"type": "number",
"description": "有效波次中原本被锁定的订单总数"
},
{
"name": "matched_group_orders",
"type": "number",
"description": "匹配到分组规则的被锁定订单数"
},
{
"name": "unlocked_count",
"type": "number",
"description": "实际已更新为 unlocked 的订单数量(update 影响数)"
}
]
},
{
"name": "wave_ids",
"type": "array",
"required": true,
"description": "通过过滤的波次ID数组"
},
{
"name": "unlocked_order_ids",
"type": "array",
"required": true,
"description": "被解锁的订单ID数组"
},
{
"name": "unlocked_orders",
"type": "array",
"required": true,
"description": "被解锁订单简要信息列表",
"children": [
{
"name": "order_id",
"type": "number",
"description": "订单ID"
},
{
"name": "wave_id",
"type": "number",
"description": "波次ID"
},
{
"name": "wave_no",
"type": "string",
"description": "波次号"
},
{
"name": "order_no",
"type": "string",
"description": "订单号(delivery_order_code 或 source_order_codes)"
}
]
},
{
"name": "ext",
"type": "object",
"required": false,
"description": "扩展字段",
"children": [
{
"name": "missing_wave_ids",
"type": "array",
"description": "传入但不存在的 wave_id 列表"
},
{
"name": "filtered_wave_ids",
"type": "array",
"description": "被过滤掉的波次(快递未完全分配),每项含 wave_id、wave_no、reason"
}
]
}
],
"errors": [
{
"code": "400",
"message": "wave_ids 必填,且必须为非空数组",
"description": "wave_ids 必填,且必须为非空数组"
},
{
"code": "400",
"message": "warehouse_id 必填且必须为正整数",
"description": "warehouse_id 必填且必须为正整数"
},
{
"code": "400",
"message": "warehouse_id 必须与当前用户上下文 store_id 保持一致",
"description": "warehouse_id 必须与当前用户上下文 store_id 保持一致"
},
{
"code": "400",
"message": "group_type 仅支持 platform、platform_express、order",
"description": "group_type 仅支持 platform、platform_express、order"
},
{
"code": "400",
"message": "unlock_scope 仅支持 group、wave",
"description": "unlock_scope 仅支持 group、wave"
},
{
"code": "400",
"message": "groups 必填,且必须为非空数组",
"description": "groups 必填,且必须为非空数组"
},
{
"code": "400",
"message": "groups 未匹配到有效的分组解锁条件",
"description": "groups 未匹配到有效的分组解锁条件"
},
{
"code": "500",
"message": "内部错误",
"description": "内部错误"
}
]
}
]
},
{
"groupName": "打印模块",
"module": "print",
"list": [
{
"method": "print.send",
"description": "发送打印任务到打印电脑,并记录打印单。说明:当 type=express 时,接口按 data.waveGroups(来源于 order.print.getWavePlatformPrintData 返回的 data.waveGroups)进行处理,按 waveGroups -> platforms 串行处理,每个平台+快递 组分别发送;返回沿用现有简要风格,不返回明细。接口在记录打印单的同时,也会写入订单操作日志(记录打印相关操作)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "computerId",
"type": "string",
"required": false,
"source": "body",
"description": "打印电脑 ID;历史/customize 分支可能使用。注意:type=express 场景下不适用(该字段不再作为 express 路径的必填或传输约束)。"
},
{
"name": "count",
"type": "number",
"required": false,
"source": "body",
"description": "打印份数;对 type=customize 有效。type=express 场景下不保留,相应字段会被忽略。"
},
{
"name": "data",
"type": "object",
"required": true,
"source": "body",
"description": "打印业务数据对象。对于 type=express:必须提供 data.waveGroups(来源于 order.print.getWavePlatformPrintData 的返回值 data.waveGroups),接口按 waveGroups->platforms 串行处理,每个 平台+快递 组分别发送;对于 type=customize,data 的具体字段由模板决定。"
},
{
"name": "printer",
"type": "string",
"required": false,
"source": "body",
"description": "打印机名称;type=customize 使用。type=express 下忽略(由快递平台/站点决定打印目标)。"
},
{
"name": "template",
"type": "object",
"required": false,
"source": "body",
"description": "打印模板对象;仅 type=customize 时必填且应包含 page_width、page_height、template_content。type=express 场景下忽略 template 字段。",
"children": [
{
"name": "page_width",
"type": "number",
"required": true,
"description": "页面宽度(mm)"
},
{
"name": "page_height",
"type": "number",
"required": true,
"description": "页面高度(mm)"
},
{
"name": "template_content",
"type": "array",
"required": false,
"description": "模板内容数组"
}
]
},
{
"name": "timestamp",
"type": "string",
"required": false,
"source": "body",
"description": "业务时间戳;历史字段。type=express 场景下不适用。"
},
{
"name": "type",
"type": "string",
"required": true,
"source": "body",
"description": "打印类型;支持 customize、express。对于 express 场景,必须遵守下列额外约束:提供 printStationId、requestCode,并在 data.waveGroups 中传入来自 order.print.getWavePlatformPrintData 的 waveGroups 数据。"
},
{
"name": "printStationId",
"type": "string",
"required": true,
"source": "body",
"description": "打印站点/工作站标识(必填,type=express 时必须提供),用于指示目标打印站或分发单元。"
},
{
"name": "requestCode",
"type": "string",
"required": true,
"source": "body",
"description": "请求去重/防重放 ID(必填,type=express 时必须提供)。接口约束:requestCode 在约定周期内不得变更(例如一次批次/会话期间),系统在同一次请求处理范围内保证对重复 requestCode 进行防重放处理;此保护仅保证同一次请求内的去重/防重放,不等同于跨请求的强幂等保证。"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": false,
"description": "全局调用结果标识,成功时为 success,失败时为 failure"
},
{
"name": "code",
"type": "number",
"required": false,
"description": "业务状态码;成功时为 200,失败时通常为 1001 或 504"
},
{
"name": "message",
"type": "string",
"required": false,
"description": "返回信息"
},
{
"name": "printId",
"type": "number",
"required": false,
"description": "打印记录 ID;任务入库成功后返回,失败时若已生成记录也会返回。接口在 express 场景下不返回明细结果,只给出调用结果摘要。"
}
],
"errors": [
{
"code": 1001,
"message": "不支持的打印类型"
},
{
"code": 504,
"message": "打印任务发送失败(如打印机不存在、打印机脱机、打印服务通讯失败)"
}
]
},
{
"method": "print.getPrintResult",
"description": "print.getPrintResult 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "printId",
"type": "string",
"required": true,
"source": "body",
"description": "printId 参数"
}
],
"response": [],
"errors": []
},
{
"method": "print.getPrintRecordItem",
"description": "print.getPrintRecordItem 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "print.getList",
"description": "查询当前仓库下的打印台列表,支持分页与 where 条件筛选(支持字段:id、name、computer_id、custom_barcode)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码,默认 1"
},
{
"name": "pageSize",
"type": "number",
"required": false,
"source": "body",
"description": "每页数量,默认 20"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选条件对象;支持字段:id(等值)、name、computer_id、custom_barcode;推荐使用 { operator, value, type } 标准结构"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "返回数据对象,包含 list 与 pagination",
"children": [
{
"name": "list",
"type": "array",
"required": true,
"description": "打印台列表",
"children": [
{
"name": "id",
"type": "number",
"description": "打印台 ID"
},
{
"name": "name",
"type": "string",
"description": "打印台名称"
},
{
"name": "computer_id",
"type": "number",
"description": "关联打印电脑 ID"
},
{
"name": "custom_barcode",
"type": "string",
"description": "自定义条码"
},
{
"name": "default_printer_name",
"type": "string",
"description": "默认打印机名称"
},
{
"name": "subject_config",
"type": "object",
"description": "打印台的 subject_config 配置"
},
{
"name": "is_online",
"type": "number",
"description": "打印电脑在线状态,1=在线,0=离线"
},
{
"name": "components",
"type": "array",
"description": "电脑组件在线信息,数组项包含 name/is_online",
"children": [
{
"name": "name",
"type": "string",
"description": "组件名称"
},
{
"name": "is_online",
"type": "number",
"description": "组件是否在线,1/0"
}
]
}
]
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息,包含 page、pageSize、total、totalPages、hasPrevious、hasNext"
}
]
}
],
"errors": [
{
"code": "400",
"description": "参数格式错误或 where 中包含非法字段"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "print.getItem",
"description": "查询单个打印台详情,返回打印台对象(raw 行记录,含 subject_config)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "打印台 ID,必填"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "打印台原始记录(PrintStation raw),字段示例",
"children": [
{
"name": "id",
"type": "number",
"description": "打印台 ID"
},
{
"name": "name",
"type": "string",
"description": "打印台名称"
},
{
"name": "computer_id",
"type": "number",
"description": "关联打印电脑 ID"
},
{
"name": "custom_barcode",
"type": "string",
"description": "自定义条码"
},
{
"name": "default_printer_name",
"type": "string",
"description": "默认打印机名称"
},
{
"name": "subject_config",
"type": "object",
"description": "打印台 subject_config 配置(见下文)"
},
{
"name": "create_at",
"type": "string",
"description": "创建时间"
},
{
"name": "update_at",
"type": "string",
"description": "更新时间"
},
{
"name": "deleted",
"type": "number",
"description": "软删除标识,1=已删除"
}
]
}
],
"errors": [
{
"code": "400",
"description": "参数错误:缺少 id 或 id 格式不正确"
},
{
"code": "404",
"description": "打印台不存在"
},
{
"code": "500",
"description": "内部错误"
}
]
},
{
"method": "print.add",
"description": "新增打印台:关联打印电脑并可保存 subject_config(会由模型 normalizeSubjectConfig 校验)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "computer_id",
"type": "number",
"required": true,
"source": "body",
"description": "关联的打印电脑 ID(必填)"
},
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "打印台名称(必填)"
},
{
"name": "custom_barcode",
"type": "string",
"required": false,
"source": "body",
"description": "自定义条码"
},
{
"name": "default_printer_name",
"type": "string",
"required": false,
"source": "body",
"description": "默认打印机名称"
},
{
"name": "subject_config",
"type": "object",
"required": false,
"source": "body",
"description": "打印台的主题/业务配置(可选,若存在将调用模型 normalizeSubjectConfig 进行校验)",
"children": [
{
"name": "express_bind_printer",
"type": "array",
"description": "快递与打印机绑定数组,数组项仅包含 { express_code, printer_name }",
"children": [
{
"name": "express_code",
"type": "string",
"required": true,
"description": "快递编码,必填"
},
{
"name": "printer_name",
"type": "string",
"required": true,
"description": "打印机名称,必填"
}
]
}
]
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "新建的打印台对象(raw)"
}
],
"errors": [
{
"code": "400",
"description": "参数错误:缺少必填字段(computer_id/name)或 subject_config 格式不合法"
},
{
"code": "500",
"description": "创建失败或内部错误"
}
]
},
{
"method": "print.hasName",
"description": "print.hasName 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "name 参数"
},
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "print.updateItem",
"description": "更新打印台信息:支持更新 name、computer_id、custom_barcode、default_printer_name 以及 subject_config(会走 normalizeSubjectConfig)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "打印台 ID(必填)"
},
{
"name": "computer_id",
"type": "number",
"required": false,
"source": "body",
"description": "要更新的打印电脑 ID"
},
{
"name": "custom_barcode",
"type": "string",
"required": false,
"source": "body",
"description": "自定义条码"
},
{
"name": "name",
"type": "string",
"required": false,
"source": "body",
"description": "打印台名称"
},
{
"name": "default_printer_name",
"type": "string",
"required": false,
"source": "body",
"description": "默认打印机名称"
},
{
"name": "subject_config",
"type": "object",
"required": false,
"source": "body",
"description": "subject_config(可选),传入将替换/规范化配置",
"children": [
{
"name": "express_bind_printer",
"type": "array",
"description": "快递-打印机绑定数组,数组项仅包含 { express_code, printer_name }",
"children": [
{
"name": "express_code",
"type": "string",
"required": true,
"description": "快递编码,必填"
},
{
"name": "printer_name",
"type": "string",
"required": true,
"description": "打印机名称,必填"
}
]
}
]
}
],
"response": [
{
"name": "data",
"type": "object",
"required": false,
"description": "更新结果,通常返回 null"
}
],
"errors": [
{
"code": "400",
"description": "参数错误(缺少 id 或 subject_config 格式不合法)"
},
{
"code": "404",
"description": "打印台不存在"
},
{
"code": "500",
"description": "更新失败或内部错误"
}
]
},
{
"method": "print.del",
"description": "批量删除(软删除)打印台:将指定 ids 的记录标记为 deleted=1。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "要删除的打印台 ID 数组,必须为非空数组(示例: [1,2,3])"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": false,
"description": "返回空数据结构,表示操作成功"
}
],
"errors": [
{
"code": "400",
"description": "参数错误:ids 必须为非空数组"
},
{
"code": "500",
"description": "删除失败或内部错误"
}
]
},
{
"method": "print.getComputer",
"description": "查询当前仓库下状态为 1 的打印电脑列表(raw 列表)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "data",
"type": "array",
"required": true,
"description": "打印电脑数组,每项为打印电脑的原始记录",
"children": [
{
"name": "id",
"type": "number",
"description": "打印电脑 ID"
},
{
"name": "name",
"type": "string",
"description": "打印电脑名称或标识"
},
{
"name": "status",
"type": "number",
"description": "状态,1=启用"
},
{
"name": "warehouse_id",
"type": "number",
"description": "所属仓库 ID"
}
]
}
],
"errors": [
{
"code": "400",
"description": "未识别到当前仓库上下文"
},
{
"code": "500",
"description": "查询失败或内部错误"
}
]
},
{
"method": "print.getComputerPrinter",
"description": "获取指定打印电脑的打印机列表(从 redis: printer:{id}:printerList 读取并返回 data 数组,通常为打印机名称数组或对象数组)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "打印电脑 ID,必填"
}
],
"response": [
{
"name": "data",
"type": "array",
"required": true,
"description": "打印机数组,通常为字符串名称数组或打印机对象数组(取决于 redis 存储格式)"
}
],
"errors": [
{
"code": "400",
"description": "参数错误:缺少 id"
},
{
"code": "500",
"description": "读取 Redis 或解析数据失败"
}
]
},
{
"method": "print.savePrinters",
"description": "保存 default_printer_name 与 subject_config.express_bind_printer。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "defaultPrinter",
"type": "string",
"required": true,
"source": "body",
"description": "默认打印机名称(必填),会写入打印台的 `default_printer_name` 字段"
},
{
"name": "express",
"type": "array",
"required": true,
"source": "body",
"description": "快递与打印机绑定数组(必填)。每项应包含首选字段 `express_code`(string)和 `printer_name`(string)。为兼容历史字段,也接受 `express_id`(可映射为 `express_code`)和 `name`(可映射为 `printer_name`)。接口实现会将结果序列化后写入打印台的 `subject_config.express_bind_printer`。",
"children": [
{
"name": "express_code",
"type": "string",
"required": false,
"description": "首选:快递编码(string),实现中优先使用该字段"
},
{
"name": "printer_name",
"type": "string",
"required": false,
"description": "首选:打印机名称(string),实现中优先使用该字段"
},
{
"name": "express_id",
"type": "number|string",
"required": false,
"description": "兼容字段:历史的 express_id,可映射为 express_code 使用"
},
{
"name": "name",
"type": "string",
"required": false,
"description": "兼容字段:历史的 name,可映射为 printer_name 使用"
}
]
},
{
"name": "print_station_id",
"type": "number",
"required": true,
"source": "body",
"description": "目标打印台 ID(必填)。接口会根据此 ID 更新对应打印台记录的 default_printer_name 与 subject_config.express_bind_printer"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": false,
"description": "成功不返回业务数据,语义为成功(实现中返回 { data: null, code: 0 })"
}
],
"errors": [
{
"code": "400",
"description": "参数错误:defaultPrinter/express/print_station_id 格式或缺失"
},
{
"code": "404",
"description": "打印台不存在:未找到对应 print_station_id 的打印台记录"
},
{
"code": "500",
"description": "保存失败或内部错误"
}
]
},
{
"method": "print.retryFailed",
"description": "失败项补打:重试指定打印记录的发送。被定时任务 print-retry-compensation 调用以批量触发失败项补打。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "print_ids",
"type": "array",
"required": true,
"source": "body",
"description": "要补打的打印记录 ID 数组",
"children": [
{
"name": "id",
"type": "number",
"description": "打印记录 ID"
}
]
},
{
"name": "force",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否强制补打(当前实现仍不放宽状态判定)"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"source": "body",
"description": "显式指定仓库 ID(调度任务推荐提供),若缺失将使用当前用户的 store_id"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "调用标识,成功为 success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功通常为 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回信息"
},
{
"name": "success_count",
"type": "number",
"required": false,
"description": "成功补打数量"
},
{
"name": "failed_count",
"type": "number",
"required": false,
"description": "补打失败数量"
},
{
"name": "skipped_count",
"type": "number",
"required": false,
"description": "被跳过的记录数量"
},
{
"name": "retried",
"type": "array",
"required": false,
"description": "补打尝试结果数组"
},
{
"name": "skipped",
"type": "array",
"required": false,
"description": "跳过项明细"
}
],
"errors": [
{
"code": 400,
"message": "warehouse_id 参数缺失,且当前上下文无可用仓库信息"
},
{
"code": 400,
"message": "print_ids 参数不能为空数组或不合法"
},
{
"code": 500,
"message": "内部错误"
}
]
},
{
"method": "print.notifyLock",
"description": "仅执行订单锁定流程,不发送打印任务;记录打印任务日志并写入订单操作日志。兼容别名:print.notify_lock(等价转调)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "order_ids",
"type": "array",
"required": false,
"source": "body",
"description": "订单 ID 数组(与 orderIds 互为别名)。至少需提供 order_ids/orderIds/waveGroups/data.waveGroups 中的一类以提取订单 ID。",
"children": [
{
"name": "id",
"type": "number",
"description": "订单 ID"
}
]
},
{
"name": "orderIds",
"type": "array",
"required": false,
"source": "body",
"description": "订单 ID 数组(驼峰兼容,等同于 order_ids)。",
"children": [
{
"name": "id",
"type": "number",
"description": "订单 ID"
}
]
},
{
"name": "waveGroups",
"type": "array",
"required": false,
"source": "body",
"description": "波次分组结构(可从中提取订单 ID,参考 order.print.getWavePlatformPrintData 返回的 waveGroups)。",
"children": [
{
"name": "wave_id",
"type": "number",
"description": "波次 ID"
}
]
},
{
"name": "data",
"type": "object",
"required": false,
"source": "body",
"description": "兼容包装对象;若传入 data.waveGroups,可从中提取订单 ID。",
"children": [
{
"name": "waveGroups",
"type": "array",
"required": false,
"description": "同上,来自 order.print.getWavePlatformPrintData 的 data.waveGroups 结构。"
}
]
}
],
"response": [
{
"name": "locked_count",
"type": "number",
"required": false,
"description": "成功锁定的订单数量"
},
{
"name": "order_ids_count",
"type": "number",
"required": false,
"description": "请求中识别出的订单 ID 数量"
},
{
"name": "order_ids",
"type": "array",
"required": false,
"description": "本次尝试锁定的订单 ID 列表"
},
{
"name": "source",
"type": "string",
"required": false,
"description": "操作来源标识(可选,若后端返回则提供具体来源)"
}
],
"errors": [
{
"code": 400,
"message": "无有效订单ID(order_ids/orderIds/waveGroups/data.waveGroups 均未提供或均无有效订单)"
},
{
"code": 500,
"message": "订单锁定失败"
}
]
},
{
"method": "print.notify_lock",
"description": "兼容别名(等价转调到 print.notifyLock);建议使用 print.notifyLock。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
}
]
},
{
"groupName": "打印机站点模块",
"module": "printer.station",
"list": [
{
"method": "printer.station.list",
"description": "获取打印站点列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
}
]
},
{
"groupName": "打印模板模块",
"module": "setting.printTemplate",
"list": [
{
"method": "setting.printTemplate.list",
"description": "获取打印模板树",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.printTemplate.save",
"description": "保存打印模板",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.printTemplate.create",
"description": "创建打印模板(platform 固定为 default,template_type 固定为 CUSTOM,template_url 固定为空字符串)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "template_name",
"type": "string",
"required": true,
"source": "body",
"description": "模板名称"
},
{
"name": "business_type",
"type": "string",
"required": true,
"source": "body",
"description": "业务类型"
},
{
"name": "page_width",
"type": "number",
"required": true,
"source": "body",
"description": "页面宽度(mm)"
},
{
"name": "page_height",
"type": "number",
"required": true,
"source": "body",
"description": "页面高度(mm)"
},
{
"name": "template_content",
"type": "array",
"required": false,
"source": "body",
"description": "模板内容,可省略;省略时默认创建空模板内容"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "新建模板ID"
}
],
"errors": [
{
"code": "400",
"description": "参数错误(缺少 template_name、business_type、page_width 或 page_height)"
},
{
"code": "409",
"description": "同一业务类型和平台下已存在自定义模板"
}
]
},
{
"method": "setting.printTemplate.delete",
"description": "删除打印模板(软删除)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "模板ID"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "删除的模板ID"
}
],
"errors": [
{
"code": "400",
"description": "参数错误(缺少 id)"
},
{
"code": "404",
"description": "模板不存在或无权限"
}
]
},
{
"method": "setting.printTemplate.listTemplatesByType",
"description": "按业务类型查询模板",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "businessType",
"type": "string",
"required": true,
"source": "body",
"description": "businessType 参数"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "仓库设置模块",
"module": "setting.warehouse",
"list": [
{
"method": "setting.warehouse.getSettings",
"description": "获取当前登录仓库的 subject_config",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "仓库 ID"
},
{
"name": "subject_config",
"type": "object",
"required": true,
"description": "仓库的 subject_config 配置对象"
},
{
"name": "subject_config.enable_external_express_code",
"type": "boolean",
"required": true,
"description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)"
}
],
"errors": [
{
"code": "400",
"message": "未识别到当前仓库"
},
{
"code": "404",
"message": "仓库不存在"
},
{
"code": "500",
"message": "获取失败"
}
]
},
{
"method": "setting.warehouse.getFieldMeta",
"description": "获取仓库设置字段元信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [
{
"name": "list",
"type": "array",
"description": "字段元信息数组",
"children": [
{
"name": "key",
"type": "string",
"description": "字段 key"
},
{
"name": "name",
"type": "string",
"description": "字段名称"
},
{
"name": "type",
"type": "string",
"description": "字段类型"
},
{
"name": "default",
"type": "any",
"description": "默认值(按字段类型返回)"
},
{
"name": "required",
"type": "boolean",
"description": "是否必填"
},
{
"name": "description",
"type": "string",
"description": "字段描述"
},
{
"name": "options",
"type": "array",
"description": "可选项(仅当 type 为 select/enum 时返回)"
},
{
"name": "min",
"type": "number",
"description": "数值型最小值(可选)"
},
{
"name": "max",
"type": "number",
"description": "数值型最大值(可选)"
},
{
"name": "maxLength",
"type": "number",
"description": "字符串最大长度(可选)"
}
]
}
],
"errors": [
{
"code": "500",
"description": "获取失败"
}
]
},
{
"method": "setting.warehouse.saveSettings",
"description": "修改仓库设置并清理指定仓库缓存",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "subject_config",
"type": "object",
"required": true,
"source": "body",
"description": "仓库的 subject_config 对象"
},
{
"name": "cache_warehouse_id",
"type": "number",
"required": false,
"source": "body",
"description": "需清理缓存的仓库 ID(下划线命名兼容)"
},
{
"name": "cacheWarehouseId",
"type": "number",
"required": false,
"source": "body",
"description": "需清理缓存的仓库 ID(驼峰命名兼容)"
},
{
"name": "subject_config.enable_external_express_code",
"type": "boolean",
"required": false,
"source": "body.subject_config",
"description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)"
}
],
"response": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "生效的仓库 ID"
},
{
"name": "subject_config",
"type": "object",
"required": true,
"description": "保存后的 subject_config"
},
{
"name": "cache_cleared_warehouse_id",
"type": "number",
"required": true,
"description": "被清理缓存的仓库 ID(若未清理则为 null)"
},
{
"name": "subject_config.enable_external_express_code",
"type": "boolean",
"required": true,
"description": "保存后的 subject_config.enable_external_express_code 值"
}
],
"errors": [
{
"code": "400",
"message": "未识别到当前仓库/参数不合法"
},
{
"code": "404",
"message": "仓库不存在"
},
{
"code": "500",
"message": "保存失败"
}
]
}
]
},
{
"groupName": "平台编码管理模块",
"module": "setting.platform",
"list": [
{
"method": "index.getPlatformList",
"description": "获取平台列表。默认返回系统基础平台与当前登录仓库自定义平台设置的合并结果:系统平台在前,仓库自定义编码在后,同一 `code` 仅保留首条(系统同码优先保留系统记录)。当 `systemOnly` 为真值(支持 `true`、`1`、`'1'`、`'true'`)时,仅返回系统基础平台列表。`full` 为真值时返回全量字段(包含 wms_platform 全部表字段、route_platform_code、platid 等)。仓库范围来自当前登录用户 `ctx.user.store_id`;未识别到仓库时,自定义设置列表为空。接口优先读取缓存,未命中时回源 `wms_platform` 与 `wms_platfrom_setting`。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "systemOnly",
"type": "boolean|number|string",
"required": false,
"source": "body",
"description": "是否仅返回系统基础平台列表;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理。也支持 `is_system` 别名(若请求体中同时存在 `is_system` 和 `systemOnly`,优先使用 `is_system`)"
},
{
"name": "full",
"type": "boolean|number|string",
"required": false,
"source": "body",
"description": "是否返回全量字段;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理。为 true 时返回 wms_platform 全部表字段、route_platform_code、platid 等扩展信息"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功时为 `success`"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回消息,成功时通常为 `ok`"
},
{
"name": "data",
"type": "array",
"required": true,
"description": "平台列表数组。默认模式下先返回系统基础平台,再追加当前仓库自定义设置;`systemOnly=true` 时仅返回系统基础平台。每项字段如下:",
"children": [
{
"name": "code",
"type": "string",
"description": "平台编码。系统平台项为 `wms_platform.code`;仓库自定义项为 `wms_platfrom_setting.code`"
},
{
"name": "name",
"type": "string",
"description": "展示名称。系统平台项为 `wms_platform.name`;仓库自定义项格式为 `<自定义编码> (<系统平台名>)`,若未匹配到系统平台名则退化为自定义编码"
},
{
"name": "value",
"type": "string",
"description": "与 `code` 相同,供前端选项组件直接使用"
},
{
"name": "label",
"type": "string",
"description": "与 `name` 相同,供前端选项组件直接使用"
},
{
"name": "platform_code",
"type": "string",
"description": "系统平台编码。系统平台项与 `code` 相同;仓库自定义项为 `wms_platfrom_setting.platform_code`(即该自定义编码所关联的系统平台编码)"
},
{
"name": "platform_name",
"type": "string",
"description": "系统平台名称。系统平台项与 `name` 相同;仓库自定义项为关联的系统平台名称"
},
{
"name": "default_express_interface",
"type": "string",
"description": "默认快递接口编码。由 `wms_platform.print_platform_id` → `wms_print_platform.platform_code` 解析得到;未配置时为空字符串"
},
{
"name": "is_system_setting",
"type": "boolean",
"description": "是否为仓库自定义平台设置。`false` 表示系统基础平台,`true` 表示来自当前仓库 `wms_platfrom_setting` 的自定义编码"
},
{
"name": "id",
"type": "number|null",
"description": "仅仓库自定义平台设置项返回,为 `wms_platfrom_setting.id` 记录主键;系统平台项不返回该字段"
},
{
"name": "alias",
"type": "string",
"description": "仅仓库自定义平台设置项返回,当前固定为空字符串(设计预留字段);系统平台项不返回该字段"
},
{
"name": "(full 模式扩展字段)",
"type": "object",
"description": "当 `full=true` 时,每项额外包含:系统平台项追加 `interface_url`、`appkey`、`app_secret`、`token`、`version`、`shoptype`、`ordersource`、`component`、`print_platform_id`(以上均为 wms_platform 原始表字段)、`route_platform_code`(平台后处理路由编码)、`platid`(打印平台 platid,仅当 print_platform_id 可映射时);仓库自定义项追加 `warehouse_id`、`route_platform_code` 及 wms_platfrom_setting 全部原始字段"
}
]
}
],
"errors": [
{
"code": 500,
"message": "获取平台列表失败(数据库或缓存访问异常)"
}
]
},
{
"method": "setting.platform.list",
"description": "查询当前仓库范围的平台设置列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.platform.create",
"description": "创建当前仓库范围的平台设置",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.platform.update",
"description": "更新当前仓库范围的平台设置",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.platform.delete",
"description": "删除当前仓库范围的平台设置",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
}
]
},
{
"groupName": "快递编码管理模块",
"module": "setting.express",
"list": [
{
"method": "index.getExpressList",
"description": "获取快递列表。默认返回系统基础快递与当前登录仓库自定义快递编码的合并结果:系统快递在前,仓库自定义编码在后,同一 `code` 仅保留首条(系统同码优先保留系统记录)。当 `systemOnly` 为真值(支持 `true`、`1`、`'1'`、`'true'`)时,仅返回系统基础快递列表。仅接受 `express_code` 入参,服务端会先 trim 再转为大写:`systemOnly=true` 时按系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义编码映射记录中的系统快递编码字段 `express_code` 过滤,仅返回当前登录仓库下匹配该系统快递编码的自定义编码列表,不再回传系统基础项。仓库范围来自当前登录用户 `ctx.user.store_id`;未识别到仓库时,自定义编码列表为空。接口优先读取缓存,未命中时回源 `wms_express` 与 `wms_express_setting`。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "systemOnly",
"type": "boolean|number|string",
"required": false,
"source": "body",
"description": "是否仅返回系统基础快递列表;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理"
},
{
"name": "express_code",
"type": "string",
"required": false,
"source": "body",
"description": "系统快递编码;服务端会去首尾空格并转为大写。`systemOnly=true` 时按该系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义映射记录中的系统快递编码字段 `express_code` 过滤当前仓库的自定义编码列表,而不是按自定义 `code` 过滤"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功时为 `success`"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回消息,成功时通常为 `ok`"
},
{
"name": "data",
"type": "array",
"required": true,
"description": "快递列表数组。默认模式下先返回系统基础快递,再追加当前仓库自定义编码;当传入 `express_code` 且 `systemOnly=false` 时,仅返回当前仓库下系统快递编码等于该 `express_code` 的自定义映射记录,不返回系统基础项。每项字段如下:",
"children": [
{
"name": "code",
"type": "string",
"description": "返回项编码。系统项为系统快递编码;仓库自定义项为自定义快递编码"
},
{
"name": "name",
"type": "string",
"description": "展示名称。系统项为快递名称;仓库自定义项格式通常为 `<自定义编码> (<系统快递名>)`,若未匹配到系统快递名则退化为自定义编码"
},
{
"name": "value",
"type": "string",
"description": "与 `code` 相同,供前端选项组件直接使用"
},
{
"name": "label",
"type": "string",
"description": "与 `name` 相同,供前端选项组件直接使用"
},
{
"name": "is_system_setting",
"type": "boolean",
"description": "是否为仓库自定义快递编码;`false` 表示系统基础快递,`true` 表示来自当前仓库 `wms_express_setting` 的自定义编码"
},
{
"name": "id",
"type": "number|null",
"description": "仓库自定义快递设置记录 ID;系统基础快递固定为 `null`"
},
{
"name": "alias",
"type": "string|null",
"description": "仓库自定义快递设置表中的原始名称(`wms_express_setting.name`);系统基础快递固定为 `null`"
},
{
"name": "express_code",
"type": "string",
"description": "仅仓库自定义快递编码项返回其关联的系统快递编码;当 `systemOnly=false` 且传入筛选值时,即按该字段匹配自定义映射记录。系统基础快递项通常不返回该字段"
}
]
}
],
"errors": [
{
"code": 500,
"message": "获取快递列表失败(数据库或缓存访问异常)"
}
]
},
{
"method": "setting.express.list",
"description": "查询当前仓库范围的快递映射列表,支持 where + pagination",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构"
}
],
"response": [],
"errors": []
},
{
"method": "setting.express.listBase",
"description": "返回系统快递基础列表(系统级别基础快递,不含仓库自定义)",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [],
"response": [],
"errors": []
},
{
"method": "setting.express.create",
"description": "创建快递映射,仅写入已实现字段(code、name、express_code 等)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "快递映射编码;接口会转为大写"
},
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "快递名称(最大 50 字符)"
},
{
"name": "express_code",
"type": "string",
"required": true,
"source": "body",
"description": "系统快递编码;同时支持驼峰写法 expressCode"
}
],
"response": [],
"errors": []
},
{
"method": "setting.express.checkCodeUnique",
"description": "校验快递编码在当前仓库/主体维度唯一性,仅支持 code 与可选 id 排除自身",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "待校验的快递编码"
},
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "排除自身 id(更新时使用)"
}
],
"response": [],
"errors": []
},
{
"method": "setting.express.update",
"description": "更新快递映射。必须提供 `id`(必填),且至少提供 `code`、`name` 或 `express_code` 中的一个用于更新;同时支持 `expressCode` 驼峰写法。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "快递记录ID;也兼容别名 `setting_id` / `settingId`"
},
{
"name": "code",
"type": "string",
"required": false,
"source": "body",
"description": "快递映射编码(最大 50 字符,接口会大写化并校验在当前仓库的唯一性)"
},
{
"name": "name",
"type": "string",
"required": false,
"source": "body",
"description": "快递名称(最大 50 字符)"
},
{
"name": "express_code",
"type": "string",
"required": false,
"source": "body",
"description": "系统快递编码(必须为系统已存在的编码);支持 `expressCode` 驼峰写法"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "更新后的快递映射对象(规范化字段)",
"children": [
{
"name": "id",
"type": "number",
"description": "记录ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "所属仓库ID"
},
{
"name": "code",
"type": "string",
"description": "快递映射编码"
},
{
"name": "name",
"type": "string",
"description": "快递名称"
},
{
"name": "express_code",
"type": "string",
"description": "系统快递编码"
},
{
"name": "express_name",
"type": "string",
"description": "系统快递名称(从系统快递表映射)"
}
]
}
],
"errors": [
{
"code": "400",
"message": "id 参数不能为空"
},
{
"code": "400",
"message": "至少需要提供一个可更新字段"
},
{
"code": "400",
"message": "code 参数不能为空"
},
{
"code": "400",
"message": "express_code 参数不能为空"
},
{
"code": "400",
"message": "系统快递编码不存在"
},
{
"code": "404",
"message": "快递映射不存在或无权限操作"
},
{
"code": "409",
"message": "快递编码已被当前仓库使用"
}
]
},
{
"method": "setting.express.delete",
"description": "批量软删除快递映射;接受 ids 参数,已删除记录会在结果中标记。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "待删除的映射ID数组;支持数组、逗号字符串或单个ID。"
}
],
"response": [
{
"name": "ids",
"type": "array",
"required": true,
"description": "请求中的所有 id 列表(原样返回)"
},
{
"name": "deleted_ids",
"type": "array",
"required": true,
"description": "本次实际被软删除的 ID 列表(即原本未被删除的 ID)"
},
{
"name": "already_deleted_ids",
"type": "array",
"required": true,
"description": "请求中已处于已删除状态的 ID 列表"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "固定返回 'deleted'"
}
],
"errors": [
{
"code": "400",
"message": "ids 参数不能为空或格式错误"
},
{
"code": "404",
"message": "快递映射不存在或无权限操作"
},
{
"code": "409",
"message": "存在快递接口引用的快递编码,无法删除"
}
]
}
]
},
{
"groupName": "快递接口管理模块",
"module": "setting.expressInterface",
"list": [
{
"method": "setting.expressInterface.list",
"description": "查询当前仓库范围的快递接口列表,支持 where + pagination;返回 data:{ list, total, page, page_size }。按 weight 升序、id 降序排序,优先按权重排序。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "pagination"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "支持按 shop_id 过滤"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"children": [
{
"name": "id",
"type": "number",
"description": "id",
"required": true
},
{
"name": "name",
"type": "string",
"description": "name",
"required": true
},
{
"name": "shop_id",
"type": "number",
"description": "店铺 ID,未绑定时返回 null",
"required": false
},
{
"name": "is_system_express_code",
"type": "number",
"description": "该行 express_code 是否为系统快递编码;若不是系统快递编码返回 0,否则返回 1",
"required": true
}
],
"description": "list,按 weight 升序、id 降序排序;优先按权重排序,权重相同再按 id 倒序"
},
{
"name": "total",
"type": "number",
"description": "total",
"required": true
},
{
"name": "page",
"type": "number",
"description": "page",
"required": true
},
{
"name": "page_size",
"type": "number",
"description": "page_size",
"required": true
}
],
"errors": []
},
{
"method": "setting.expressInterface.listByWarehousePlatformCode",
"description": "按 warehouse_id + platform_code 查询快递接口全字段数组,支持缓存;返回结果按 weight 升序、必要时按 id 升序排序,每条记录显式包含 express_code 以及关联的 express 对象(如 express.id/express.code/express.name/express.platform)。该接口不分页,按 warehouse_id + platform_code 全量返回匹配记录。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id / warehouseId",
"type": "number",
"required": false,
"source": "body",
"description": "仓库ID;默认使用当前登录主体/仓库上下文(ctx.user.store_id),也支持显式传入以查询指定仓库,文档兼容 warehouse_id 与 warehouseId 两种写法。"
},
{
"name": "platform_code / platformCode",
"type": "string",
"required": true,
"source": "body",
"description": "平台代码;作为缓存键的一部分,建议使用大写形式(服务端会标准化处理)。"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "快递接口记录数组(按 warehouse_id + platform_code 全量返回,不分页),每项包含以下字段:",
"children": [
{
"name": "id",
"type": "number",
"description": "记录ID"
},
{
"name": "name",
"type": "string",
"description": "接口名称"
},
{
"name": "express_code",
"type": "string",
"description": "快递编码"
},
{
"name": "warehouse_id",
"type": "number",
"description": "所属仓库ID(文档中的仓库范围由系统强制校验)"
},
{
"name": "platform_code",
"type": "string",
"description": "平台代码"
},
{
"name": "express_platform_id",
"type": "number",
"description": "平台接口ID"
},
{
"name": "sender_name",
"type": "string",
"description": "发件人姓名"
},
{
"name": "sender_tel",
"type": "string",
"description": "发件人电话"
},
{
"name": "weight",
"type": "number",
"description": "默认重量"
},
{
"name": "token",
"type": "string",
"description": "接口密钥或 token(部分记录可能为空)"
},
{
"name": "viewer",
"type": "string",
"description": "查看者标识"
},
{
"name": "client_id",
"type": "string",
"description": "客户端 ID"
},
{
"name": "is_share",
"type": "number",
"description": "是否共享(0/1)"
},
{
"name": "share_id",
"type": "number",
"description": "共享记录ID"
},
{
"name": "can_use_count",
"type": "number",
"description": "可用次数或配额"
},
{
"name": "province_name",
"type": "string",
"description": "省"
},
{
"name": "city_name",
"type": "string",
"description": "市"
},
{
"name": "district_name",
"type": "string",
"description": "区/县"
},
{
"name": "site_code",
"type": "string",
"description": "站点编码"
},
{
"name": "product_type",
"type": "string",
"description": "快递产品类型"
},
{
"name": "shop_name",
"type": "string",
"description": "店铺名称/分组标识"
},
{
"name": "ext_data",
"type": "object",
"description": "扩展信息 JSON(支持任意键值对象)"
},
{
"name": "express",
"type": "object",
"description": "关联的快递对象(若存在),包含基础快递信息,便于前端展示与回源校验",
"children": [
{
"name": "id",
"type": "number",
"description": "快递主表 ID"
},
{
"name": "code",
"type": "string",
"description": "快递编码"
},
{
"name": "name",
"type": "string",
"description": "快递名称"
},
{
"name": "platform",
"type": "string",
"description": "所属平台标识"
}
]
}
]
}
],
"errors": [
{
"code": "400",
"description": "缺少 platform_code 或仓库上下文错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "setting.expressInterface.create",
"description": "在当前仓库范围内创建快递接口,支持 shop_id/shopId 入参。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "name"
},
{
"name": "express_code",
"type": "string",
"required": true,
"source": "body",
"description": "express_code"
},
{
"name": "platform_code",
"type": "string",
"required": true,
"source": "body",
"description": "platform_code"
},
{
"name": "shop_id",
"type": "number",
"required": false,
"source": "body",
"description": "店铺 ID(支持 shopId),正整数,可空;未传或空值按 null 处理"
},
{
"name": "address",
"type": "string",
"required": false,
"source": "body",
"description": "发件人详细地址(可选),使用 index.getShopExpressList 返回的 detail 字段值,非 full_address"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "新建记录 ID"
}
],
"errors": []
},
{
"method": "setting.expressInterface.update",
"description": "更新快递接口,支持 shop_id/shopId 入参(可空)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id"
},
{
"name": "shop_id",
"type": "number",
"required": false,
"source": "body",
"description": "shop_id"
},
{
"name": "address",
"type": "string",
"required": false,
"source": "body",
"description": "发件人详细地址(可选),使用 index.getShopExpressList 返回的 detail 字段值,非 full_address"
}
],
"response": [
{
"name": "id",
"type": "number",
"description": "id",
"required": true
}
],
"errors": []
},
{
"method": "setting.expressInterface.delete",
"description": "删除快递接口,支持 id 别名 interface_id / interfaceId;返回被删除记录 id 与所属 warehouse_id。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "快递接口ID;兼容 interface_id / interfaceId"
}
],
"response": [
{
"name": "id",
"type": "number",
"description": "已删除记录 ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "记录所属仓库 ID"
},
{
"name": "deleted",
"type": "boolean",
"description": "是否已删除,成功时为 true"
}
],
"errors": [
{
"code": "400",
"description": "id 为空或格式错误"
},
{
"code": "404",
"description": "快递接口不存在或无权限操作"
}
]
},
{
"method": "index.getPrintPlatformList",
"description": "获取打印平台全量列表。供前端新增、修改快递接口时下拉选择使用;仅返回未删除且状态为 `ACTIVE` 的打印平台,不分页,按 `platform_name` 升序、`id` 升序返回。接口不校验额外鉴权或权限点,但需要登录态。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "全局调用结果标识,成功时为 `success`"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功时返回 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "返回消息,成功时通常为 `ok`"
},
{
"name": "data",
"type": "array",
"required": true,
"description": "打印平台列表数组,不分页,仅包含未删除且状态为 `ACTIVE` 的平台;按 `platform_name` 升序、`id` 升序返回。每项字段如下:",
"children": [
{
"name": "id",
"type": "number|null",
"description": "打印平台主键 ID;原始值为空时返回 `null`"
},
{
"name": "code",
"type": "string",
"description": "打印平台编码,等同于 `platform_code`,服务端会标准化为大写"
},
{
"name": "name",
"type": "string",
"description": "打印平台展示名称;若原始 `platform_name` 为空,则回退为 `platform_code`"
},
{
"name": "value",
"type": "string",
"description": "与 `code` 相同,供前端选项组件直接使用"
},
{
"name": "label",
"type": "string",
"description": "与 `name` 相同,供前端选项组件直接使用"
},
{
"name": "platform_code",
"type": "string",
"description": "打印平台编码,大写返回"
},
{
"name": "platform_name",
"type": "string|null",
"description": "打印平台名称;为空时前端可使用 `name` 或 `label` 展示"
},
{
"name": "status",
"type": "string",
"description": "平台状态;当前接口仅返回 `ACTIVE`,若原始值缺失会兜底为 `ACTIVE`"
},
{
"name": "remark",
"type": "string|null",
"description": "打印平台备注;无备注时返回 `null`"
}
]
}
],
"errors": [
{
"code": 500,
"message": "获取打印平台列表失败"
}
]
}
]
},
{
"groupName": "账号管理模块",
"module": "setting.account",
"list": [
{
"method": "setting.account.list",
"description": "查询当前主体下的工号基础信息列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "状态筛选,默认 1,仅查有效工号"
},
{
"name": "includeDisabled",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否包含已删除工号"
}
],
"response": [
{
"name": "data[]",
"type": "object",
"required": true,
"description": "工号列表项"
},
{
"name": "data[].employee_id",
"type": "number",
"required": true,
"description": "工号ID"
},
{
"name": "data[].account_id",
"type": "number",
"required": true,
"description": "账号ID"
},
{
"name": "data[].store_id",
"type": "number",
"required": true,
"description": "主体ID"
},
{
"name": "data[].real_name",
"type": "string",
"required": true,
"description": "工号姓名"
},
{
"name": "data[].status",
"type": "number",
"required": true,
"description": "工号状态:1=启用,0=停用"
},
{
"name": "data[].username",
"type": "string",
"required": true,
"description": "账号用户名"
},
{
"name": "data[].phone",
"type": "string",
"required": true,
"description": "账号手机号"
},
{
"name": "data[].email",
"type": "string",
"required": true,
"description": "账号邮箱"
},
{
"name": "data[].avatar_file_id",
"type": "number",
"required": false,
"description": "头像文件ID,为空表示未设置"
},
{
"name": "data[].avatar_url",
"type": "string",
"required": true,
"description": "头像访问地址"
}
],
"errors": [
{
"code": "400",
"description": "当前登录态缺少主体上下文(store_id)"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "setting.account.add",
"description": "新增工号,按手机号复用或创建账号后绑定到当前主体",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "phone",
"type": "string",
"required": true,
"source": "body",
"description": "手机号,作为账号复用/创建依据"
},
{
"name": "real_name",
"type": "string",
"required": true,
"source": "body",
"description": "工号姓名,新增时禁止直接使用保留名称"
},
{
"name": "username",
"type": "string",
"required": false,
"source": "body",
"description": "新账号用户名,不传时系统自动生成"
},
{
"name": "password",
"type": "string",
"required": false,
"source": "body",
"description": "新账号密码,不传默认 111111"
},
{
"name": "role_id",
"type": "number",
"required": false,
"source": "body",
"description": "工号角色,不传时继承当前操作人工号角色"
},
{
"name": "email",
"type": "string",
"required": false,
"source": "body",
"description": "新账号邮箱,不传时按 username 自动生成"
}
],
"response": [
{
"name": "employee_id",
"type": "number",
"required": true,
"description": "新增或复用后的工号ID"
},
{
"name": "account_id",
"type": "number",
"required": true,
"description": "绑定账号ID"
},
{
"name": "role_id",
"type": "number",
"required": true,
"description": "绑定后的角色ID"
},
{
"name": "is_new_account",
"type": "boolean",
"required": true,
"description": "是否为本次新建账号"
},
{
"name": "phone",
"type": "string",
"required": true,
"description": "绑定账号手机号"
},
{
"name": "username",
"type": "string",
"required": true,
"description": "绑定账号用户名"
}
],
"errors": [
{
"code": "400",
"description": "参数错误、手机号格式错误、或直接使用保留名称"
},
{
"code": "409",
"description": "手机号对应账号已禁用、手机号已绑定当前主体工号、或用户名重复"
},
{
"code": "500",
"description": "新增失败"
}
]
},
{
"method": "setting.account.delete",
"description": "删除工号绑定关系,仅停用工号,不删除账号",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "employee_id",
"type": "number",
"required": true,
"source": "body",
"description": "要删除的工号ID"
}
],
"response": [
{
"name": "employee_id",
"type": "number",
"required": true,
"description": "被停用的工号ID"
},
{
"name": "account_id",
"type": "number",
"required": true,
"description": "关联账号ID"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "固定返回 deleted"
},
{
"name": "already_deleted",
"type": "boolean",
"required": false,
"description": "可选,true 表示该工号原本已停用"
}
],
"errors": [
{
"code": "400",
"description": "参数错误或尝试删除当前登录工号"
},
{
"code": "404",
"description": "工号不存在或无权限删除"
},
{
"code": "500",
"description": "删除失败"
}
]
},
{
"method": "setting.account.update",
"description": "更新工号姓名和头像引用",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "employee_id",
"type": "number",
"required": true,
"source": "body",
"description": "要更新的工号ID"
},
{
"name": "real_name",
"type": "string",
"required": false,
"source": "body",
"description": "更新后的工号姓名"
},
{
"name": "file_id",
"type": "number",
"required": false,
"source": "body",
"description": "已有文件ID,作为头像引用"
}
],
"response": [
{
"name": "employee_id",
"type": "number",
"required": true,
"description": "更新后的工号ID"
},
{
"name": "real_name",
"type": "string",
"required": true,
"description": "更新后的工号姓名"
},
{
"name": "avatar_file_id",
"type": "number",
"required": false,
"description": "更新后的头像文件ID"
},
{
"name": "avatar_url",
"type": "string",
"required": true,
"description": "更新后的头像地址"
}
],
"errors": [
{
"code": "400",
"description": "参数错误,未提供更新项"
},
{
"code": "404",
"description": "工号或头像文件不存在"
},
{
"code": "500",
"description": "更新失败"
}
]
},
{
"method": "setting.account.getBindWechatCode",
"description": "为指定工号账号获取微信绑定码",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "account_id",
"type": "number",
"required": true,
"source": "body",
"description": "目标账号ID,兼容 user_id / id"
},
{
"name": "longPoll",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否开启长轮询等待状态变化,最长60秒"
},
{
"name": "waitTimeoutMs",
"type": "number",
"required": false,
"source": "body",
"description": "等待超时毫秒数,后端自动封顶60000"
}
],
"response": [],
"errors": []
},
{
"method": "setting.account.unbindWechat",
"description": "为指定工号账号解绑微信",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "account_id",
"type": "number",
"required": true,
"source": "body",
"description": "目标账号ID,兼容 user_id / id"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "权限管理模块",
"module": "setting.permission",
"list": [
{
"method": "setting.permission.list",
"description": "查询权限树/权限列表,可附带指定角色的选中状态",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "role_id",
"type": "number",
"required": false,
"source": "body",
"description": "角色ID;传入后返回 selected 标记"
},
{
"name": "type",
"type": "string",
"required": false,
"source": "body",
"description": "权限类型筛选:web_pages/pda_pages/btns/api/miniprogram_pages/block"
},
{
"name": "keyword",
"type": "string",
"required": false,
"source": "body",
"description": "关键字模糊搜索 path/name/meta_title"
},
{
"name": "includeDisabled",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否包含已停用权限"
}
],
"response": [],
"errors": []
},
{
"method": "setting.permission.add",
"description": "新增权限节点",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "path",
"type": "string",
"required": true,
"source": "body",
"description": "权限路径"
},
{
"name": "type",
"type": "string",
"required": true,
"source": "body",
"description": "权限类型"
},
{
"name": "name",
"type": "string",
"required": false,
"source": "body",
"description": "权限名称"
},
{
"name": "parent_id",
"type": "number",
"required": false,
"source": "body",
"description": "父级权限ID"
}
],
"response": [],
"errors": []
},
{
"method": "setting.permission.update",
"description": "更新权限节点信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "permission_id",
"type": "number",
"required": true,
"source": "body",
"description": "权限ID"
}
],
"response": [],
"errors": []
},
{
"method": "setting.permission.delete",
"description": "批量停用权限节点",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "待停用的权限ID数组"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "角色管理模块",
"module": "setting.role",
"list": [
{
"method": "setting.role.list",
"description": "获取当前主体可管理的角色树",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "includeDisabled",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否包含已停用角色"
},
{
"name": "includeSystem",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否包含系统角色域"
}
],
"response": [],
"errors": []
},
{
"method": "setting.role.permission",
"description": "获取角色权限树(兼容旧入口,等同于 setting.permission.list)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "role_id",
"type": "number",
"required": false,
"source": "body",
"description": "角色ID"
}
],
"response": [],
"errors": []
},
{
"method": "setting.role.add",
"description": "新增角色并绑定权限集合",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "role_code",
"type": "string",
"required": true,
"source": "body",
"description": "角色编码"
},
{
"name": "role_name",
"type": "string",
"required": true,
"source": "body",
"description": "角色名称"
},
{
"name": "permission_ids",
"type": "array",
"required": true,
"source": "body",
"description": "权限ID数组,支持 [\"*\"]"
},
{
"name": "pid",
"type": "number",
"required": false,
"source": "body",
"description": "父角色ID"
}
],
"response": [],
"errors": []
},
{
"method": "setting.role.update",
"description": "更新角色信息并重设权限集合",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "role_id",
"type": "number",
"required": true,
"source": "body",
"description": "角色ID"
},
{
"name": "permission_ids",
"type": "array",
"required": true,
"source": "body",
"description": "权限ID数组,角色权限需一次性提交"
}
],
"response": [],
"errors": []
},
{
"method": "setting.role.delete",
"description": "批量停用角色",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "待停用的角色ID数组"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "商品模块",
"module": "stock",
"list": [
{
"method": "stock.warehouse.list",
"description": "仓库商品列表查询(支持 where 条件与分页)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "pagination 参数"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、barcode、prohibited_type 等商品筛选字段。示例:where.barcode={operator:like,value:69}; where.prohibited_type={operator:eq,value:liquid}。"
}
],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.export",
"description": "提交导出任务,返回 task_id/status/progress/message/result/error/update_time",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "查询条件对象,与 stock.warehouse.list 的 where 语义一致;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数对象,支持 sortField/sortOrder 与 sort_field/sort_order 下划线别名兼容。"
},
{
"name": "sort.sortField",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序字段(兼容 sort.sortField)。"
},
{
"name": "sort.sort_field",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序字段下划线别名(兼容 sort.sort_field)。"
},
{
"name": "sort.sortOrder",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序方向(ASC/DESC,大小写不敏感)。"
},
{
"name": "sort.sort_order",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序方向下划线别名(兼容 sort.sort_order)。"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"description": "任务 ID(后端生成的唯一标识)"
},
{
"name": "status",
"type": "string",
"description": "任务状态,枚举:submitted/running/success/failed/not_found"
},
{
"name": "progress",
"type": "number",
"description": "进度百分比(0-100)"
},
{
"name": "message",
"type": "string",
"description": "额外提示信息或受理消息"
},
{
"name": "result",
"type": "object",
"description": "任务成功时返回的结果对象(可选)"
},
{
"name": "error",
"type": "string",
"description": "失败时的错误信息(可选)"
},
{
"name": "update_time",
"type": "string",
"description": "最近一次状态更新时间,ISO8601 字符串(可选)"
}
],
"errors": [
{
"code": 400,
"message": "参数格式不正确或 where 条件非法"
},
{
"code": 500,
"message": "导出任务提交失败"
}
]
},
{
"method": "stock.warehouse.exportTaskProgress",
"description": "按 task_id 查询导出任务进度,未找到时 status=not_found",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id / taskId",
"type": "string",
"required": true,
"source": "body|query",
"description": "任务 ID,兼容 taskId"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"description": "任务 ID"
},
{
"name": "status",
"type": "string",
"description": "任务状态:submitted/running/success/failed/not_found"
},
{
"name": "progress",
"type": "number",
"description": "进度百分比(0-100)"
},
{
"name": "message",
"type": "string",
"description": "额外提示信息"
},
{
"name": "result",
"type": "object",
"description": "任务成功时返回的结果对象(可选)"
},
{
"name": "error",
"type": "string",
"description": "失败时的错误信息(可选)"
},
{
"name": "download_url",
"type": "string",
"description": "任务完成后可直接下载的文件地址(若有)"
},
{
"name": "update_time",
"type": "string",
"description": "最近一次状态更新时间,ISO8601 字符串(可选)"
}
],
"errors": [
{
"code": 400,
"message": "task_id 参数不能为空"
},
{
"code": 500,
"message": "查询失败或内部错误"
}
]
},
{
"method": "stock.warehouse.getProhibitedType",
"description": "查询违禁品类型列表(系统预设+仓库自定义)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.getInfo",
"description": "查询仓库商品详情",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.getStockDetail",
"description": "按库位/批次维度查询商品库存分布",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "stock_id",
"type": "number",
"required": true,
"source": "body",
"description": "商品库存ID(stock_warehouse.id)"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,包含 page/pageSize"
},
{
"name": "group_by_batch",
"type": "boolean",
"required": false,
"source": "body",
"default": false,
"description": "是否按批次返回明细;true 返回每条明细,false 按库位合并"
}
],
"response": [
{
"name": "stockItem",
"type": "object",
"description": "商品概要,包含 id、item_code、item_name、sku_property、stock_unit、quantity、locked_quantity 等"
},
{
"name": "storageList",
"type": "array",
"description": "库存明细数组;group_by_batch=true 返回 wms_storage 明细(含 batch_no、production_date、expiry_date、inbound_time、inbound_order_no、supplier_batch_no 等),group_by_batch=false 时按库位合并,批次相关字段为 null"
},
{
"name": "pagination",
"type": "object",
"description": "分页信息,包含 page、pageSize、total"
}
],
"errors": []
},
{
"method": "stock.warehouse.saveWarehouseStock",
"description": "更新仓库商品资料",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.createWarehouseStock",
"description": "新建仓库商品资料",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.import",
"description": "批量导入或更新仓库商品。请求体优先直接传入商品数据数组 JSON(主方式为数组);也兼容以 rows/items/list/data 包装。每项仅需包含商品相关字段;当 SKU 为空时创建新商品,SKU 非空时为更新操作;更新会写操作日志以便审计。未传 store_id 时默认使用当前上下文仓库/主体(ctx.user.store_id)。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "items / rows / list / data",
"type": "array",
"required": true,
"source": "body",
"description": "商品数组(主方式为直接传数组 []),也兼容对象包装:{ rows: [...] } / { items: [...] } / { list: [...] } / { data: [...] }。每项可使用下列字段别名:",
"children": [
{
"name": "SKU / sku / id / item_id / itemId",
"type": "string|number",
"description": "SKU 或商品 ID(编辑/更新使用;为空时创建)"
},
{
"name": "商品编码 / item_code / itemCode",
"type": "string",
"description": "商品编码"
},
{
"name": "货物编码 / goods_code / goodsCode",
"type": "string",
"description": "货物编码(支持导入)"
},
{
"name": "SKU规格 / sku_property / skuProperty",
"type": "string",
"description": "规格信息"
},
{
"name": "库存单位 / stock_unit / stockUnit",
"type": "string",
"description": "库存单位"
},
{
"name": "品牌 / brand_name / brandName",
"type": "string",
"description": "品牌"
},
{
"name": "毛重 / gross_weight / grossWeight",
"type": "number",
"description": "毛重(数值,单位与系统一致)"
},
{
"name": "标价 / tag_price / tagPrice",
"type": "number",
"description": "标价"
},
{
"name": "零售价 / retail_price / retailPrice",
"type": "number",
"description": "零售价"
},
{
"name": "store_id / storeId",
"type": "number",
"required": false,
"source": "body",
"description": "可选,货主/仓库 ID;未传入时使用当前上下文(ctx.user.store_id)"
}
]
}
],
"response": [
{
"name": "total_count",
"type": "number",
"description": "解析到的总条目数"
},
{
"name": "created_count",
"type": "number",
"description": "成功创建的新商品数"
},
{
"name": "updated_count",
"type": "number",
"description": "成功更新的商品数"
},
{
"name": "fail_count",
"type": "number",
"description": "导入失败数"
},
{
"name": "created_ids",
"type": "array",
"description": "创建成功的商品 ID 列表"
},
{
"name": "updated_ids",
"type": "array",
"description": "更新成功的商品 ID 列表"
},
{
"name": "fail_items",
"type": "array",
"description": "失败项明细数组,每项包含原始输入与错误信息"
}
],
"errors": [
{
"code": "400",
"description": "导入数据不能为空"
},
{
"code": "400",
"description": "缺少仓库上下文"
},
{
"code": "400",
"description": "导入行数据无效"
},
{
"code": "500",
"description": "导入失败"
}
]
},
{
"method": "stock.warehouse.getBarcodes",
"description": "查询商品条码列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.saveWarehouseStockBarcode",
"description": "保存商品条码信息",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.getStoreStocks",
"description": "查询仓库商品与货主关联列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.bindItem",
"description": "绑定货主商品关系",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.unbindItem",
"description": "解绑货主商品关系",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.checkItemCodeUnique",
"description": "检测商品编码唯一性。在同一仓库和货主下,排除商品自身后,判断商品编码是否已存在于未删除商品中。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "仓库ID;默认使用当前登录主体/仓库上下文(ctx.user.store_id)"
},
{
"name": "item_code",
"type": "string",
"required": true,
"source": "body",
"description": "要检测的商品编码"
},
{
"name": "item_id",
"type": "number",
"required": false,
"source": "body",
"description": "当前商品ID(编辑场景用,排除自身);兼容字段名 id"
},
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "兼容字段 id"
},
{
"name": "owner_id",
"type": "number",
"required": true,
"source": "body",
"description": "货主ID(对应表字段 store_id);兼容字段名 store_id"
},
{
"name": "store_id",
"type": "number",
"required": true,
"source": "body",
"description": "兼容字段 store_id"
}
],
"response": [
{
"name": "unique",
"type": "boolean",
"description": "true 表示编码唯一,false 表示已存在重复"
},
{
"name": "isUnique",
"type": "boolean",
"description": "同 unique(兼容旧字段名)"
},
{
"name": "message",
"type": "string",
"description": "重复时返回 '商品编码已存在',唯一时不返回该字段",
"required": false
}
],
"errors": []
},
{
"method": "stock.warehouse.queryStockLogs",
"description": "查询库存操作日志",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouseId",
"type": "string",
"required": false,
"source": "body",
"description": "warehouseId 参数"
}
],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.handleBatchDelete",
"description": "批量删除仓库商品资料",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.deleteUnit",
"description": "删除库存单位",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.deleteProhibited",
"description": "删除违禁品类型",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.handleBatchChange",
"description": "批量修改仓库商品字段",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "要批量修改的仓库商品记录 ID 数组(stock_warehouse.id)",
"children": [
{
"name": "id",
"type": "number",
"description": "单个记录 ID"
}
]
},
{
"name": "method",
"type": "string",
"required": true,
"source": "body",
"description": "要修改的字段名,可选值:brand_name、prohibited_id、gross_weight、packing_requirements、managementFlags、stock_unit"
},
{
"name": "value",
"type": "string|number|object",
"required": true,
"source": "body",
"description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正数,可含小数);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'"
},
{
"name": "values",
"type": "any",
"required": false,
"source": "body",
"description": "兼容字段:当前实现以 `value` 为准,不使用 `values`。若客户端历史使用 `values`,请切换为 `value`。"
}
],
"response": [
{
"name": "code",
"type": "number",
"description": "业务状态码,200 表示成功;405 表示参数/权限校验不通过;500 表示服务器错误"
},
{
"name": "message",
"type": "string",
"description": "业务提示信息"
},
{
"name": "data",
"type": "object",
"description": "成功时返回的结果对象",
"children": [
{
"name": "affectedRows",
"type": "number",
"description": "被更新的记录数"
},
{
"name": "ids",
"type": "array",
"description": "请求中传入的 ids 数组"
}
]
}
],
"errors": [
{
"code": "405",
"description": "请选择要修改的商品(缺少 ids 或 ids 为空)"
},
{
"code": "405",
"description": "不支持修改的字段: {method}"
},
{
"code": "405",
"description": "修改值不能为空"
},
{
"code": "405",
"description": "违禁品类型必须是数字"
},
{
"code": "405",
"description": "毛重必须是有效的正数"
},
{
"code": "405",
"description": "管理标识必须是对象格式 / 管理标识缺少字段 / 管理标识字段值必须是 'Y' 或 'N'"
},
{
"code": "405",
"description": "部分商品不存在或无权修改: <ids>"
},
{
"code": "405",
"description": "缺少仓库信息"
},
{
"code": "500",
"description": "内部错误:批量修改失败"
}
]
},
{
"method": "stock.warehouse.getStockUnits",
"description": "查询可用库存单位(系统+仓库)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.getUnitList",
"description": "查询当前仓库自定义单位列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.createProhibited",
"description": "新增违禁品类型",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "name 参数"
}
],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.createUnit",
"description": "新增库存单位",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "name",
"type": "string",
"required": true,
"source": "body",
"description": "name 参数"
}
],
"response": [],
"errors": []
},
{
"method": "stock.warehouse.search",
"description": "仓库商品关键字搜索,按 item_code / item_name / goods_code / 条形码模糊匹配,最多返回 50 条",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "keyword",
"type": "string",
"required": false,
"source": "body",
"description": "搜索关键字,模糊匹配 item_code、item_name、goods_code 以及关联的 barcode;为空时返回全部(仍受 limit 50 限制)"
},
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID,传入时仅返回指定货主的商品"
},
{
"name": "with_stock",
"type": "boolean",
"required": false,
"source": "body",
"default": false,
"description": "是否返回关联库存数据(wms_storage),为 true 时每条商品新增 storage[] 字段"
},
{
"name": "is_batch",
"type": "boolean",
"required": false,
"source": "body",
"default": false,
"description": "是否按批次明细返回库存,仅 with_stock=true 时生效。false(默认)按库位分组汇总;true 逐条返回批次明细"
}
],
"response": [
{
"name": "code",
"type": "number",
"description": "业务状态码,200 表示成功"
},
{
"name": "data",
"type": "array",
"description": "商品列表,每项包含以下字段",
"children": [
{
"name": "id",
"type": "number",
"description": "商品库存ID(stock_warehouse.id)"
},
{
"name": "item_code",
"type": "string",
"description": "商品编码"
},
{
"name": "goods_code",
"type": "string",
"description": "货物编码"
},
{
"name": "item_name",
"type": "string",
"description": "商品名称"
},
{
"name": "sku_property",
"type": "string",
"description": "SKU 规格"
},
{
"name": "stock_unit",
"type": "string",
"description": "库存单位"
},
{
"name": "quantity",
"type": "number",
"description": "库存数量"
},
{
"name": "locked_quantity",
"type": "number",
"description": "锁定数量"
},
{
"name": "brand_name",
"type": "string",
"description": "品牌名称"
},
{
"name": "item_type",
"type": "string",
"description": "商品类型"
},
{
"name": "barcodes",
"type": "array",
"description": "商品条形码列表(string[])"
},
{
"name": "store_stock",
"type": "object",
"description": "关联的货主签约信息(LEFT JOIN),含 store_id、store_remask;无签约时为 null"
},
{
"name": "is_shelf_life_mgmt",
"type": "boolean",
"description": "是否启用效期管理(true=启用)"
},
{
"name": "shelf_life_days",
"type": "number",
"description": "商品标准效期/保质期(单位:天)"
},
{
"name": "inbound_min_days",
"type": "number",
"description": "入库后最小可出库天数(单位:天)"
},
{
"name": "outbound_min_days",
"type": "number",
"description": "出库前需保留的最小天数(单位:天)"
},
{
"name": "remaining_threshold_days",
"type": "number",
"description": "剩余天数阈值,低于该值视为即将过期(单位:天)"
},
{
"name": "storage",
"type": "array",
"description": "关联库存明细,仅 with_stock=true 时返回。is_batch=false 时按库位分组汇总,is_batch=true 时逐条返回批次明细",
"children_grouped": {
"description": "is_batch=false(默认):按库位分组汇总,每条包含以下字段",
"fields": [
{
"name": "space_id",
"type": "number",
"description": "库位ID"
},
{
"name": "inventory_type",
"type": "string",
"description": "库存类型"
},
{
"name": "quantity",
"type": "number",
"description": "该库位总库存数量(合并同库位)"
},
{
"name": "locked_quantity",
"type": "number",
"description": "该库位总锁定数量"
},
{
"name": "available_quantity",
"type": "number",
"description": "可用数量(quantity - locked_quantity)"
},
{
"name": "space",
"type": "object",
"description": "库位信息子对象,含 id、space_code、custom_name"
}
]
},
"children_batch": {
"description": "is_batch=true:逐条批次明细,每条包含以下字段",
"fields": [
{
"name": "id",
"type": "number",
"description": "storage 记录ID"
},
{
"name": "stock_id",
"type": "number",
"description": "关联的商品库存ID"
},
{
"name": "space_id",
"type": "number",
"description": "库位ID"
},
{
"name": "batch_no",
"type": "string",
"description": "批次号"
},
{
"name": "inventory_type",
"type": "string",
"description": "库存类型"
},
{
"name": "quantity",
"type": "number",
"description": "库存数量"
},
{
"name": "locked_quantity",
"type": "number",
"description": "锁定数量"
},
{
"name": "available_quantity",
"type": "number",
"description": "可用数量"
},
{
"name": "production_date",
"type": "string",
"description": "生产日期"
},
{
"name": "expiry_date",
"type": "string",
"description": "过期日期"
},
{
"name": "inbound_time",
"type": "string",
"description": "入库时间"
},
{
"name": "inbound_order_no",
"type": "string",
"description": "入库单号"
},
{
"name": "supplier_batch_no",
"type": "string",
"description": "供应商批次号"
},
{
"name": "created_at",
"type": "string",
"description": "记录创建时间"
},
{
"name": "space",
"type": "object",
"description": "库位信息子对象,含 id、space_code、custom_name"
}
]
}
}
]
},
{
"name": "total",
"type": "number",
"description": "本次返回的记录条数(≤50)"
}
],
"errors": []
}
]
},
{
"groupName": "拣货模块",
"module": "pick",
"list": [
{
"method": "pick.query",
"description": "按 keyword(运单号或波次号)获取或创建当前用户的拣货任务:命中同用户活动任务返回 existing;无活动任务则创建并返回 created;若活动任务归属他人则返回冲突提示。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "keyword",
"type": "string",
"required": true,
"source": "body",
"description": "关键字,支持运单号或波次号。"
}
],
"response": [
{
"name": "task_id",
"type": "number",
"required": true,
"description": "拣货任务ID。"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "任务状态:existing(命中当前用户已有活动任务)或 created(新建成功)。"
},
{
"name": "tip",
"type": "string",
"required": true,
"description": "提示文案。"
}
],
"errors": [
{
"code": 400,
"message": "参数错误或目标波次不满足建任务条件(如 keyword 为空、缺少仓库上下文、目标波次信息不完整、散单波次无可用订单)。"
},
{
"code": 401,
"message": "未获取到操作人上下文。"
},
{
"code": 404,
"message": "关键字未命中有效运单/波次,或命中的订单/波次不属于当前仓库。"
},
{
"code": 409,
"message": "目标波次已存在他人创建的活动任务(失败 data 含 task_id、task_owner_id、task_owner_name)。"
},
{
"code": 500,
"message": "内部错误(如分表模型不可用或任务创建异常)。"
}
]
},
{
"method": "pick.wavePickTaskDetail",
"description": "按任务ID获取拣货任务详情。查询前会校验任务内订单是否全部完成快递号与储位分配:若存在未分配快递号或未分配储位订单,将返回 400 并在 data 中返回 action 与 order_ids 供前端触发一键分配;详情响应新增中间态进度语义(task.is_completed、task.progress 与顶层 is_completed),用于前端判断是否已完成与展示阶段进度;仅允许任务的 pick_user_id 与当前登录用户一致时返回详情。当 pick_mode=1(团购小波次)时,picking_details 字段不返回以减少带宽。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id",
"type": "number",
"required": true,
"source": "body",
"description": "wms_wave_pick_task 主键 ID"
}
],
"response": [
{
"name": "task",
"type": "object",
"description": "拣货任务主表(精简字段)",
"children": [
{
"name": "task_id",
"type": "number",
"description": "任务ID",
"required": false
},
{
"name": "task_no",
"type": "string",
"description": "任务编号",
"required": false
},
{
"name": "status",
"type": "number",
"description": "任务状态",
"required": false
},
{
"name": "pick_mode",
"type": "number",
"description": "拣货模式",
"required": false
},
{
"name": "start_at",
"type": "string",
"description": "开始时间(ISO 字符串或 null)",
"required": false
},
{
"name": "finish_at",
"type": "string",
"description": "完成时间(ISO 字符串或 null)",
"required": false
},
{
"name": "batch_no",
"type": "string",
"description": "批次号",
"required": false
},
{
"name": "is_completed",
"type": "boolean",
"description": "任务是否已完成(订单维度全部已拣或任务状态已进入完成态)",
"required": false
},
{
"name": "progress",
"type": "object",
"description": "任务订单拣货进度统计",
"required": false,
"children": [
{
"name": "total_orders",
"type": "number",
"description": "任务订单总数",
"required": false
},
{
"name": "picked_orders",
"type": "number",
"description": "已确认拣货订单数",
"required": false
},
{
"name": "pending_orders",
"type": "number",
"description": "待确认拣货订单数",
"required": false
}
]
}
],
"required": false
},
{
"name": "is_completed",
"type": "boolean",
"description": "任务是否已完成(与 task.is_completed 含义一致,便于前端直接判断)",
"required": false
},
{
"name": "boxes",
"type": "array",
"description": "箱列表;包含用于前端展示与拣货进度的统计字段",
"children": [
{
"name": "task_id",
"type": "number",
"description": "任务ID",
"required": false
},
{
"name": "box_id",
"type": "number",
"description": "箱ID",
"required": false
},
{
"name": "box_no",
"type": "string",
"description": "箱编码",
"required": false
},
{
"name": "box_type",
"type": "number",
"description": "箱类型",
"required": false
},
{
"name": "status",
"type": "number",
"description": "箱状态",
"required": false
},
{
"name": "ref_label",
"type": "string",
"description": "箱参考标签或关联业务标识(用于前端定位/关联)",
"required": false
},
{
"name": "required_qty",
"type": "number",
"description": "箱内需要拣货的总数量",
"required": false
},
{
"name": "picked_qty",
"type": "number",
"description": "当前已完成拣货的数量",
"required": false
}
],
"required": false
},
{
"name": "picking_details",
"type": "array",
"description": "拣货明细列表(按库位/商品/数量拆分),用于从明细视角展示拣货要求。注意:当 pick_mode=1(团购小波次)时该字段不返回,减少带宽浪费;其他 pick_mode(2/3/4/5)正常返回。",
"children": [
{
"name": "order_id",
"type": "number",
"description": "订单ID",
"required": false
},
{
"name": "order_item_id",
"type": "number",
"description": "订单行ID",
"required": false
},
{
"name": "quantity",
"type": "number",
"description": "本行需拣货数量",
"required": false
},
{
"name": "storage_id",
"type": "number",
"description": "仓库ID",
"required": false
},
{
"name": "space_id",
"type": "number",
"description": "库位ID",
"required": false
},
{
"name": "space_name",
"type": "string",
"description": "库位名称",
"required": false
},
{
"name": "location_space",
"type": "object",
"description": "库位扩展信息(当存在时返回)",
"children": [
{
"name": "space_code",
"type": "string",
"description": "库位编码",
"required": false
},
{
"name": "custom_name",
"type": "string",
"description": "库位自定义名称",
"required": false
},
{
"name": "custom_barcode",
"type": "string",
"description": "库位自定义条码",
"required": false
},
{
"name": "pick_sequence",
"type": "number",
"description": "拣货序列,用于路线/优先级排序",
"required": false
},
{
"name": "pick_priority",
"type": "number",
"description": "拣货优先级(数值越小优先级越高)",
"required": false
}
],
"required": false
},
{
"name": "item_code",
"type": "string",
"description": "商品编码",
"required": false
},
{
"name": "item_name",
"type": "string",
"description": "商品名称",
"required": false
},
{
"name": "stock_id",
"type": "number",
"description": "库存记录ID(stock 主键)",
"required": false
},
{
"name": "plan_qty",
"type": "number",
"description": "计划拣货数量(用于与实际拣货对比)",
"required": false
},
{
"name": "item_snapshot",
"type": "object",
"description": "商品快照(下单时的商品信息,可能包含规格/属性等)",
"required": false
}
],
"required": false
},
{
"name": "picking_summary",
"type": "object",
"description": "对 picking_details 的汇总信息,用于统计与前端显示",
"children": [
{
"name": "total_lines",
"type": "number",
"description": "明细行数(picking_details.length)",
"required": false
},
{
"name": "total_qty",
"type": "number",
"description": "明细总数量(quantity 汇总)",
"required": false
},
{
"name": "distinct_spaces",
"type": "number",
"description": "涉及的不同库位数量",
"required": false
},
{
"name": "distinct_items",
"type": "number",
"description": "涉及的不同商品数量",
"required": false
}
],
"required": false
},
{
"name": "picking_view",
"type": "object",
"description": "按 pick_mode 区分的 picking_view 形态输出(五种形态);用于前端按任务类型展示聚合视图。",
"children": [
{
"name": "mode_code",
"type": "number",
"description": "拣货视图模式编码,与 task.pick_mode 对应",
"required": false
},
{
"name": "mode_name",
"type": "string",
"description": "拣货视图模式名称",
"required": false
},
{
"name": "require_box_allocations",
"type": "boolean",
"description": "当前模式是否需要箱分配;pick_mode=1/3/4 时为 true,pick_mode=2/5 时为 false",
"required": false
},
{
"name": "group_by",
"type": "string",
"description": "分组字段,示例值:\"space+item\"",
"required": false
},
{
"name": "sort_by",
"type": "array",
"description": "排序字段数组,典型为 [\"pick_sequence\",\"pick_priority\",\"space_id\",\"item_code\"]",
"required": false
},
{
"name": "items",
"type": "array",
"description": "分组后的拣货项数组(按库位+商品聚合)",
"children": [
{
"name": "space_id",
"type": "number",
"description": "库位 ID",
"required": false
},
{
"name": "space_name",
"type": "string",
"description": "库位名称",
"required": false
},
{
"name": "location_space",
"type": "object",
"description": "库位扩展信息(同 picking_details.location_space 结构)",
"children": [
{
"name": "space_code",
"type": "string",
"description": "库位编码",
"required": false
},
{
"name": "custom_name",
"type": "string",
"description": "库位自定义名称",
"required": false
},
{
"name": "custom_barcode",
"type": "string",
"description": "库位自定义条码",
"required": false
},
{
"name": "pick_sequence",
"type": "number",
"description": "拣货序列,用于路线/优先级排序",
"required": false
},
{
"name": "pick_priority",
"type": "number",
"description": "拣货优先级(数值越小优先)",
"required": false
}
],
"required": false
},
{
"name": "item_code",
"type": "string",
"description": "商品编码",
"required": false
},
{
"name": "item_name",
"type": "string",
"description": "商品名称",
"required": false
},
{
"name": "stock_id",
"type": "number",
"description": "库存记录ID(stock 主键)",
"required": false
},
{
"name": "total_qty",
"type": "number",
"description": "该库位该商品的总需拣货数量",
"required": false
},
{
"name": "box_allocations",
"type": "array",
"description": "与该库位/商品相关的箱分配列表(当 require_box_allocations=true 时返回)",
"children": [
{
"name": "box_id",
"type": "number",
"description": "箱ID",
"required": false
},
{
"name": "box_no",
"type": "string",
"description": "箱编码",
"required": false
},
{
"name": "box_type",
"type": "number",
"description": "箱类型",
"required": false
},
{
"name": "required_qty",
"type": "number",
"description": "该箱分配需要拣货的数量",
"required": false
},
{
"name": "picked_qty",
"type": "number",
"description": "该箱已完成拣货的数量",
"required": false
},
{
"name": "allocated_qty",
"type": "number",
"description": "该箱已分配的数量(由后端分配)",
"required": false
}
],
"required": false
}
],
"required": false
}
],
"required": false
}
],
"errors": [
{
"code": 400,
"message": "业务校验失败:包含 task_id 参数不合法、未分配快递号(data.action=assign_express, data.order_ids)或未分配储位(data.action=assign_storage, data.order_ids)等场景。"
},
{
"code": 401,
"message": "未获取到操作人上下文。"
},
{
"code": 403,
"message": "当前操作人与任务创建人不一致,无权查看。"
},
{
"code": 404,
"message": "拣货任务不存在。"
},
{
"code": 500,
"message": "查询失败。"
}
]
},
{
"method": "pick.wavePickTaskSubmit",
"description": "提交拣货任务中间态。用于保存阶段性数据到任务 ext_json.pick_intermediate,并在任务初始状态时自动推进到进行中。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id",
"type": "number",
"required": true,
"source": "body",
"description": "拣货任务ID"
},
{
"name": "payload",
"type": "object",
"required": false,
"source": "body",
"description": "中间态业务数据对象,将原样保存到 ext_json.pick_intermediate.payload"
}
],
"response": [
{
"name": "task_id",
"type": "number",
"required": true,
"description": "拣货任务ID"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "提交结果状态,固定为 submitted"
},
{
"name": "is_completed",
"type": "boolean",
"required": true,
"description": "当前任务是否已完成"
},
{
"name": "progress",
"type": "object",
"required": true,
"description": "任务订单拣货进度统计",
"children": [
{
"name": "total_orders",
"type": "number",
"required": true,
"description": "任务订单总数"
},
{
"name": "picked_orders",
"type": "number",
"required": true,
"description": "已确认拣货订单数"
},
{
"name": "pending_orders",
"type": "number",
"required": true,
"description": "待确认拣货订单数"
}
]
}
],
"errors": [
{
"code": 400,
"message": "参数或业务状态不满足提交条件(如 task_id 不合法、缺少仓库上下文、任务已完成/已取消)。"
},
{
"code": 401,
"message": "未获取到操作人上下文。"
},
{
"code": 403,
"message": "当前操作人与任务创建人不一致,无权操作。"
},
{
"code": 404,
"message": "拣货任务不存在。"
},
{
"code": 500,
"message": "提交失败。"
}
]
},
{
"method": "pick.wavePickTaskComplete",
"description": "完全提交拣货任务。支持 mode=1 全部确认,mode=2 部分确认(需传 order_ids)。提交后根据是否全部完成自动推进任务状态。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id",
"type": "number",
"required": true,
"source": "body",
"description": "拣货任务ID"
},
{
"name": "mode",
"type": "number",
"required": false,
"source": "body",
"description": "提交模式:1=全部确认(默认),2=部分确认"
},
{
"name": "order_ids",
"type": "array",
"required": false,
"source": "body",
"description": "部分确认模式(mode=2)时必填;仅会确认命中当前任务的订单ID"
}
],
"response": [
{
"name": "task_id",
"type": "number",
"required": true,
"description": "拣货任务ID"
},
{
"name": "mode",
"type": "number",
"required": true,
"description": "实际生效的提交模式(1=全部确认,2=部分确认)"
},
{
"name": "confirmed_order_ids",
"type": "array",
"required": true,
"description": "本次成功确认的订单ID列表"
},
{
"name": "is_completed",
"type": "boolean",
"required": true,
"description": "提交后任务是否已完成"
},
{
"name": "progress",
"type": "object",
"required": true,
"description": "任务订单拣货进度统计",
"children": [
{
"name": "total_orders",
"type": "number",
"required": true,
"description": "任务订单总数"
},
{
"name": "picked_orders",
"type": "number",
"required": true,
"description": "已确认拣货订单数"
},
{
"name": "pending_orders",
"type": "number",
"required": true,
"description": "待确认拣货订单数"
}
]
}
],
"errors": [
{
"code": 400,
"message": "参数或业务状态不满足提交条件(如 task_id 不合法、mode 非 1/2、部分确认未传 order_ids、任务下无可确认订单等)。"
},
{
"code": 401,
"message": "未获取到操作人上下文。"
},
{
"code": 403,
"message": "当前操作人与任务创建人不一致,无权操作。"
},
{
"code": 404,
"message": "拣货任务不存在。"
},
{
"code": 500,
"message": "提交失败。"
}
]
}
]
},
{
"groupName": "拣货车模块",
"module": "pickCart",
"list": [
{
"method": "pickCart.scan",
"description": "按拣货车条码/编码查询拣货车信息,供 PDA 扫码后用于拣货任务绑定。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "cart_code",
"type": "string",
"required": true,
"source": "body",
"description": "拣货车条码/编码"
}
],
"response": [
{
"name": "cart_id",
"type": "number",
"required": true,
"description": "拣货车ID"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "仓库ID"
},
{
"name": "cart_code",
"type": "string",
"required": true,
"description": "拣货车编码"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"description": "拣货车名称"
},
{
"name": "status",
"type": "number",
"required": true,
"description": "拣货车状态:0-停用 1-启用"
},
{
"name": "current_task_id",
"type": "number",
"required": false,
"description": "当前绑定任务ID,无绑定时为 null"
},
{
"name": "current_task_no",
"type": "string",
"required": false,
"description": "当前绑定任务编号,无绑定时为 null"
}
],
"errors": [
{
"code": 400,
"message": "cart_code 未传或缺少仓库上下文。"
},
{
"code": 404,
"message": "拣货车不存在。"
},
{
"code": 500,
"message": "查询失败。"
}
]
},
{
"method": "pickCart.bindTaskCart",
"description": "绑定拣货任务与拣货车。支持传 cart_id 或 cart_code;若任务已绑定其他拣货车则自动改绑,若目标拣货车已绑定其他活动任务则返回冲突。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id",
"type": "number",
"required": true,
"source": "body",
"description": "拣货任务ID"
},
{
"name": "cart_id",
"type": "number",
"required": false,
"source": "body",
"description": "拣货车ID,和 cart_code 二选一即可"
},
{
"name": "cart_code",
"type": "string",
"required": false,
"source": "body",
"description": "拣货车编码,和 cart_id 二选一即可"
}
],
"response": [
{
"name": "task_id",
"type": "number",
"required": true,
"description": "拣货任务ID"
},
{
"name": "task_no",
"type": "string",
"required": true,
"description": "拣货任务编号"
},
{
"name": "cart",
"type": "object",
"required": true,
"description": "绑定后的拣货车信息",
"children": [
{
"name": "cart_id",
"type": "number",
"description": "拣货车ID"
},
{
"name": "cart_code",
"type": "string",
"description": "拣货车编码"
},
{
"name": "cart_name",
"type": "string",
"description": "拣货车名称"
},
{
"name": "current_task_id",
"type": "number",
"description": "当前绑定任务ID"
},
{
"name": "current_task_no",
"type": "string",
"description": "当前绑定任务编号"
}
]
}
],
"errors": [
{
"code": 400,
"message": "参数不合法、任务已完成/已取消、拣货车已停用等业务校验失败。"
},
{
"code": 401,
"message": "未获取到操作人上下文。"
},
{
"code": 403,
"message": "当前操作人与任务创建人不一致,或任务不属于当前仓库。"
},
{
"code": 404,
"message": "拣货任务或拣货车不存在。"
},
{
"code": 409,
"message": "目标拣货车已绑定其他活动任务。"
},
{
"code": 500,
"message": "绑定失败。"
}
]
},
{
"method": "pickCart.create",
"description": "创建拣货车。拣货车编码在当前仓库内不可重复。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "cart_code",
"type": "string",
"required": true,
"source": "body",
"description": "拣货车编码,当前仓库内唯一"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"source": "body",
"description": "拣货车名称"
},
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "状态:0-停用 1-启用,默认 1"
}
],
"response": [
{
"name": "cart_id",
"type": "number",
"required": true,
"description": "拣货车ID"
},
{
"name": "cart_code",
"type": "string",
"required": true,
"description": "拣货车编码"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"description": "拣货车名称"
},
{
"name": "status",
"type": "number",
"required": true,
"description": "状态:0-停用 1-启用"
}
],
"errors": [
{
"code": 400,
"message": "cart_code 未传或缺少仓库上下文。"
},
{
"code": 409,
"message": "拣货车编码已存在,请勿重复。"
},
{
"code": 500,
"message": "创建失败。"
}
]
},
{
"method": "pickCart.update",
"description": "更新拣货车。支持修改编码、名称、状态;若修改后的编码与当前仓库内其他拣货车重复则拦截。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "cart_id",
"type": "number",
"required": true,
"source": "body",
"description": "拣货车ID"
},
{
"name": "cart_code",
"type": "string",
"required": false,
"source": "body",
"description": "新的拣货车编码"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"source": "body",
"description": "新的拣货车名称"
},
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "新的状态:0-停用 1-启用"
}
],
"response": [
{
"name": "cart_id",
"type": "number",
"required": true,
"description": "拣货车ID"
},
{
"name": "cart_code",
"type": "string",
"required": true,
"description": "拣货车编码"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"description": "拣货车名称"
},
{
"name": "status",
"type": "number",
"required": true,
"description": "状态:0-停用 1-启用"
}
],
"errors": [
{
"code": 400,
"message": "参数不合法,或拣货车已绑定任务不能停用。"
},
{
"code": 404,
"message": "拣货车不存在。"
},
{
"code": 409,
"message": "拣货车编码已存在,请勿重复。"
},
{
"code": 500,
"message": "更新失败。"
}
]
},
{
"method": "pickCart.delete",
"description": "删除拣货车。若拣货车当前已绑定任务或存在有效绑定记录,则不允许删除。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "cart_id",
"type": "number",
"required": true,
"source": "body",
"description": "拣货车ID"
}
],
"response": [
{
"name": "cart_id",
"type": "number",
"required": true,
"description": "被删除的拣货车ID"
},
{
"name": "deleted",
"type": "boolean",
"required": true,
"description": "是否删除成功,固定为 true"
}
],
"errors": [
{
"code": 400,
"message": "cart_id 不合法,或拣货车当前已绑定任务/存在有效绑定记录。"
},
{
"code": 404,
"message": "拣货车不存在。"
},
{
"code": 500,
"message": "删除失败。"
}
]
},
{
"method": "pickCart.detail",
"description": "查询拣货车详情。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "cart_id",
"type": "number",
"required": true,
"source": "body",
"description": "拣货车ID"
}
],
"response": [
{
"name": "cart_id",
"type": "number",
"required": true,
"description": "拣货车ID"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "仓库ID"
},
{
"name": "cart_code",
"type": "string",
"required": true,
"description": "拣货车编码"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"description": "拣货车名称"
},
{
"name": "status",
"type": "number",
"required": true,
"description": "状态:0-停用 1-启用"
},
{
"name": "current_task_id",
"type": "number",
"required": false,
"description": "当前绑定任务ID,无绑定时为 null"
},
{
"name": "current_task_no",
"type": "string",
"required": false,
"description": "当前绑定任务编号,无绑定时为 null"
}
],
"errors": [
{
"code": 400,
"message": "cart_id 不合法或缺少仓库上下文。"
},
{
"code": 404,
"message": "拣货车不存在。"
},
{
"code": 500,
"message": "查询失败。"
}
]
},
{
"method": "pickCart.list",
"description": "分页查询拣货车列表。支持按关键字、状态、当前绑定任务筛选。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page/pageSize,默认 1/20"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选条件,支持 keyword、status、current_task_id"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "拣货车列表,元素结构同 pickCart.detail 返回"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息,包含 page、pageSize、total、totalPages"
}
],
"errors": [
{
"code": 400,
"message": "缺少仓库上下文。"
},
{
"code": 500,
"message": "查询失败。"
}
]
},
{
"method": "pickCart.codeDuplicateCheck",
"description": "拣货车编码查重。支持传 exclude_cart_id 排除自身,用于编辑场景判断是否与其他车重复。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "cart_code",
"type": "string",
"required": true,
"source": "body",
"description": "待校验的拣货车编码"
},
{
"name": "exclude_cart_id",
"type": "number",
"required": false,
"source": "body",
"description": "需排除的拣货车ID,通常为当前编辑记录自身ID"
}
],
"response": [
{
"name": "duplicated",
"type": "boolean",
"required": true,
"description": "是否存在重复编码"
},
{
"name": "cart_id",
"type": "number",
"required": false,
"description": "命中的重复拣货车ID,无重复时为 null"
},
{
"name": "cart_code",
"type": "string",
"required": false,
"description": "命中的重复编码,无重复时为 null"
},
{
"name": "cart_name",
"type": "string",
"required": false,
"description": "命中的重复拣货车名称,无重复时为 null"
},
{
"name": "status",
"type": "number",
"required": false,
"description": "命中的重复拣货车状态,无重复时为 null"
}
],
"errors": [
{
"code": 400,
"message": "cart_code 未传或缺少仓库上下文。"
},
{
"code": 500,
"message": "校验失败。"
}
]
}
]
},
{
"groupName": "收货单模块",
"module": "storage_receiving",
"list": [
{
"method": "storage.receiving.getReceivingList",
"description": "storage.receiving.getReceivingList 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page/pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、status、store_id、日期区间等字段。示例:where.status={operator:eq,value:finished}; where.store_id={operator:eq,value:1001}; where.create_time_start={value:2026-03-01}。"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "收货单列表"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
},
{
"name": "summary",
"type": "object",
"required": true,
"description": "汇总信息(total_quantity、total_locked、total_available、total_items)"
}
],
"errors": [
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "storage.receiving.getReceivingDetail",
"description": "storage.receiving.getReceivingDetail 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID"
},
{
"name": "pagination",
"type": "object",
"required": true,
"source": "body",
"description": "明细分页参数,支持 page/pageSize"
}
],
"response": [
{
"name": "receiving",
"type": "object",
"required": true,
"description": "收货单详情(含 details、images、pagination)"
},
{
"name": "receiving.details",
"type": "array",
"required": false,
"description": "收货单明细列表,单条记录包含明细字段(见下文)"
},
{
"name": "receiving.details.*.space_id",
"type": "string",
"required": false,
"description": "库位展示名称(string|null)。优先取 custom_space_name,其次取 space_name。兼容说明:该字段历史上为数值库位ID,现已调整为展示名称;原始ID请使用 receiving.details.*.space_id_raw。"
},
{
"name": "receiving.details.*.space_id_raw",
"type": "number",
"required": false,
"description": "原始库位ID(number|null),用于兼容依赖旧语义(space_id=数字ID)的调用方。"
},
{
"name": "receiving.details.*.space_name",
"type": "string",
"required": false,
"description": "库位名称/编码(string|null),作为展示名称的回退来源。"
},
{
"name": "receiving.details.*.custom_space_name",
"type": "string",
"required": false,
"description": "库位自定义名称(string|null,可空)。"
},
{
"name": "receiving.details.*.box_remainder",
"type": "number",
"required": false,
"description": "箱内剩余数量/零散数量(不满箱时的件数)"
},
{
"name": "receiving.details.*.box_weight",
"type": "number",
"required": false,
"description": "实测箱重(单位与系统重量一致,如 kg)"
}
],
"errors": [
{
"code": "0",
"message": "无记录或无权访问"
},
{
"code": "500",
"message": "服务器错误"
}
]
},
{
"method": "storage.receiving.batchCancelReceiving",
"description": "storage.receiving.batchCancelReceiving 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "待作废收货单ID数组"
}
],
"response": [
{
"name": "message",
"type": "string",
"required": true,
"description": "批量作废处理结果"
}
],
"errors": [
{
"code": "0",
"description": "部分单据不存在、无权访问或状态不允许作废"
},
{
"code": "500",
"description": "服务器错误"
}
]
},
{
"method": "storage.receiving.rejectReceiving",
"description": "驳回收货单:将已完成(completed)的收货单批量恢复为收货中(receiving),记录驳回人信息和驳回理由。若任意一张收货单状态非 completed,则整批拒绝操作。驳回人信息(reviewer_name、reviewer_employee_id)自动取当前登录用户上下文,无需传入.",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "收货单ID数组,所有收货单必须属于当前仓库且状态为 completed,否则整批拒绝"
},
{
"name": "remark",
"type": "string",
"required": false,
"source": "body",
"description": "驳回理由,覆盖收货单原备注字段;不传则保留原备注"
}
],
"response": [
{
"name": "count",
"type": "number",
"description": "成功驳回的收货单数量"
}
],
"errors": [
{
"code": "0",
"description": "ids 为空、部分单据不存在/无权访问,或存在非 completed 状态的收货单"
},
{
"code": "500",
"description": "服务器错误"
}
]
},
{
"method": "storage.receiving.reviewReceiving",
"description": "批量审核收货单:校验所有单据满足条件(收货完成、全部匹配、未入库、已绑定货主、未审核)后统一审核,任意一张不符合则整批失败回滚。审核人信息自动取当前登录用户上下文,无需传入.",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array",
"required": true,
"source": "body",
"description": "收货单ID数组,所有单据必须满足:status=completed、detail_status=all_matched、storage_status=none、store_id 已绑定、is_review=0,否则整批拒绝"
}
],
"response": [
{
"name": "count",
"type": "number",
"description": "成功审核的收货单数量"
}
],
"errors": [
{
"code": "0",
"description": "ids 为空、单据不存在/无权访问,或不满足审核条件(含并发冲突)"
},
{
"code": "500",
"description": "服务器错误,事务已回滚"
}
]
},
{
"method": "storage.receiving.create",
"description": "storage.receiving.create 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "delivery_method",
"type": "string",
"required": true,
"source": "body",
"description": "到货方式:truck/express/air_freight/sea_freight/other"
},
{
"name": "loading_method",
"type": "string",
"required": true,
"source": "body",
"description": "装卸方式:with_pallet/without_pallet"
},
{
"name": "license_plate",
"type": "string",
"required": false,
"source": "body",
"description": "车牌号(delivery_method=truck 时建议传)"
},
{
"name": "tracking_number",
"type": "string",
"required": false,
"source": "body",
"description": "物流单号(非 truck/other 场景建议传)"
},
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID"
},
{
"name": "total_boxes",
"type": "number",
"required": false,
"source": "body",
"description": "总箱数"
},
{
"name": "total_pallets",
"type": "number",
"required": false,
"source": "body",
"description": "总托盘数"
},
{
"name": "remark",
"type": "string",
"required": false,
"source": "body",
"description": "备注"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "新建收货单ID"
},
{
"name": "receiving_number",
"type": "string",
"required": true,
"description": "收货单号"
}
],
"errors": [
{
"code": "0",
"description": "创建失败(如字段枚举不合法、数据库约束异常)"
}
]
},
{
"method": "storage.receiving.bindStore",
"description": "收货单绑定货主",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID"
},
{
"name": "store_id",
"type": "number",
"required": true,
"source": "body",
"description": "货主ID(必须与当前仓库存在有效签约关系)"
}
],
"response": [
{
"name": "data.id",
"type": "number",
"required": true,
"description": "收货单ID"
},
{
"name": "data.store_id",
"type": "number",
"required": true,
"description": "已绑定的货主ID"
},
{
"name": "data.store_name",
"type": "string",
"required": false,
"description": "货主名称/签约备注名"
},
{
"name": "data.status",
"type": "string",
"required": true,
"description": "当前收货单状态"
}
],
"errors": [
{
"code": "400",
"description": "用户未绑定仓库、收货单ID/货主ID为空、已取消或已绑定货主"
},
{
"code": "404",
"description": "收货单不存在/无权访问,或货主与当前仓库未建立有效签约关系"
},
{
"code": "500",
"description": "绑定货主失败"
}
]
},
{
"method": "storage.receiving.bindDetailProduct",
"description": "收货单明细绑定或改绑系统商品",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "detail_id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单明细ID(兼容字段 `id`)"
},
{
"name": "system_product_id",
"type": "number",
"required": true,
"source": "body",
"description": "系统商品ID(`StockWarehouse.id`,且必须属于当前仓库)"
}
],
"response": [
{
"name": "data.detail_id",
"type": "number",
"required": true,
"description": "收货单明细ID"
},
{
"name": "data.receiving_id",
"type": "number",
"required": true,
"description": "收货单ID"
},
{
"name": "data.system_product_id",
"type": "number",
"required": true,
"description": "已绑定的系统商品ID"
},
{
"name": "data.product_name",
"type": "string",
"required": true,
"description": "自动回填的商品名称"
}
],
"errors": [
{
"code": "400",
"description": "用户未绑定仓库、明细ID/商品ID为空,收货单状态不允许绑定/改绑,或收货单已审核禁止绑定/改绑"
},
{
"code": "404",
"description": "收货单明细不存在,或商品不存在/不属于当前仓库"
},
{
"code": "500",
"description": "绑定商品失败"
}
]
},
{
"method": "storage.receiving.queryReceivingLogs",
"description": "按收货单ID查询操作日志列表(分页),仅返回当前仓库上下文数据",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number|string",
"required": false,
"source": "body",
"description": "收货单ID(与 receiving_id 二选一)"
},
{
"name": "receiving_id",
"type": "number|string",
"required": false,
"source": "body",
"description": "收货单ID(兼容字段,与 id 二选一)"
},
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码(兼容顶层分页入参)"
},
{
"name": "pageSize",
"type": "number",
"required": false,
"source": "body",
"description": "每页数量(兼容顶层分页入参)"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "日志列表"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息,包含 page、pageSize、total、totalPages"
}
],
"errors": [
{
"code": "400",
"description": "收货单ID为空或仓库上下文缺失"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "storage.receiving.removeItem",
"description": "storage.receiving.removeItem 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "id 参数"
},
{
"name": "item_id",
"type": "number",
"required": false,
"source": "body",
"description": "item_id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "storage.receiving.save",
"description": "修改收货单基础信息。按收货单ID更新当前仓库下收货单的基础字段。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID,按该ID修改当前仓库下的收货单"
},
{
"name": "delivery_method",
"type": "string",
"required": false,
"source": "body",
"description": "到货方式:truck/express/air_freight/sea_freight/other;不传则保持原值"
},
{
"name": "loading_method",
"type": "string",
"required": false,
"source": "body",
"description": "装卸方式:with_pallet/without_pallet;不传则保持原值"
},
{
"name": "license_plate",
"type": "string",
"required": false,
"source": "body",
"description": "车牌号;当 delivery_method=truck 时可更新,其他到货方式会被清空或忽略"
},
{
"name": "tracking_number",
"type": "string",
"required": false,
"source": "body",
"description": "物流单号;当 delivery_method 为 express/air_freight/sea_freight 时可更新,truck/other 场景会被清空或忽略"
},
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID;若传入,会校验当前仓库下签约关系并同步更新货主名称;传 0/null 可清空货主"
},
{
"name": "total_boxes",
"type": "number",
"required": false,
"source": "body",
"description": "总箱数,默认 0"
},
{
"name": "total_pallets",
"type": "number",
"required": false,
"source": "body",
"description": "总托盘数,默认 0"
},
{
"name": "remark",
"type": "string",
"required": false,
"source": "body",
"description": "备注信息"
},
{
"name": "status",
"type": "string",
"required": false,
"source": "body",
"description": "收货单状态;不传则保持原值"
},
{
"name": "video_device_id",
"type": "string",
"required": false,
"source": "body",
"description": "录像设备ID"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码;200 表示修改成功"
},
{
"name": "id",
"type": "number",
"required": true,
"description": "修改的收货单ID"
},
{
"name": "receiving_number",
"type": "string",
"required": true,
"description": "收货单号"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "结果描述;成功时通常为收货单修改成功"
}
],
"errors": [
{
"code": "400",
"description": "收货单ID不能为空、已取消的收货单不允许修改或用户未绑定仓库"
},
{
"code": "404",
"description": "收货单不存在/无权访问,或指定货主不存在/未与当前仓库建立有效签约关系"
},
{
"code": "0",
"description": "修改失败,如字段枚举不合法或数据库写入异常"
}
]
},
{
"method": "storage.receiving.get",
"description": "storage.receiving.get 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID"
}
],
"response": [
{
"name": "code",
"type": "number",
"description": "业务状态码,200 表示成功"
},
{
"name": "message",
"type": "string",
"description": "返回信息"
},
{
"name": "data",
"type": "object",
"description": "收货单详情对象,包含 details(明细数组)、images 及主表字段"
},
{
"name": "data.details",
"type": "array",
"description": "收货单明细数组(每项为明细对象)"
},
{
"name": "data.details.*.box_remainder",
"type": "number",
"required": false,
"description": "箱内剩余数量/零散数量(不满箱时的件数),默认 0"
},
{
"name": "data.details.*.box_weight",
"type": "number",
"required": false,
"description": "实测箱重(单位与系统重量一致,如 kg),默认 0"
}
],
"errors": []
},
{
"method": "storage.receiving.addDetail",
"description": "支持新增可选入参 item;item 有值时按传入字段创建明细(服务端会覆盖 receiving_id 与 creator_id);item 无值时沿原链路创建空白明细。返回的 selectId 与 data.details 语义不变(仍返回新创建明细的 selectId 与更新后的明细列表)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "receiving_id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID"
},
{
"name": "item",
"type": "object",
"required": false,
"source": "body",
"description": "可选:按传入字段创建明细;不传则创建空白明细。item.children 需覆盖以下字段(有则写、无则补齐):actual_quantity, box_quantity, boxes_per_pallet, space_id, system_product_id, box_width, box_height, box_length, box_remainder, box_weight, weight, barcode, product_name, pallet_quantity, receiving_time, production_date, expiry_date, remark, batch_number, product_snapshot。若传入 item,服务端仍会覆盖 receiving_id 与 creator_id。",
"children": [
{
"name": "actual_quantity",
"type": "number",
"description": "实收数量"
},
{
"name": "box_quantity",
"type": "number",
"description": "箱数量"
},
{
"name": "boxes_per_pallet",
"type": "number",
"description": "每托盘箱数"
},
{
"name": "space_id",
"type": "number",
"description": "库位 ID"
},
{
"name": "system_product_id",
"type": "number",
"description": "系统商品 ID"
},
{
"name": "box_width",
"type": "number",
"description": "箱宽(单位同系统)"
},
{
"name": "box_height",
"type": "number",
"description": "箱高"
},
{
"name": "box_length",
"type": "number",
"description": "箱长"
},
{
"name": "box_remainder",
"type": "number",
"description": "箱内剩余数量/零散数量"
},
{
"name": "box_weight",
"type": "number",
"description": "箱重"
},
{
"name": "weight",
"type": "number",
"description": "商品重量"
},
{
"name": "barcode",
"type": "string",
"description": "商品条码"
},
{
"name": "product_name",
"type": "string",
"description": "商品名称"
},
{
"name": "pallet_quantity",
"type": "number",
"description": "托盘数量"
},
{
"name": "receiving_time",
"type": "string",
"description": "收货时间(ISO 字符串)"
},
{
"name": "production_date",
"type": "string",
"description": "生产日期(ISO 或 YYYY-MM-DD)"
},
{
"name": "expiry_date",
"type": "string",
"description": "有效期/失效日期(ISO 或 YYYY-MM-DD)"
},
{
"name": "remark",
"type": "string",
"description": "备注"
},
{
"name": "batch_number",
"type": "string",
"description": "批次号"
},
{
"name": "product_snapshot",
"type": "object",
"description": "商品快照,具体结构以实现为准"
}
]
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,200 表示添加成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "结果描述,成功时为 '添加成功'"
},
{
"name": "data.details",
"type": "array",
"required": true,
"description": "收货单明细数组(每项为明细对象)"
},
{
"name": "data.selectId",
"type": "number",
"required": true,
"description": "新创建的明细ID,用于前端选中"
}
],
"errors": [
{
"code": "400",
"description": "收货单状态不允许添加明细"
},
{
"code": "404",
"description": "收货单不存在"
},
{
"code": "500",
"description": "服务器错误或添加失败(数据库写入异常等)"
}
]
},
{
"method": "storage.receiving.deleteDetail",
"description": "删除收货单明细并回算统计。仅允许明细创建者在收货中状态删除未入库的明细;服务端从登录用户上下文获取 creator_id(ctx.user.employees_id)与 warehouse_id(ctx.user.store_id)。若关联收货单状态为 completed(已完成)或 cancelled(已取消),接口会返回删除失败(400),不允许删除明细。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "detail_id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单明细 ID(必填)"
}
],
"response": [
{
"name": "code",
"type": "number",
"description": "业务状态码,200 表示成功,400/404/500 表示失败"
},
{
"name": "message",
"type": "string",
"description": "简短的错误或成功信息"
},
{
"name": "data",
"type": "object",
"description": "成功时返回的结果对象"
},
{
"name": "data.details",
"type": "array",
"description": "删除后收货单剩余的明细数组。每项字段与 storage.receiving.getReceivingDetail 返回的明细项一致;product_snapshot 为解析后的对象或 null"
},
{
"name": "data.selectId",
"type": "number|null",
"description": "删除后建议前端选中的明细 ID;无剩余明细时为 null"
}
],
"errors": [
{
"code": "404",
"description": "明细不存在(或非创建者/仓库无权访问)"
},
{
"code": "400",
"description": "收货单已完成或已取消,禁止删除明细;或该明细已入库或已被占用,删除失败"
},
{
"code": "500",
"description": "服务器内部错误或删除异常(含数据库写入/事务异常)"
}
]
},
{
"method": "storage.receiving.detailChange",
"description": "修改收货单明细(数量/箱规/批次/商品信息回写等)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "收货明细ID"
},
{
"name": "receiving_id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID"
},
{
"name": "actual_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "实际收货数量"
},
{
"name": "batch_number",
"type": "string",
"required": false,
"source": "body",
"description": "批次号"
},
{
"name": "production_date",
"type": "string",
"required": false,
"source": "body",
"description": "生产日期(可解析的日期字符串)"
},
{
"name": "expiry_date",
"type": "string",
"required": false,
"source": "body",
"description": "到期日期(可解析的日期字符串)。若早于当前日期,接口会返回 400 并拒绝录入。"
},
{
"name": "box_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "箱数"
},
{
"name": "boxes_per_pallet",
"type": "number",
"required": false,
"source": "body",
"description": "每托盘箱数"
},
{
"name": "pallet_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "托盘数"
},
{
"name": "space_id",
"type": "number",
"required": false,
"source": "body",
"description": "库位 ID(可回写)"
},
{
"name": "remark",
"type": "string",
"required": false,
"source": "body",
"description": "备注"
},
{
"name": "system_product_id",
"type": "number",
"required": false,
"source": "body",
"description": "系统商品 ID(StockWarehouse.id)。若提供,服务端会尝试回填 barcode/weight/箱规/product_name/product_snapshot 等。"
},
{
"name": "barcode",
"type": "string",
"required": false,
"source": "body",
"description": "条码(未传 system_product_id 时可单独更新)"
},
{
"name": "product_name",
"type": "string",
"required": false,
"source": "body",
"description": "商品名称(未传 system_product_id 时可单独更新)"
},
{
"name": "box_width",
"type": "number",
"required": false,
"source": "body",
"description": "箱宽"
},
{
"name": "box_height",
"type": "number",
"required": false,
"source": "body",
"description": "箱高"
},
{
"name": "box_length",
"type": "number",
"required": false,
"source": "body",
"description": "箱长"
},
{
"name": "box_remainder",
"type": "number",
"required": false,
"source": "body",
"description": "箱内剩余数量/零散数量(不满箱时的件数)"
},
{
"name": "box_weight",
"type": "number",
"required": false,
"source": "body",
"description": "实测箱重(单位与系统重量一致,如 kg)"
},
{
"name": "weight",
"type": "number",
"required": false,
"source": "body",
"description": "毛重/重量"
}
],
"response": [
{
"name": "data.id",
"type": "number",
"required": true,
"description": "收货明细 ID"
},
{
"name": "data.receiving_id",
"type": "number",
"required": true,
"description": "收货单 ID"
},
{
"name": "data.actual_quantity",
"type": "number",
"required": false,
"description": "实际收货数量"
},
{
"name": "data.product_name",
"type": "string",
"required": false,
"description": "商品名称"
},
{
"name": "data.barcode",
"type": "string",
"required": false,
"description": "条码"
},
{
"name": "data.system_product_id",
"type": "number",
"required": false,
"description": "系统商品 ID"
},
{
"name": "data.box_remainder",
"type": "number",
"required": false,
"description": "箱内剩余数量/零散数量(不满箱时的件数)"
},
{
"name": "data.box_weight",
"type": "number",
"required": false,
"description": "实测箱重(单位与系统重量一致,如 kg)"
},
{
"name": "data.updated_at",
"type": "string",
"required": false,
"description": "记录更新时间(ISO)"
}
],
"errors": [
{
"code": "400",
"description": "收货明细ID不能为空 / 收货单ID不能为空 / 到期日期已过期,不能录入收货 / 箱数/托盘数不能为负数等参数校验失败"
},
{
"code": "404",
"description": "收货明细不存在或无权访问"
},
{
"code": "500",
"description": "服务器错误或修改失败"
}
]
},
{
"method": "storage.receiving.cancel",
"description": "storage.receiving.cancel 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "storage.receiving.completeReceiving",
"description": "storage.receiving.completeReceiving 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"notes": [
"完成收货时会发送通知:通知 payload 或 metadata 将在每条明细中携带 box_remainder(箱内剩余数量/零散件数,number)与 box_weight(实测箱重,number,单位同系统重量,例如 kg)。新增字段为可选,旧客户端可忽略。"
],
"errors": []
}
]
},
{
"groupName": "入库单模块",
"module": "storage.entry",
"list": [
{
"method": "storage.entry.list",
"description": "入库单列表查询",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page/pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status、store_id、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in;值会归一化为 0/1,兼容 true/false、1/0、y/n、yes/no(大小写不敏感,含布尔/字符串/数字写法)。示例:where.expense_record={operator:eq,value:true} 等价 where.expense_record={operator:eq,value:1};where.expense_record={operator:in,value:[true,\"0\",\"yes\",\"n\"]} 会归一化为 [1,0]。若部署环境尚未完成 expense_record 字段迁移,传入该筛选可能返回 400,错误提示为“当前环境未提供 expense_record 字段,暂不支持该筛选条件,请先完成表结构升级”。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField/sortOrder"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "入库单列表"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
},
{
"name": "summary",
"type": "object",
"required": true,
"description": "状态汇总(total、pending、creating、created、completed、cancelled)"
}
],
"errors": [
{
"code": "400",
"message": "筛选条件格式错误",
"description": "筛选条件格式错误"
},
{
"code": "500",
"message": "查询失败",
"description": "查询失败"
}
]
},
{
"method": "storage.entry.get",
"description": "查询入库单详情",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "入库单ID,与 entry_order_code 二选一"
},
{
"name": "entry_order_code",
"type": "string",
"required": false,
"source": "body",
"description": "入库单号,与 id 二选一"
}
],
"response": [
{
"name": "entryOrder",
"type": "object",
"required": true,
"description": "入库单详情(含 items 明细)"
}
],
"errors": [
{
"code": "400",
"description": "id 与 entry_order_code 均未传"
},
{
"code": "0",
"description": "无记录或无权访问"
}
]
},
{
"method": "storage.entry.cancel",
"description": "作废入库单(支持单条或批量作废)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "入库单ID,兼容旧调用;与 `ids` 二选一。若同时传入 `ids`,以 `ids` 为准。"
},
{
"name": "ids",
"type": "array",
"required": false,
"source": "body",
"description": "入库单ID数组(number[]),用于批量作废;必须为非空数组,建议批量操作使用 `ids`,优先于 `id`。"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": false,
"description": "单条作废时返回的入库单ID"
},
{
"name": "ids",
"type": "array",
"required": false,
"description": "批量作废时返回的已成功作废入库单ID数组(number[])"
}
],
"errors": [
{
"code": "400",
"description": "参数错误/参数不合法:需传入非空的 `id` 或 `ids`;`ids` 必须为数字数组且不得包含非法或重复值"
},
{
"code": "404",
"description": "入库单不存在或无权访问"
}
]
},
{
"method": "storage.entry.completeEntry",
"description": "完成入库单",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "入库单ID"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "完成成功的入库单ID"
}
],
"errors": [
{
"code": "400",
"description": "参数不合法、已作废或缺少明细"
},
{
"code": "404",
"description": "入库单不存在或无权访问"
}
]
}
]
},
{
"groupName": "出库单模块",
"module": "storage.stockout",
"list": [
{
"method": "storage.stockout.list",
"name": "出库单列表",
"description": "非订单出库单能力(对应奇门 stockout.create):用于处理由奇门创建的非订单出库单;主出口为 storage.stockout.*,不再推荐通过 storage.delivery.* 命名使用。storage.delivery.* 仅保留兼容转发。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page/pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;常用字段包括 delivery_order_code、status、outbound_status、buyer_nick、mobile 与日期区间字段。"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数,支持 sortField/sortOrder,默认按 updated_at DESC、id DESC"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "出库单列表"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
}
],
"errors": [
{
"code": "400",
"description": "筛选条件格式错误"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "storage.stockout.toOrder",
"name": "出库单转订单(占位)",
"description": "占位接口,暂未开放。当前仅保留方法名用于后续扩展,逻辑暂不能使用。参数 id / delivery_order_code 暂未启用。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "预留参数,暂未启用;当前仅保留字段名用于后续扩展。"
},
{
"name": "delivery_order_code",
"type": "string",
"required": false,
"source": "body",
"description": "预留参数,暂未启用;当前仅保留字段名用于后续扩展。"
}
],
"response": [
{
"name": "_note",
"type": "string",
"required": false,
"description": "占位接口,当前无有效业务响应"
}
],
"errors": [
{
"code": "405",
"description": "占位接口,暂未开放"
}
]
},
{
"method": "storage.stockout.listItems",
"name": "出库单拉取明细",
"description": "按出库单查询商品明细(用于非订单出库单),底层复用 order.listItems。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "delivery_order_code",
"type": "string",
"required": false,
"source": "body",
"description": "出库单号,可用于定位订单"
},
{
"name": "order_id",
"type": "number",
"required": false,
"source": "body",
"description": "订单ID,可与 id 兼容用于定位订单"
},
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "订单ID,可选;与 delivery_order_code / order_id 至少传一个"
}
],
"response": [
{
"name": "order",
"type": "object",
"required": true,
"description": "订单基础信息(含 id、delivery_order_code)"
},
{
"name": "items",
"type": "array",
"required": true,
"description": "出库单商品明细"
}
],
"errors": [
{
"code": "404",
"description": "订单不存在"
},
{
"code": "500",
"description": "缺少定位参数或查询失败"
}
]
}
]
},
{
"groupName": "库存操作模块",
"module": "storage.inventory",
"list": [
{
"method": "storage.inventory.quickPutaway",
"description": "收货单快捷入库上架。从收货单直接生成入库单并写入库存表,要求收货单已完成、已审核、货主已开启快捷入库策略且所有明细已匹配系统商品",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{
"name": "receiving_id",
"type": "number",
"required": true,
"source": "body",
"description": "收货单ID,兼容 id"
}
],
"response": {
"receiving_id": "收货单ID",
"receiving_number": "收货单号",
"receiving_storage_status": "收货单入库状态(all/partial)",
"entry_order": {
"id": "自动创建的入库单ID",
"entry_order_code": "入库单号",
"order_status": "COMPLETED"
},
"items": [
{
"detail_id": "收货明细ID",
"product_name": "商品名称",
"stock_warehouse_id": "库存商品ID",
"inbound_quantity": "入库数量",
"space_id": "库位ID",
"storage_status": "明细入库状态"
}
]
},
"errors": [
{
"code": 400,
"message": "receiving_id 必填"
},
{
"code": 400,
"message": "收货单状态须为已完成"
},
{
"code": 400,
"message": "收货单未审核,审核通过后才能入库"
},
{
"code": 400,
"message": "货主xxxx不允许快速上架,如需开启请到:货主->策略配置调整"
},
{
"code": 400,
"message": "商品未匹配系统商品"
},
{
"code": 404,
"message": "收货单绑定的货主与当前仓库不存在有效签约关系"
},
{
"code": 400,
"message": "已全部入库无需重复操作"
},
{
"code": 404,
"message": "收货单不存在或无权访问"
},
{
"code": 409,
"message": "库存记录被锁定(行锁超时)"
}
]
},
{
"method": "storage.inventory.matchPutaway",
"description": "收货单与入库单匹配入库。接收多个收货单和入库单,按商品(stock_warehouse_id)进行数量匹配入库,要求收货单已完成且已审核,完成后根据入库单来源(QM/API)自动触发回传",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{
"name": "receiving_ids",
"type": "array",
"required": true,
"source": "body",
"description": "收货单ID列表"
},
{
"name": "entry_order_ids",
"type": "array",
"required": true,
"source": "body",
"description": "入库单ID列表"
}
],
"response": {
"summary": {
"total_products_matched": "匹配的商品种类数",
"total_quantity_inbound": "入库总数量"
},
"receiving_results": [
{
"receiving_id": "收货单ID",
"storage_status": "入库状态(all/partial/none)"
}
],
"entry_order_results": [
{
"entry_order_id": "入库单ID",
"order_status": "入库单状态(COMPLETED 等)",
"callback_triggered": "是否触发回传(boolean)",
"callback_result": "回传结果对象"
}
],
"warnings": "匹配过程中的警告信息列表"
},
"errors": [
{
"code": 400,
"message": "receiving_ids 必填且为数组"
},
{
"code": 400,
"message": "entry_order_ids 必填且为数组"
},
{
"code": 404,
"message": "收货单不存在或无权访问"
},
{
"code": 400,
"message": "收货单未审核,审核通过后才能入库"
},
{
"code": 404,
"message": "入库单不存在或无权访问"
}
]
},
{
"method": "storage.inventory.transferLocation",
"description": "单商品单库位移库,将库存从一个库位移动到另一个库位,支持部分数量移库和全量移库",
"name": "库存移库(库位转移)",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{
"name": "storage_id",
"type": "number",
"required": true,
"source": "body",
"description": "库存记录ID"
},
{
"name": "target_space_id",
"type": "number",
"required": true,
"source": "body",
"description": "目标库位ID"
},
{
"name": "quantity",
"type": "number",
"required": false,
"source": "body",
"description": "移库数量,不传则全部移动"
}
],
"response": {
"storage_id": "原库存记录ID",
"target_space_id": "目标库位ID",
"quantity": "实际移库数量",
"success": "是否成功(boolean)",
"message": "结果说明"
},
"errors": [
{
"code": 400,
"message": "storage_id 必填"
},
{
"code": 400,
"message": "target_space_id 必填"
},
{
"code": 400,
"message": "移库数量必须大于0且不超过可用库存"
},
{
"code": 400,
"message": "目标库位与原库位相同"
},
{
"code": 404,
"message": "库存记录不存在或无权访问"
},
{
"code": 404,
"message": "目标库位不存在或不属于该仓库"
}
]
},
{
"method": "storage.inventory.transferByProduct",
"description": "按库位+商品维度移库,自动查找原库位下该商品的所有库存记录并合并移动。不适用于开启批次管理的商品",
"name": "按商品移库(库位转移)",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{
"name": "space_id",
"type": "number",
"required": true,
"source": "body",
"description": "原库位ID"
},
{
"name": "stock_id",
"type": "number",
"required": true,
"source": "body",
"description": "商品SKU ID(wms_stock_warehouse.id)"
},
{
"name": "target_space_id",
"type": "number",
"required": true,
"source": "body",
"description": "目标库位ID"
},
{
"name": "quantity",
"type": "number",
"required": true,
"source": "body",
"description": "移库数量"
}
]
},
{
"method": "storage.inventory.list",
"description": "库存列表查询(查 wms_storage),支持 where 条件、分页、排序、批次分组。默认按库位+商品合并数量(合并模式),group_by_batch=true 时返回每条库存明细(明细模式)",
"name": "库存列表",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"params": [
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象,可用字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数 { page, pageSize },默认 page=1, pageSize=20"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数 { sortField, sortOrder },默认 sortField='created_at', sortOrder='DESC'"
},
{
"name": "group_by_batch",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否按批次查询,默认 false。false=合并模式(按库位+商品聚合quantity/locked_quantity/available_quantity),true=明细模式(逐条返回含 batch_no/production_date/expiry_date 等)"
}
],
"response": {
"_note": "响应结构因 group_by_batch 而异",
"_shelf_life_note": "production_date 和 expiry_date 为库存批次日期字段;is_shelf_life_warning_triggered 表示该库存在商品启用保质期管理且剩余天数小于等于阈值时是否触发效期预警。",
"list_merged": {
"_description": "group_by_batch=false(默认合并模式)",
"list": [
{
"stock_id": "商品库存ID",
"space_id": "库位ID",
"inventory_type": "库存类型",
"warehouse_id": "仓库ID",
"store_id": "货主ID",
"quantity": "总库存数量(SUM)",
"locked_quantity": "总锁定数量(SUM)",
"available_quantity": "总可用数量(SUM)",
"first_inbound_time": "最早入库时间",
"last_inbound_time": "最晚入库时间",
"batch_count": "批次数",
"production_date": "生产日期(库存批次日期字段,合并模式下可能为 null)",
"expiry_date": "过期日期(库存批次日期字段,合并模式下可能为 null)",
"is_shelf_life_warning_triggered": "布尔,表示效期预警是否触发(仅在商品启用保质期管理且剩余天数 ≤ 阈值时为 true)",
"stock": {
"id": "商品ID",
"item_code": "商品编码",
"item_name": "商品名称",
"sku_property": "规格",
"stock_unit": "单位",
"store_name": "货主名称(来源于签约表 store_remask,若无签约关系则为 null)"
},
"space": {
"id": "库位ID",
"space_code": "库位编码",
"custom_name": "库位名称"
}
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
},
"list_detail": {
"_description": "group_by_batch=true(明细模式)",
"list": [
{
"id": "库存记录ID",
"warehouse_id": "仓库ID",
"store_id": "货主ID",
"space_id": "库位ID",
"stock_id": "商品库存ID",
"batch_no": "批次号",
"inventory_type": "库存类型",
"quantity": "库存数量",
"locked_quantity": "锁定数量",
"available_quantity": "可用数量",
"production_date": "生产日期(库存批次日期字段)",
"expiry_date": "过期日期(库存批次日期字段)",
"inbound_time": "入库时间",
"inbound_order_no": "入库单号",
"receiving_id": "收货单ID",
"entry_order_id": "入库单ID",
"supplier_batch_no": "供应商批次号",
"created_at": "创建时间",
"updated_at": "更新时间",
"is_shelf_life_warning_triggered": "布尔,表示效期预警是否触发(仅在商品启用保质期管理且剩余天数 ≤ 阈值时为 true)",
"stock": {
"id": "商品ID",
"item_code": "商品编码",
"item_name": "商品名称",
"sku_property": "规格",
"stock_unit": "单位",
"store_name": "货主名称(来源于签约表 store_remask,若无签约关系则为 null)"
},
"space": {
"id": "库位ID",
"space_code": "库位编码",
"custom_name": "库位名称"
}
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
}
},
{
"method": "storage.expiry.list",
"description": "库存有效期列表查询(效期预警),按 wms_storage 查询并计算剩余天数与过期状态,支持 where 条件与分页。注意:无需传 warehouse_id/store_id,服务端会从当前登录用户取仓库上下文。",
"name": "库存有效期列表(或:库存效期预警列表)",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"params": [
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象;支持字段:item_code、goods_code、item_name、sku_property、stock_unit、is_shelf_life_mgmt、remaining_threshold_days。示例:where.item_code={operator:like,value:ABC}; where.remaining_threshold_days={operator:lte,value:7}。注意:无需传入 store_id 或 warehouse_id,服务端会从当前登录用户获取仓库上下文。"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数 { page, pageSize },默认 page=1, pageSize=20"
}
],
"response": [
{
"name": "data.list",
"type": "array",
"required": true,
"description": "匹配到的库存效期项数组"
},
{
"name": "data.list[]",
"type": "object",
"description": "列表项,包含至少以下字段",
"children": [
{
"name": "id",
"type": "number",
"description": "库存记录ID(wms_storage.id)"
},
{
"name": "warehouse_id",
"type": "number",
"description": "仓库ID"
},
{
"name": "store_id",
"type": "number",
"description": "货主ID"
},
{
"name": "space_id",
"type": "number",
"description": "库位ID"
},
{
"name": "stock_id",
"type": "number",
"description": "商品库存ID(stock_warehouse.id)"
},
{
"name": "batch_no",
"type": "string",
"description": "批次号"
},
{
"name": "quantity",
"type": "number",
"description": "库存数量"
},
{
"name": "expiry_date",
"type": "string",
"description": "过期/到期日期(ISO)"
},
{
"name": "remaining_days",
"type": "number",
"description": "距到期剩余天数(正数表示未过期,0 当日到期,负数表示已过期)"
},
{
"name": "threshold_days",
"type": "number",
"description": "阈值天数,优先使用传入 remaining_threshold_days,否则使用商品配置"
},
{
"name": "is_expired",
"type": "boolean",
"description": "是否已过期(true=已过期)"
},
{
"name": "stock",
"type": "object",
"description": "关联商品信息(id、item_code、item_name、sku_property、stock_unit 等)"
},
{
"name": "space",
"type": "object",
"description": "关联库位信息(id、space_code、custom_name 等)"
},
{
"name": "created_at",
"type": "string",
"description": "记录创建时间"
},
{
"name": "updated_at",
"type": "string",
"description": "记录更新时间"
},
{
"name": "inbound_time",
"type": "string",
"description": "入库时间"
},
{
"name": "production_date",
"type": "string",
"description": "生产日期"
}
]
},
{
"name": "data.pagination",
"type": "object",
"required": true,
"description": "分页信息,含 page、pageSize、total、totalPages"
}
],
"errors": [
{
"code": 400,
"message": "where 条件格式不正确"
}
]
},
{
"method": "storage.transaction.list",
"description": "出入库记录列表查询,支持 where 条件、分页、排序、批次分组切换。默认按库位合并数量(合并模式),group_by_batch=true 时返回每条明细(明细模式)",
"name": "出入库流水记录列表",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
"params": [
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象,可用字段:transaction_type(ENUM INBOUND/OUTBOUND)、stock_id、space_id、store_id、order_type(SCRK/MATCH)、order_no、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、operator_name、created_at(支持 between)"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数 { page, pageSize },默认 page=1, pageSize=20"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数 { sortField, sortOrder },默认 sortField='created_at', sortOrder='DESC'"
},
{
"name": "group_by_batch",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否按批次查询明细,默认 false。false=合并模式(按库位+商品聚合),true=明细模式(逐条返回)"
}
],
"response": {
"_note": "响应结构因 group_by_batch 而异",
"list_merged": {
"_description": "group_by_batch=false(默认合并模式)",
"list": [
{
"stock_id": "商品库存ID",
"space_id": "库位ID",
"transaction_type": "INBOUND/OUTBOUND",
"inventory_type": "库存类型",
"warehouse_id": "仓库ID",
"store_id": "货主ID",
"order_type": "关联单据类型",
"quantity": "合计数量",
"first_created_at": "最早记录时间",
"last_created_at": "最晚记录时间",
"record_count": "合并记录条数",
"stockItem": {
"id": "商品ID",
"item_code": "商品编码",
"item_name": "商品名称",
"sku_property": "规格",
"stock_unit": "单位"
}
}
],
"pagination": {
"page": "当前页",
"pageSize": "每页条数",
"total": "总记录数",
"totalPages": "总页数"
}
},
"list_detail": {
"_description": "group_by_batch=true(明细模式)",
"list": [
{
"id": "记录ID",
"transaction_type": "INBOUND/OUTBOUND",
"warehouse_id": "仓库ID",
"store_id": "货主ID",
"stock_id": "商品库存ID",
"storage_id": "库存记录ID",
"space_id": "库位ID",
"quantity": "数量",
"batch_no": "批次号",
"inventory_type": "库存类型",
"order_type": "关联单据类型",
"order_no": "关联单据号",
"order_id": "关联单据ID",
"receiving_id": "收货单ID",
"entry_order_id": "入库单ID",
"operator_id": "操作人ID",
"operator_name": "操作人姓名",
"remark": "备注",
"created_at": "创建时间",
"stockItem": {
"id": "商品ID",
"item_code": "商品编码",
"item_name": "商品名称",
"sku_property": "规格",
"stock_unit": "单位"
}
}
],
"pagination": {
"page": "当前页",
"pageSize": "每页条数",
"total": "总记录数",
"totalPages": "总页数"
}
}
},
"errors": [
{
"code": 400,
"message": "where 条件格式不正确"
},
{
"code": 400,
"message": "分页参数不合法"
}
]
}
]
},
{
"groupName": "库存报表模块",
"module": "storage.report",
"list": [
{
"method": "storage.report.search",
"description": "库存报表查询(主入口):按时间闭区间统计商品出入库并支持按库位或按商品聚合",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、by_space(是否按库位返回,默认 false)、store_ids(货主ID数组)。仅返回在时间区间内存在流水的数据(无流水键不返回)。"
},
{
"name": "where.start_time",
"type": "string",
"required": false,
"source": "body",
"description": "开始时间,支持字符串/Date;用于闭区间过滤:created_at >= start_time"
},
{
"name": "where.end_time",
"type": "string",
"required": false,
"source": "body",
"description": "结束时间,支持字符串/Date;用于闭区间过滤:created_at <= end_time"
},
{
"name": "where.by_space",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否按库位返回,默认 false。false=按商品+货主聚合(多库位汇总),true=按商品+库位+货主返回;当 where.by_space=true 时,额外返回 space_id、space_name(custom_name 优先,否则使用 space_code)。"
},
{
"name": "where.store_ids",
"type": "array",
"required": false,
"source": "body",
"description": "货主ID数组,用于过滤特定货主(空或未传表示不过滤)",
"list": []
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数对象(请求体 data.sort)。支持 data.sort.sortField / data.sort.sort_field 与 data.sort.sortOrder / data.sort.sort_order;sortField 白名单:begin_total、inbound_total、outbound_total、end_total;sortOrder 支持 ASC / DESC(大小写不敏感);非法字段或顺序将回退默认排序。"
},
{
"name": "sort.sortField",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序字段(兼容 data.sort.sortField)。白名单:begin_total、inbound_total、outbound_total、end_total;非法值回退默认排序。"
},
{
"name": "sort.sort_field",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序字段下划线别名(兼容 data.sort.sort_field),规则同 sort.sortField。"
},
{
"name": "sort.sortOrder",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序方向(兼容 data.sort.sortOrder),支持 ASC / DESC(大小写不敏感);非法值回退默认排序。"
},
{
"name": "sort.sort_order",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序方向下划线别名(兼容 data.sort.sort_order),规则同 sort.sortOrder。"
}
],
"response": [
{
"name": "data.list",
"type": "array",
"required": true,
"description": "匹配到的报表行列表\n已按 sort 规则排序返回。"
},
{
"name": "data.list[]",
"type": "object",
"required": true,
"description": "单条报表记录字段",
"children": [
{
"name": "start_time",
"type": "string",
"description": "请求时传入的 start_time(或 null)"
},
{
"name": "end_time",
"type": "string",
"description": "请求时传入的 end_time(或 null)"
},
{
"name": "store_name",
"type": "string",
"description": "货主名称"
},
{
"name": "item_name",
"type": "string",
"description": "商品名称"
},
{
"name": "barcode",
"type": "string",
"description": "商品条码(逗号分隔)"
},
{
"name": "item_code",
"type": "string",
"description": "商品编码"
},
{
"name": "begin_total",
"type": "number",
"description": "期初库存量:取 start_time 前最后一条记录的 after_quantity(若 start_time 未传,默认为 0)"
},
{
"name": "end_total",
"type": "number",
"description": "期末库存量:取 end_time 时点(<= end_time)最后一条记录的 after_quantity(若 end_time 未传则取最近一条)"
},
{
"name": "inbound_total",
"type": "number",
"description": "在查询区间内累计入库数(INBOUND)"
},
{
"name": "outbound_total",
"type": "number",
"description": "在查询区间内累计出库数(OUTBOUND)"
},
{
"name": "stock_id",
"type": "number",
"description": "商品库存记录ID(stock_warehouse.id)"
},
{
"name": "store_id",
"type": "number",
"description": "货主ID"
},
{
"name": "begin_total",
"type": "number",
"description": "期初库存(数值)"
},
{
"name": "end_total",
"type": "number",
"description": "期末库存(数值)"
},
{
"name": "inbound_total",
"type": "number",
"description": "入库合计"
},
{
"name": "outbound_total",
"type": "number",
"description": "出库合计"
},
{
"name": "by_space_mode",
"type": "string",
"description": "说明当前返回模式:'by_space' 或 'by_product'"
},
{
"name": "space_id",
"type": "number",
"description": "库位ID(仅当 where.by_space=true 返回)"
},
{
"name": "space_name",
"type": "string",
"description": "库位名称(custom_name 优先,否则使用 space_code,where.by_space=true 时返回)"
}
]
}
],
"errors": [
{
"code": 400,
"message": "start_time 不合法"
},
{
"code": 400,
"message": "end_time 不合法"
},
{
"code": 400,
"message": "start_time 不能大于 end_time"
}
]
},
{
"method": "storage.report.export",
"description": "提交库存报表导出异步任务(与 storage.report.search 使用相同查询条件),立即返回任务受理信息,不直接返回文件。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、by_space(是否按库位返回,默认 false)、store_ids(货主ID数组)。仅返回在时间区间内存在流水的数据(无流水键不返回)。"
},
{
"name": "where.start_time",
"type": "string",
"required": false,
"source": "body",
"description": "开始时间,支持字符串/Date;用于闭区间过滤:created_at >= start_time"
},
{
"name": "where.end_time",
"type": "string",
"required": false,
"source": "body",
"description": "结束时间,支持字符串/Date;用于闭区间过滤:created_at <= end_time"
},
{
"name": "where.by_space",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否按库位返回,默认 false。false=按商品+货主聚合(多库位汇总),true=按商品+库位+货主返回;当 where.by_space=true 时,导出汇总 sheet 会额外包含 space_id、space_name。"
},
{
"name": "where.store_ids",
"type": "array",
"required": false,
"source": "body",
"description": "货主ID数组,用于过滤特定货主(空或未传表示不过滤)",
"list": []
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数对象(请求体 data.sort)。支持 data.sort.sortField / data.sort.sort_field 与 data.sort.sortOrder / data.sort.sort_order;sortField 白名单:begin_total、inbound_total、outbound_total、end_total;sortOrder 支持 ASC / DESC(大小写不敏感);非法字段或顺序将回退默认排序。"
},
{
"name": "sort.sortField",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序字段(兼容 data.sort.sortField)。白名单:begin_total、inbound_total、outbound_total、end_total;非法值回退默认排序。"
},
{
"name": "sort.sort_field",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序字段下划线别名(兼容 data.sort.sort_field),规则同 sort.sortField。"
},
{
"name": "sort.sortOrder",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序方向(兼容 data.sort.sortOrder),支持 ASC / DESC(大小写不敏感);非法值回退默认排序。"
},
{
"name": "sort.sort_order",
"type": "string",
"required": false,
"source": "body.sort",
"description": "排序方向下划线别名(兼容 data.sort.sort_order),规则同 sort.sortOrder。"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "导出任务ID,用于后续查询进度。"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "任务状态,提交受理后初始为 submitted。"
},
{
"name": "progress",
"type": "number",
"required": true,
"description": "任务进度百分比(0-100)。"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "任务受理提示信息。"
},
{
"name": "error",
"type": "string",
"required": true,
"description": "错误信息;受理成功时通常为空字符串。"
},
{
"name": "result",
"type": "object|null",
"required": true,
"description": "任务结果对象;受理阶段为 null。"
},
{
"name": "update_time",
"type": "number",
"required": true,
"description": "任务状态更新时间(时间戳)。"
}
],
"errors": [
{
"code": 400,
"message": "start_time 不合法"
},
{
"code": 400,
"message": "end_time 不合法"
},
{
"code": 400,
"message": "start_time 不能大于 end_time"
}
]
},
{
"method": "storage.report.exportTaskProgress",
"description": "根据 task_id 查询库存报表导出任务进度与结果;status 可能值:submitted/running/success/failed/not_found。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "task_id",
"type": "string",
"required": false,
"source": "body",
"description": "导出任务ID(下划线写法)。"
},
{
"name": "taskId",
"type": "string",
"required": false,
"source": "body",
"description": "导出任务ID(驼峰写法,兼容别名)。"
}
],
"response": [
{
"name": "task_id",
"type": "string",
"required": true,
"description": "导出任务ID。"
},
{
"name": "status",
"type": "string",
"required": true,
"description": "任务状态:submitted/running/success/failed/not_found。"
},
{
"name": "progress",
"type": "number",
"required": true,
"description": "任务进度百分比(0-100)。"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "任务状态说明。"
},
{
"name": "error",
"type": "string",
"required": true,
"description": "失败时的错误信息;成功时通常为空字符串。"
},
{
"name": "download_url",
"type": "string",
"required": true,
"description": "任务成功后返回的下载链接;未完成或失败时为空字符串。"
},
{
"name": "update_time",
"type": "number",
"required": true,
"description": "任务状态更新时间(时间戳)。"
},
{
"name": "result",
"type": "object|null",
"required": true,
"description": "任务结果对象(包含导出文件信息);未完成或失败时可能为 null。"
}
],
"errors": []
}
]
},
{
"groupName": "主体模块",
"module": "store",
"list": [
{
"method": "store.createStore",
"description": "store.createStore 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))、enable_external_express_code=false(是否启用外部快递编码,默认 false(关闭))",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "subject_config",
"type": "object",
"required": false,
"source": "body",
"description": "货主主体配置,不传时自动写入默认值"
},
{
"name": "subject_config.max_notice_webhook_count",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "当前主体最多允许绑定 / 触达的消息推送接口数量,默认 5"
},
{
"name": "subject_config.default_express_code",
"type": "string",
"required": false,
"source": "body.subject_config",
"description": "默认快递编码,缺省为 STO"
},
{
"name": "subject_config.default_platform_code",
"type": "string",
"required": false,
"source": "body.subject_config",
"description": "默认平台编码,缺省为 TB"
},
{
"name": "subject_config.group_wave_prefix",
"type": "string",
"required": false,
"source": "body.subject_config",
"description": "团购波次前缀,最多 5 个字符,默认 B"
},
{
"name": "subject_config.min_group_order_fetch_quantity",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "最小团购订单抓取数量,默认 13"
},
{
"name": "subject_config.auto_grouping_enabled",
"type": "boolean",
"required": false,
"source": "body.subject_config",
"description": "是否自动加团,默认 false(关闭)"
},
{
"name": "subject_config.enable_external_express_code",
"type": "boolean",
"required": false,
"source": "body.subject_config",
"description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)"
}
],
"response": [],
"errors": []
},
{
"method": "store.createWarehouse",
"description": "store.createWarehouse 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))、enable_external_express_code=false(是否启用外部快递编码,默认 false(关闭))",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "subject_config",
"type": "object",
"required": false,
"source": "body",
"description": "货主主体配置,不传时自动写入默认值"
},
{
"name": "subject_config.max_notice_webhook_count",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "当前主体最多允许绑定 / 触达的消息推送接口数量,默认 5"
},
{
"name": "subject_config.default_express_code",
"type": "string",
"required": false,
"source": "body.subject_config",
"description": "默认快递编码,缺省为 STO"
},
{
"name": "subject_config.default_platform_code",
"type": "string",
"required": false,
"source": "body.subject_config",
"description": "默认平台编码,缺省为 TB"
},
{
"name": "subject_config.group_wave_prefix",
"type": "string",
"required": false,
"source": "body.subject_config",
"description": "团购波次前缀,最多 5 个字符,默认 B"
},
{
"name": "subject_config.min_group_order_fetch_quantity",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "最小团购订单抓取数量,默认 13"
},
{
"name": "subject_config.auto_grouping_enabled",
"type": "boolean",
"required": false,
"source": "body.subject_config",
"description": "是否自动加团,默认 false(关闭)"
},
{
"name": "subject_config.enable_external_express_code",
"type": "boolean",
"required": false,
"source": "body.subject_config",
"description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)"
}
],
"response": [],
"errors": []
},
{
"method": "store.joinStore",
"description": "store.joinStore 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "store.joinWarehouse",
"description": "store.joinWarehouse 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "store.getStoreRoles",
"description": "store.getStoreRoles 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "申请码(join_token)"
}
],
"response": [],
"errors": []
},
{
"method": "store.auditApply",
"description": "store.auditApply 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "audit_status",
"type": "string",
"required": true,
"source": "body",
"description": "审核状态(approved/rejected)"
},
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "申请码(join_token)"
},
{
"name": "store_id",
"type": "number",
"required": true,
"source": "body",
"description": "当前审批门店ID"
},
{
"name": "role_ids",
"type": "array",
"required": true,
"source": "body",
"description": "分配角色ID数组"
},
{
"name": "reject_reason",
"type": "string",
"required": false,
"source": "body",
"description": "拒绝原因(audit_status=rejected 时可传)"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "货主-仓库签约模块",
"module": "storeWarehouse.store",
"list": [
{
"method": "storeWarehouse.store.list",
"description": "查询当前主体可见的仓库-货主签约列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码,默认 1"
},
{
"name": "page_size",
"type": "number",
"required": false,
"source": "body",
"description": "分页大小,默认 20"
},
{
"name": "keyword",
"type": "string",
"required": false,
"source": "body",
"description": "签约备注或主体名称关键字"
}
],
"response": [
{
"name": "data.list",
"type": "array",
"description": "签约关系列表"
},
{
"name": "data.list[].id",
"type": "number",
"description": "签约关系主键 ID"
},
{
"name": "data.list[].store_id",
"type": "number",
"description": "货主 ID"
},
{
"name": "data.list[].store_name",
"type": "string",
"description": "货主名称(优先取备注名,无则取 company_name)"
},
{
"name": "data.list[].warehouse_id",
"type": "number",
"description": "仓库 ID"
},
{
"name": "data.list[].warehouse_name",
"type": "string",
"description": "仓库名称(优先取备注名,无则取 company_name)"
},
{
"name": "data.list[].counterparty_id",
"type": "number",
"description": "对方主体 ID(当前为仓库则返回货主 ID,反之亦然)"
},
{
"name": "data.list[].counterparty_name",
"type": "string",
"description": "对方主体名称"
},
{
"name": "data.list[].current_subject_role",
"type": "string",
"description": "当前主体角色:warehouse 或 store"
},
{
"name": "data.list[].auth_status",
"type": "number",
"description": "签约状态:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期"
},
{
"name": "data.list[].auth_status_label",
"type": "string",
"description": "签约状态中文标签"
},
{
"name": "data.list[].apply_reason",
"type": "string",
"description": "申请原因"
},
{
"name": "data.list[].review_comment",
"type": "string",
"description": "审核评语"
},
{
"name": "data.list[].apply_time",
"type": "string|null",
"description": "申请时间"
},
{
"name": "data.list[].review_time",
"type": "string|null",
"description": "审核时间"
},
{
"name": "data.list[].auth_start",
"type": "string|null",
"description": "授权开始时间"
},
{
"name": "data.list[].auth_end",
"type": "string|null",
"description": "授权结束时间"
},
{
"name": "data.list[].actual_end",
"type": "string|null",
"description": "实际结束时间"
},
{
"name": "data.list[].print_quantity",
"type": "number",
"description": "面单余额数量"
},
{
"name": "data.list[].applied_by",
"type": "number|null",
"description": "申请人账号 ID"
},
{
"name": "data.list[].reviewed_by",
"type": "number|null",
"description": "审核人账号 ID"
},
{
"name": "data.list[].ended_by",
"type": "number|null",
"description": "解除人账号 ID"
},
{
"name": "data.list[].remask",
"type": "string",
"description": "备注名(当前为仓库则返回货主备注名,反之亦然)"
},
{
"name": "data.list[].use_status",
"type": "number",
"description": "启用状态:0=禁用 1=启用"
},
{
"name": "data.list[].policy_config",
"type": "object|null",
"description": "签约策略配置对象,无则为 null"
},
{
"name": "data.list[].is_auth_valid",
"type": "boolean",
"description": "签约是否在有效期内"
},
{
"name": "data.list[].remaining_days",
"type": "number",
"description": "剩余有效天数(未在有效期内时为 0)"
},
{
"name": "data.list[].has_qimen_config",
"type": "boolean",
"description": "该货主是否已配置奇门(true=已配置,false=未配置)"
},
{
"name": "data.total",
"type": "number",
"description": "总记录数"
},
{
"name": "data.page",
"type": "number",
"description": "当前页码"
},
{
"name": "data.page_size",
"type": "number",
"description": "每页条数"
},
{
"name": "data.current_subject.store_id",
"type": "number",
"description": "当前主体 ID"
},
{
"name": "data.current_subject.company_name",
"type": "string",
"description": "当前主体公司名称"
},
{
"name": "data.current_subject.role",
"type": "string",
"description": "当前主体角色:warehouse 或 store"
}
],
"errors": []
},
{
"method": "storeWarehouse.store.sign",
"description": "发起或确认仓库-货主签约",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID;由仓库侧发起时必传"
},
{
"name": "warehouse_id",
"type": "number",
"required": false,
"source": "body",
"description": "仓库ID;由货主侧发起时必传"
},
{
"name": "temp_code",
"type": "string",
"required": false,
"source": "body",
"description": "临时签约码;传入后进入确认或预览流程"
}
],
"response": [],
"errors": []
},
{
"method": "storeWarehouse.store.rename",
"description": "修改当前主体视角下的签约备注名",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
}
],
"response": [],
"errors": []
},
{
"method": "storeWarehouse.store.unbind",
"description": "解除或停用签约关系",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
},
{
"name": "use_status",
"type": "number",
"required": false,
"source": "body",
"description": "使用状态,0=停用,1=恢复"
}
],
"response": [],
"errors": []
},
{
"method": "storeWarehouse.store.adjustPrintQuantity",
"description": "人工调整签约关系下的面单余额并记录变更日志",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
},
{
"name": "print_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "目标面单余额(覆盖值);优先使用该字段"
},
{
"name": "target_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "目标面单余额(覆盖值);兼容别名"
},
{
"name": "change_quantity",
"type": "number",
"required": true,
"source": "body",
"description": "兼容旧字段;当前按目标面单余额(覆盖值)解释,差值将自动写入变更日志"
},
{
"name": "adjust_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "兼容旧字段;当前按目标面单余额(覆盖值)解释"
},
{
"name": "reason",
"type": "string",
"required": true,
"source": "body",
"description": "人工调整缘由,必填"
},
{
"name": "business_type",
"type": "string",
"required": false,
"source": "body",
"description": "业务来源类型,预留给后续 order_express 等自动扣减场景"
},
{
"name": "business_id",
"type": "number",
"required": false,
"source": "body",
"description": "业务关联ID,预留给后续关联 wms_order_express.id"
}
],
"response": [],
"errors": []
},
{
"method": "storeWarehouse.store.queryPrintQuantityLogs",
"description": "按 store_id 分页查询面单余额变更日志",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "store_id",
"type": "number|string",
"required": true,
"source": "body",
"description": "货主ID(必填)"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页对象,包含 page 与 page_size;默认 { page: 1, page_size: 20 }",
"children": [
{
"name": "page",
"type": "number",
"required": false,
"description": "页码,默认 1"
},
{
"name": "page_size",
"type": "number",
"required": false,
"description": "每页条数,默认 20"
}
]
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "返回结果对象,包含 list 和 pagination",
"children": [
{
"name": "list",
"type": "array",
"required": true,
"description": "变更日志列表,字段示例:id, contract_id, store_id, warehouse_id, change_type, business_type, business_id, change_quantity, balance_before, balance_after, reason, operator_id, created_by, created_at, updated_at"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)",
"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": false,
"description": "总页数"
},
{
"name": "hasPrevious",
"type": "boolean",
"required": false,
"description": "是否有上一页"
},
{
"name": "hasNext",
"type": "boolean",
"required": false,
"description": "是否有下一页"
}
]
}
]
}
],
"errors": [
{
"code": "400",
"description": "参数错误或缺少 store_id"
},
{
"code": "403",
"description": "仅可查询当前货主的面单余额变更日志"
},
{
"code": "500",
"description": "查询失败"
}
]
},
{
"method": "storeWarehouse.store.getPolicyConfig",
"description": "读取签约策略配置",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
}
],
"response": [
{
"name": "data.contract_id",
"type": "number",
"required": true,
"description": "签约关系ID"
},
{
"name": "data.policy_config",
"type": "object",
"required": true,
"description": "策略配置对象(包含默认值补齐后的字段)"
},
{
"name": "data.policy_config.enable_external_express_code",
"type": "number",
"required": true,
"description": "是否启用外部快递编码(flag:0=关闭,1=开启;默认 0)"
}
],
"errors": []
},
{
"method": "storeWarehouse.store.getPolicyConfigFields",
"description": "获取签约策略可配置字段元信息列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "storeWarehouse.store.savePolicyConfig",
"description": "保存签约策略配置",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
},
{
"name": "policy_config",
"type": "object",
"required": true,
"source": "body",
"description": "策略配置对象;支持 receive_mode、auto_allocate_bin、auto_allocate_express(是否自动分配快递)、auto_allocate_storage(是否自动分配储位)、allow_mix_batch、allow_temp_storage、storage_separation、print_recharge_price(面单充值元/单,支持 2 位小数)、max_daily_inbound、remark、waybill_custom_display_type(面单自定义显示类型:1=隐藏,2=商品名称和数量,3=拣货库位和条码和数量,4=拣货库位和条码后5位和数量,5=拣货库位商品名称条码和数量)、enable_external_express_code(是否启用外部快递编码,flag:0=关闭,1=开启;默认 0)"
},
{
"name": "policy_config.enable_external_express_code",
"type": "number",
"required": false,
"source": "body.policy_config",
"description": "是否启用外部快递编码(flag:0=关闭,1=开启;默认 0)"
}
],
"response": [
{
"name": "data.contract_id",
"type": "number",
"required": true,
"description": "签约关系ID"
},
{
"name": "data.policy_config",
"type": "object",
"required": true,
"description": "保存后并补齐默认值的策略配置对象"
},
{
"name": "data.policy_config.enable_external_express_code",
"type": "number",
"required": true,
"description": "是否启用外部快递编码(flag:0=关闭,1=开启;默认 0)"
}
],
"errors": []
},
{
"method": "storeWarehouse.store.listApiConfig",
"description": "查询签约关系下的接口配置列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
},
{
"name": "interface_type_id",
"type": "number",
"required": false,
"source": "body",
"description": "接口类型ID,默认查询全部可用类型"
}
],
"response": [
{
"name": "data.list[].callback_url",
"type": "string",
"description": "API回调通知URL,来自 serializeQimenConfig 序列化"
}
],
"errors": []
},
{
"method": "storeWarehouse.store.saveApiConfig",
"description": "新增或更新签约关系下的接口配置。QM_WMS 类型须填写奇门字段;OPEN_API 类型由系统自动生成 self_app_key 和 self_app_secret",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
},
{
"name": "interface_type_id",
"type": "number",
"required": true,
"source": "body",
"description": "接口类型ID,必须是 wms_interface_type 已存在的类型"
},
{
"name": "qimen_app_key",
"type": "string",
"required": false,
"source": "body",
"description": "奇门 AppKey(QM_WMS 类型必填,OPEN_API 类型不需要)"
},
{
"name": "qimen_customer_id",
"type": "string",
"required": false,
"source": "body",
"description": "奇门客户ID(QM_WMS 类型必填,OPEN_API 类型不需要)"
},
{
"name": "qimen_warehouse_code",
"type": "string",
"required": false,
"source": "body",
"description": "奇门仓库编码(QM_WMS 类型必填,OPEN_API 类型不需要)"
},
{
"name": "app_name",
"type": "string",
"required": true,
"source": "body",
"description": "应用名称"
},
{
"name": "callback_url",
"type": "string",
"required": false,
"source": "body",
"description": "API 回调通知 URL(可选),最大 500 字符;配置后订单状态变更时将回调通知推送到此地址;兼容别名 callbackUrl"
}
],
"response": [],
"errors": [],
"notes": [
"callback_url:OpenAPI 类型的接口可配置回调地址,订单同步完成/取消等事件将推送到此 URL"
]
},
{
"method": "storeWarehouse.store.deleteQimenConfig",
"description": "删除签约关系下的奇门接口配置",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "签约关系ID,兼容 contract_id"
},
{
"name": "interface_type_id",
"type": "number",
"required": false,
"source": "body",
"description": "接口类型ID"
}
],
"response": [],
"errors": []
},
{
"method": "storeWarehouse.store.openAccount",
"description": "仓库代货主一键开户:同时完成账号注册、货主创建和仓库-货主签约",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token(当前主体必须为仓库角色)"
}
],
"params": [
{
"name": "username",
"type": "string",
"required": true,
"source": "body",
"description": "登录账号(用户名),全局唯一"
},
{
"name": "password",
"type": "string",
"required": false,
"source": "body",
"description": "初始密码,不传则自动随机生成 12 位密码"
},
{
"name": "real_name",
"type": "string",
"required": false,
"source": "body",
"description": "真实姓名"
},
{
"name": "company_name",
"type": "string",
"required": true,
"source": "body",
"description": "公司全称,全局唯一,1-200 字符"
},
{
"name": "business_license",
"type": "string",
"required": false,
"source": "body",
"description": "营业执照号"
},
{
"name": "contact_person",
"type": "string",
"required": true,
"source": "body",
"description": "联系人姓名,1-50 字符"
},
{
"name": "contact_phone",
"type": "string",
"required": false,
"source": "body",
"description": "联系电话"
},
{
"name": "legal_person",
"type": "string",
"required": false,
"source": "body",
"description": "法人代表"
},
{
"name": "contact_email",
"type": "string",
"required": false,
"source": "body",
"description": "联系邮箱"
},
{
"name": "address",
"type": "string",
"required": false,
"source": "body",
"description": "公司地址"
},
{
"name": "industry",
"type": "string",
"required": false,
"source": "body",
"description": "所属行业"
},
{
"name": "logo_url",
"type": "string",
"required": false,
"source": "body",
"description": "Logo 链接"
},
{
"name": "domain",
"type": "string",
"required": false,
"source": "body",
"description": "绑定域名"
},
{
"name": "auth_start",
"type": "string",
"required": false,
"source": "body",
"description": "授权开始日期,默认当天(ISO 8601 格式)"
},
{
"name": "auth_end",
"type": "string",
"required": false,
"source": "body",
"description": "授权结束日期(ISO 8601 格式)"
},
{
"name": "print_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "初始面单余额,默认 0"
},
{
"name": "apply_reason",
"type": "string",
"required": false,
"source": "body",
"description": "申请原因,默认\"仓库代开户\",最长 2000 字符"
},
{
"name": "store_remask",
"type": "string",
"required": false,
"source": "body",
"description": "货主备注名,最长 50 字符"
},
{
"name": "warehouse_remask",
"type": "string",
"required": false,
"source": "body",
"description": "仓库备注名,最长 50 字符"
}
],
"response": [
{
"name": "store_id",
"type": "number",
"required": true,
"description": "新建的货主 ID"
},
{
"name": "account_id",
"type": "number",
"required": true,
"description": "新建的账号 ID"
},
{
"name": "contract_id",
"type": "number",
"required": true,
"description": "新建的签约关系 ID"
},
{
"name": "company_name",
"type": "string",
"required": true,
"description": "货主公司名称"
},
{
"name": "username",
"type": "string",
"required": true,
"description": "新建的登录账号名"
},
{
"name": "role_id",
"type": "number",
"required": true,
"description": "分配的货主管理员角色 ID"
}
],
"errors": []
}
]
},
{
"groupName": "用户模块",
"module": "user",
"list": [
{
"method": "user.login",
"description": "用户登录(仅返回 token)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "password",
"type": "string",
"required": false,
"source": "body",
"description": "password 参数"
},
{
"name": "username",
"type": "string",
"required": false,
"source": "body",
"description": "username 参数"
}
],
"response": [],
"errors": []
},
{
"method": "user.loginByCode",
"description": "登录码登录(使用 ye4s_user.tmp_code)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "code",
"type": "string",
"required": true,
"source": "body",
"description": "登录码,对应 ye4s_user.tmp_code"
}
],
"response": [],
"errors": []
},
{
"method": "user.getLoginWechatCode",
"description": "获取微信扫码登录码(无 clientCode 时分配新客户端编码;有 clientCode 时可长轮询刷新)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "clientCode",
"type": "string",
"required": false,
"source": "body",
"description": "客户端编码;首次可不传,后续轮询建议透传已有值"
}
],
"response": [],
"errors": []
},
{
"method": "user.getBindWechatCode",
"description": "获取微信绑定码(默认立即返回;显式开启长轮询后,最长等待60秒,状态变化立即返回)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "forceRefresh",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否强制刷新状态,true 时跳过缓存等待窗口"
},
{
"name": "waitForChange",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否显式开启长轮询等待(推荐字段);true 时进入最长60秒等待"
},
{
"name": "longPoll",
"type": "boolean",
"required": false,
"source": "body",
"description": "长轮询开关(兼容字段);true 时进入最长60秒等待"
},
{
"name": "waitTimeoutMs",
"type": "number",
"required": false,
"source": "body",
"description": "等待超时毫秒数;后端自动封顶60000"
},
{
"name": "init",
"type": "boolean",
"required": false,
"source": "body",
"description": "初始化请求标记;true 时强制立即返回,不进入长等待"
}
],
"response": [],
"errors": []
},
{
"method": "user.unbindWechat",
"description": "解绑微信账号(清理 ye4s 关联账号数据)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "user.logout",
"description": "用户登出",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "user.info",
"description": "获取当前用户信息",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "user.changeRole",
"description": "user.changeRole 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "user.register",
"description": "user.register 接口",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [],
"response": [],
"errors": []
}
]
},
{
"groupName": "仓库模块",
"module": "warehouse",
"list": [
{
"method": "warehouse.getWarehouseZones",
"description": "warehouse.getWarehouseZones 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "warehouse.getWarehouseTree",
"description": "warehouse.getWarehouseTree 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouseId",
"type": "number",
"required": true,
"source": "body",
"description": "warehouseId 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.getChildren",
"description": "warehouse.getChildren 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "zoneId",
"type": "number",
"required": true,
"source": "body",
"description": "zoneId 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.create",
"description": "warehouse.create 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
},
{
"method": "warehouse.update",
"description": "warehouse.update 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
},
{
"name": "aisles",
"type": "string",
"required": false,
"source": "body",
"description": "aisles 参数"
},
{
"name": "cell_height",
"type": "string",
"required": false,
"source": "body",
"description": "cell_height 参数"
},
{
"name": "cell_length",
"type": "string",
"required": false,
"source": "body",
"description": "cell_length 参数"
},
{
"name": "cell_width",
"type": "string",
"required": false,
"source": "body",
"description": "cell_width 参数"
},
{
"name": "direction",
"type": "string",
"required": false,
"source": "body",
"description": "direction 参数"
},
{
"name": "height",
"type": "number",
"required": false,
"source": "body",
"description": "height 参数"
},
{
"name": "is_active",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否启用,支持 true/false 或 1/0"
},
{
"name": "length",
"type": "number",
"required": false,
"source": "body",
"description": "length 参数"
},
{
"name": "rack_columns",
"type": "string",
"required": false,
"source": "body",
"description": "rack_columns 参数"
},
{
"name": "rack_levels",
"type": "string",
"required": false,
"source": "body",
"description": "rack_levels 参数"
},
{
"name": "rack_rows",
"type": "string",
"required": false,
"source": "body",
"description": "rack_rows 参数"
},
{
"name": "width",
"type": "number",
"required": false,
"source": "body",
"description": "width 参数"
},
{
"name": "x",
"type": "number",
"required": false,
"source": "body",
"description": "x 参数"
},
{
"name": "y",
"type": "number",
"required": false,
"source": "body",
"description": "y 参数"
},
{
"name": "z",
"type": "number",
"required": false,
"source": "body",
"description": "z 参数"
},
{
"name": "zone_code",
"type": "string",
"required": false,
"source": "body",
"description": "zone_code 参数"
},
{
"name": "zone_name",
"type": "string",
"required": false,
"source": "body",
"description": "zone_name 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.delete",
"description": "warehouse.delete 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.detail",
"description": "warehouse.detail 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.checkBarcodeUnique",
"description": "warehouse.checkBarcodeUnique 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "barcode",
"type": "string",
"required": true,
"source": "body",
"description": "barcode 参数"
},
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.toggleActive",
"description": "warehouse.toggleActive 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
},
{
"name": "isActive",
"type": "string",
"required": false,
"source": "body",
"description": "isActive 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.getPath",
"description": "warehouse.getPath 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.getPickPath",
"description": "warehouse.getPickPath 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "query",
"description": "warehouse_id 参数"
},
{
"name": "include_spaces",
"type": "string",
"required": false,
"source": "query",
"description": "include_spaces 参数"
},
{
"name": "limit",
"type": "number",
"required": false,
"source": "query",
"description": "limit 参数"
},
{
"name": "sort_by",
"type": "string",
"required": false,
"source": "query",
"description": "sort_by 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.updateRackPosition",
"description": "warehouse.updateRackPosition 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "x",
"type": "number",
"required": true,
"source": "body",
"description": "x 参数"
},
{
"name": "y",
"type": "number",
"required": true,
"source": "body",
"description": "y 参数"
},
{
"name": "rack_id",
"type": "number",
"required": false,
"source": "path",
"description": "rack_id 参数"
},
{
"name": "z",
"type": "number",
"required": false,
"source": "body",
"description": "z 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.recalculatePickPath",
"description": "warehouse.recalculatePickPath 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "warehouse_id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.updateNeighbors",
"description": "warehouse.updateNeighbors 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "warehouse_id",
"type": "number",
"required": true,
"source": "body",
"description": "warehouse_id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.getAreaRacks",
"description": "warehouse.getAreaRacks 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "area_id",
"type": "number",
"required": true,
"source": "query",
"description": "area_id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.getSpacesByRack",
"description": "warehouse.getSpacesByRack 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.createRackWithSpaces",
"description": "warehouse.createRackWithSpaces 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": []
},
{
"method": "warehouse.exportRackSpaces",
"description": "按货架ID导出仓位模板(含仓库编码、仓位编码、自定义名称、自定义条码、拣货顺序、仓位类型)",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "货架ID,仅导出该货架下仓位"
}
],
"response": [
{
"name": "count",
"type": "number",
"description": "导出记录数"
},
{
"name": "fileName",
"type": "string",
"description": "导出文件名"
},
{
"name": "fileUrl",
"type": "string",
"description": "导出文件下载地址"
}
],
"errors": []
},
{
"method": "warehouse.batchUpdateSpaceInfo",
"description": "按导出模板批量修改货架仓位信息,任一行越界或冲突则整批失败。前端提交示例:{ id: 36, items: [ { space_code: 'A01-01-01', custom_name: '拣货位1', custom_barcode: 'PICK-001', pick_sequence: 10, location_type_id: 3 } ] }。其中 id 为货架ID(可选,传入时只允许操作该货架下的仓位),space_code 为必填定位键,location_type_id 为仓位类型主键(可通过 index.getLocationTypeList 获取)。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": false,
"source": "body",
"description": "货架ID,传入时校验所有 space_code 必须属于该货架,不传则只校验属于任意货架类型库位"
},
{
"name": "items",
"type": "array",
"required": true,
"source": "body",
"description": "批量修改数据数组;每项支持字段:space_code、custom_name、custom_barcode、pick_sequence、location_type_name"
},
{
"name": "items[].space_code",
"type": "string",
"required": true,
"source": "body",
"description": "仓位编码,作为批量修改的唯一定位键;缺失、重复或不存在都会整批失败"
},
{
"name": "items[].custom_name",
"type": "string",
"required": false,
"source": "body",
"description": "自定义名称,空字符串会被清空"
},
{
"name": "items[].custom_barcode",
"type": "string",
"required": false,
"source": "body",
"description": "自定义条码,批次内或系统内冲突都会整批失败;空字符串会被清空"
},
{
"name": "items[].pick_sequence",
"type": "number",
"required": false,
"source": "body",
"description": "拣货顺序,必须为非负整数,超出边界则整批失败"
},
{
"name": "items[].location_type_id",
"type": "number",
"required": false,
"source": "body",
"description": "仓位类型ID,必须为正整数且在当前仓库或全局类型中存在(is_active=true),否则整批失败;传 null 或不传则不修改仓位类型"
}
],
"response": [
{
"name": "count",
"type": "number",
"description": "成功更新的记录数"
}
],
"errors": []
},
{
"method": "warehouse.getSpaceInfo",
"description": "warehouse.getSpaceInfo 接口",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
}
],
"response": [],
"errors": [
{
"code": "0",
"description": "仓位不存在"
},
{
"code": "0",
"description": "仓位不属于当前仓库"
}
]
},
{
"method": "warehouse.updateSpaceInfo",
"description": "warehouse.updateSpaceInfo 接口",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "id 参数"
},
{
"name": "custom_barcode",
"type": "string",
"required": false,
"source": "body",
"description": "custom_barcode 参数"
},
{
"name": "custom_name",
"type": "string",
"required": false,
"source": "body",
"description": "custom_name 参数"
},
{
"name": "location_type_id",
"type": "number",
"required": false,
"source": "body",
"description": "location_type_id 参数"
},
{
"name": "pick_sequence",
"type": "string",
"required": false,
"source": "body",
"description": "pick_sequence 参数"
},
{
"name": "space_status",
"type": "string",
"required": false,
"source": "body",
"description": "space_status 参数"
}
],
"response": [],
"errors": []
}
]
},
{
"groupName": "order.wave",
"module": "order",
"list": [
{
"method": "order.wave.batchList",
"description": "波次列表查询。仅使用当前登录操作者仓库上下文(禁止传入 warehouse_id/warehouseId)。支持 where 白名单过滤,固定查询 wave_status=0/1;返回波次基础信息及分配状态汇总。支持 only_todo=1 仅返回仍有未复核订单的波次,并返回复核状态汇总(review_assignment_status)与未复核数量(unreviewed_order_count)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page / pageSize"
},
{
"name": "only_todo",
"type": "number|boolean|string",
"required": false,
"source": "body",
"description": "是否仅返回待处理(仍有未复核订单)的波次,默认 0;传 1/true 时仅返回 unreviewed_order_count > 0 的波次。"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选白名单字段(object,可选)。仅支持下列字段过滤,且禁止传入 warehouse_id / warehouseId:\n- wave_id(等值)\n- wave_no(模糊)\n- wave_type(等值)\n- wave_status(等值,接口固定叠加状态 0/1)\n- creator(模糊)\n- logistics_name(模糊)\n- item_part_type(等值)\n- item_part(模糊)\n- item_snapshot_key(模糊)\n- item_detail_machine(模糊)\n- distinguish_express(等值)\n- total_orders_min / total_orders_max(范围)\n- processed_orders_min / processed_orders_max(范围)\n- express_assignment_status(等值,string,可选,英文枚举,取值:unassigned、partially_assigned、assigned;语义:按快递分配聚合判断,assigned 表示聚合后全部 fin,partially_assigned 表示部分已分配且不含 error,unassigned 表示全 none 或包含 error(异常并入未分配集合))。\n- print_assignment_status(等值,string,可选,英文枚举,取值:unprinted、partially_printed、printed;语义:按打印分配聚合判断,printed 表示聚合后全部已打印)。\n- storage_assignment_status(等值,string,可选,取值:未分配、部分分配、已分配;默认不传不做限制)。过滤语义:已分配=聚合后全部 fin;部分分配=不含 error,且既不是全 none,也不是全 fin;未分配=全 none 或包含 error(异常并入未分配筛选集合)。说明:返回字段 storage_assignment_status 的展示值保持不变,包含 error 时仍可显示“分配异常”;此处 where 的过滤语义会把异常计入“未分配”,以避免把过滤语义与展示值混淆。\n- source(可选,number)来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。\n说明:express_assignment_status 与 print_assignment_status 要求使用英文枚举值;storage_assignment_status 仍向后兼容中文展示值。若传入的枚举值不在允许集合内,接口会返回 400(参数校验失败),并在 message 中说明错误字段与允许取值。\n- sync_assignment_status(等值,string,可选,英文枚举,取值:unsynced、partially_synced、synced;语义:按同步状态聚合判断,synced 表示全部 fin,partially_synced 表示部分已同步且不含 error,unsynced 表示全 padding 或包含 error(异常并入未同步集合))。\n- review_assignment_status(等值,string,可选,英文枚举:unreviewed、partially_reviewed、reviewed;分别表示未复核、部分复核、已复核)。"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "波次列表,包含波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status / sync_assignment_status / review_assignment_status / unreviewed_order_count)。每条记录新增字段 source(number):来源标识,0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务。"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
}
],
"errors": [
{
"code": 400,
"message": "未识别到当前仓库上下文"
},
{
"code": 500,
"message": "查询失败"
}
]
}
]
},
{
"groupName": "店铺模块",
"module": "shops",
"list": [
{
"method": "shops.list",
"description": "分页查询店铺,支持 where 条件(支持字段:id, platform_code, custom_name, shop_name, status, quickWhere),兼容 snake_case 与 camelCase 入参;返回分页信息与标准化店铺列表。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码,兼容 pagination.page/currentPage"
},
{
"name": "pageSize",
"type": "number",
"required": false,
"source": "body",
"description": "每页大小,兼容 page_size/pagination.page_size,最大 200"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "查询条件,支持标准 where 结构或 quickWhere 简写,字段兼容 id/platform_code/custom_name/shop_name/status/quickWhere"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "调用结果标识,成功为 success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功为 200"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data.list",
"type": "array",
"required": true,
"description": "店铺数组,元素结构见 children",
"children": [
{
"name": "id",
"type": "number",
"description": "店铺 ID"
},
{
"name": "warehouse_id",
"type": "number",
"description": "仓库 ID"
},
{
"name": "platform_code",
"type": "string",
"description": "平台编码,返回大写"
},
{
"name": "platform_name",
"type": "string",
"description": "平台名称(来自关联 printPlatform)"
},
{
"name": "shop_name",
"type": "string",
"description": "店铺原始名称"
},
{
"name": "custom_name",
"type": "string|null",
"description": "店铺自定义名称"
},
{
"name": "status",
"type": "number",
"description": "授权状态:0=未授权,1=已授权"
},
{
"name": "created_at",
"type": "string",
"description": "创建时间"
},
{
"name": "updated_at",
"type": "string",
"description": "更新时间"
}
]
},
{
"name": "data.pagination",
"type": "object",
"required": true,
"description": "分页信息",
"children": [
{
"name": "page",
"type": "number",
"description": "当前页"
},
{
"name": "pageSize",
"type": "number",
"description": "每页大小"
},
{
"name": "total",
"type": "number",
"description": "总记录数"
},
{
"name": "totalPages",
"type": "number",
"description": "总页数"
},
{
"name": "hasNext",
"type": "boolean",
"description": "是否有下一页"
},
{
"name": "hasPrevious",
"type": "boolean",
"description": "是否有上一页"
}
]
}
],
"errors": [
{
"code": 400,
"message": "未识别到当前仓库"
},
{
"code": 400,
"message": "where 参数解析失败"
},
{
"code": 500,
"message": "查询店铺列表失败"
}
]
},
{
"method": "shops.add",
"description": "新增店铺,校验 platform_code 必须匹配已配置且处于 ACTIVE 且未删除的打印平台;custom_name 必填且长度<=100。shop_name 由服务端生成待授权占位名(PENDING_*),授权后再同步真实店铺名。支持 snake_case 与 camelCase 入参兼容。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "platform_code",
"type": "string",
"required": true,
"source": "body",
"description": "平台编码,兼容 platformCode,服务端会标准化为大写并验证"
},
{
"name": "custom_name",
"type": "string",
"required": true,
"source": "body",
"description": "店铺自定义名称,最大长度 100"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "200 成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data.id",
"type": "number",
"required": true,
"description": "新建店铺 ID"
}
],
"errors": [
{
"code": 400,
"message": "platform_code 未匹配到打印平台编码"
},
{
"code": 400,
"message": "custom_name 不能为空"
},
{
"code": 400,
"message": "custom_name 长度不能超过 100"
},
{
"code": 409,
"message": "同仓同平台下 shop_name 已存在"
},
{
"code": 500,
"message": "新增店铺失败"
}
]
},
{
"method": "shops.del",
"description": "软删除店铺:将 shop_name 修改为 DELETED_SHOP_<id>_<suffix> 并清空敏感字段;若存在 ExpressInterface 引用则返回 409;返回 deleted=true 与 id。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "店铺 ID,兼容 shop_id/shopId"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "200 成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data.deleted",
"type": "boolean",
"required": true,
"description": "是否已删除"
},
{
"name": "data.id",
"type": "number",
"required": true,
"description": "删除的店铺 ID"
}
],
"errors": [
{
"code": 400,
"message": "shop_id 参数不合法"
},
{
"code": 404,
"message": "店铺不存在"
},
{
"code": 409,
"message": "店铺存在快递接口引用,无法删除"
},
{
"code": 500,
"message": "删除店铺失败"
}
]
},
{
"method": "shops.edit",
"description": "编辑店铺,仅允许修改 platform_code 或 custom_name;至少传入其中一个。platform_code 会校验平台存在且为 ACTIVE;custom_name 必填且长度<=100;服务端兼容 snake_case/camelCase。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "店铺 ID,兼容 shop_id/shopId"
},
{
"name": "platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "平台编码,兼容 platformCode,服务端会转为大写并校验"
},
{
"name": "custom_name",
"type": "string",
"required": false,
"source": "body",
"description": "自定义名称,兼容 customName,若传入需非空且 <=100 字符"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "200 成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data.updated",
"type": "boolean",
"required": true,
"description": "是否已更新"
},
{
"name": "data.id",
"type": "number",
"required": true,
"description": "被更新的店铺 ID"
}
],
"errors": [
{
"code": 400,
"message": "仅允许修改 platform_code 或 custom_name"
},
{
"code": 400,
"message": "platform_code 未匹配到打印平台编码"
},
{
"code": 400,
"message": "custom_name 不能为空"
},
{
"code": 409,
"message": "同仓同平台下 shop_name 已存在"
},
{
"code": 500,
"message": "编辑店铺失败"
}
]
},
{
"method": "shops.GetAuthorizeSessionKey",
"description": "按店铺所属平台生成授权会话。入参兼容 id/shop_id/shopId 与 callbackurl/callback_url,callbackurl 必填。对已实现的平台(PDD/CAINIAO)返回 session_key/authorize_url/state,其他平台返回 501 未实现。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "店铺 ID,兼容 shop_id/shopId"
},
{
"name": "callbackurl",
"type": "string",
"required": true,
"source": "body",
"description": "回调地址,兼容 callback_url"
}
],
"response": [
{
"name": "flag",
"type": "string",
"required": true,
"description": "success"
},
{
"name": "code",
"type": "number",
"required": true,
"description": "200 成功"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data.shop_id",
"type": "number",
"required": true,
"description": "店铺 ID"
},
{
"name": "data.platform_code",
"type": "string",
"required": true,
"description": "平台编码(大写)"
},
{
"name": "data.callbackurl",
"type": "string",
"required": true,
"description": "回调地址"
},
{
"name": "data.session_key",
"type": "string",
"required": true,
"description": "授权预占码(session)"
},
{
"name": "data.authorize_url",
"type": "string",
"required": true,
"description": "平台授权跳转地址(含 state)"
},
{
"name": "data.state",
"type": "string",
"required": true,
"description": "内部 state 值(platform + '_' + authRandomCode),用于回调解析"
}
],
"errors": [
{
"code": 400,
"message": "callbackurl 不能为空"
},
{
"code": 400,
"message": "未识别到当前仓库"
},
{
"code": 404,
"message": "店铺不存在"
},
{
"code": 400,
"message": "平台授权基础地址未配置"
},
{
"code": 501,
"message": "平台 %s 暂未实现授权会话换取能力"
},
{
"code": 500,
"message": "生成唯一授权码失败,请稍后重试"
}
]
}
]
},
{
"groupName": "包材管理模块",
"module": "setting.packageMaterial",
"list": [
{
"method": "setting.packageMaterial.create",
"description": "创建包材(当前仓库范围)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "material_code",
"type": "string",
"required": true,
"source": "body",
"description": "包材编码(大写且在当前仓库唯一)"
},
{
"name": "material_name",
"type": "string",
"required": true,
"source": "body",
"description": "包材名称"
},
{
"name": "material_type",
"type": "string",
"required": false,
"source": "body",
"description": "包材类型"
},
{
"name": "spec",
"type": "string",
"required": false,
"source": "body",
"description": "规格"
},
{
"name": "length",
"type": "number",
"required": false,
"source": "body",
"description": "长度"
},
{
"name": "width",
"type": "number",
"required": false,
"source": "body",
"description": "宽度"
},
{
"name": "height",
"type": "number",
"required": false,
"source": "body",
"description": "高度"
},
{
"name": "weight",
"type": "number",
"required": false,
"source": "body",
"description": "重量"
},
{
"name": "cost_price",
"type": "number",
"required": false,
"source": "body",
"description": "成本价"
},
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "状态 0/1,默认 1"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "包材 ID"
}
],
"errors": [
{
"code": 400,
"message": "参数错误"
},
{
"code": 409,
"message": "material_code 冲突"
},
{
"code": 500,
"message": "服务器错误"
}
]
},
{
"method": "setting.packageMaterial.update",
"description": "更新包材(按 id 更新,支持部分字段)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "包材 ID(也兼容 material_id/materialId)"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "包材 ID"
}
],
"errors": [
{
"code": 400,
"message": "参数错误"
},
{
"code": 404,
"message": "未找到包材或无权限"
},
{
"code": 409,
"message": "material_code 冲突"
}
]
},
{
"method": "setting.packageMaterial.delete",
"description": "删除包材(支持 ids 数组或逗号分隔字符串,兼容 id/material_id/materialId)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array|number|string",
"required": true,
"source": "body",
"description": "要删除的 ID 列表"
}
],
"response": [
{
"name": "deleted",
"type": "boolean",
"required": true,
"description": "是否删除成功"
}
],
"errors": [
{
"code": 400,
"message": "ids 参数错误"
},
{
"code": 404,
"message": "存在不存在或无权限删除的项"
}
]
},
{
"method": "setting.packageMaterial.get",
"description": "查询包材列表,支持 where + pagination(兼容旧别名 list,建议使用 get)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,支持 page/pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选条件,支持 material_code/material_name/material_type/status/quickWhere"
}
],
"response": [
{
"name": "page",
"type": "number",
"required": true,
"description": "当前页"
},
{
"name": "page_size",
"type": "number",
"required": true,
"description": "每页大小"
},
{
"name": "total",
"type": "number",
"required": true,
"description": "总数"
},
{
"name": "list",
"type": "array",
"required": true,
"description": "包材项数组"
}
],
"errors": [
{
"code": 400,
"message": "参数解析失败"
}
]
},
{
"method": "setting.packageMaterial.list",
"description": "兼容旧称 list,内部转发至 get;建议改用 setting.packageMaterial.get",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
}
]
},
{
"groupName": "package-supplier-module",
"module": "setting.packageSupplier",
"list": [
{
"method": "setting.packageSupplier.create",
"description": "Create package supplier (current warehouse scope)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "supplier_code",
"type": "string",
"required": true,
"source": "body",
"description": "Supplier code (uppercased, unique in warehouse)"
},
{
"name": "supplier_name",
"type": "string",
"required": true,
"source": "body",
"description": "Supplier name"
},
{
"name": "contact_name",
"type": "string",
"required": false,
"source": "body",
"description": "Contact name"
},
{
"name": "contact_phone",
"type": "string",
"required": false,
"source": "body",
"description": "Contact phone"
},
{
"name": "status",
"type": "number",
"required": false,
"source": "body",
"description": "Status 0/1, default 1"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "Created supplier id"
}
],
"errors": [
{
"code": 400,
"message": "Invalid parameters"
},
{
"code": 409,
"message": "supplier_code conflict"
}
]
},
{
"method": "setting.packageSupplier.update",
"description": "Update package supplier by id (partial update supported)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "Supplier id (also supports supplier_id / supplierId)"
}
],
"response": [
{
"name": "id",
"type": "number",
"required": true,
"description": "Supplier id"
}
],
"errors": [
{
"code": 400,
"message": "Invalid parameters"
},
{
"code": 404,
"message": "Supplier not found or no permission"
}
]
},
{
"method": "setting.packageSupplier.delete",
"description": "Delete package suppliers (supports ids array or comma-separated string)",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "ids",
"type": "array|number|string",
"required": true,
"source": "body",
"description": "IDs to delete"
}
],
"response": [
{
"name": "deleted",
"type": "boolean",
"required": true,
"description": "Deleted flag"
}
],
"errors": [
{
"code": 400,
"message": "ids invalid"
},
{
"code": 404,
"message": "Some items not found or no permission"
}
]
},
{
"method": "setting.packageSupplier.get",
"description": "Get package supplier list (supports where + pagination). list is an alias to get; prefer get.",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "Pagination parameters"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "Filter conditions"
}
],
"response": [
{
"name": "page",
"type": "number",
"required": true,
"description": "Current page"
},
{
"name": "page_size",
"type": "number",
"required": true,
"description": "Page size"
},
{
"name": "total",
"type": "number",
"required": true,
"description": "Total"
},
{
"name": "list",
"type": "array",
"required": true,
"description": "Supplier array"
}
],
"errors": [
{
"code": 400,
"message": "Invalid parameters"
}
]
},
{
"method": "setting.packageSupplier.list",
"description": "Compatibility alias for get; internally forwards to get. Prefer setting.packageSupplier.get.",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [],
"response": [],
"errors": []
}
]
}
]
}
}