{ "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", "version": "0.3.7", "updatedAt": "2026-07-27", "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(正整数,单位 g);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": "部分商品不存在或无权修改: " }, { "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": "订单趋势统计:按小时统计当日订单数与发货数,包含汇总信息(订单总数、发货总数、发货率、峰值时段)。数据来源于真实数据库查询,已废弃旧版 mock 数据。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token,从中解析 warehouseId(仓库上下文)" } ], "params": [], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息" }, { "name": "data", "type": "object", "required": true, "description": "成功时返回的趋势数据对象", "children": [ { "name": "range", "type": "string", "required": true, "description": "统计范围,固定为 'day'" }, { "name": "date", "type": "string", "required": true, "description": "统计日期,格式 YYYY-MM-DD" }, { "name": "summary", "type": "object", "required": true, "description": "汇总统计信息", "children": [ { "name": "total_orders", "type": "number", "required": true, "description": "当日订单总数(step in [1,2,3],排除 outbound_status='padding' 和 status='cancel' 的订单)" }, { "name": "total_shipments", "type": "number", "required": true, "description": "当日发货总数(dispatch_lane='m4' 的发货记录数)" }, { "name": "shipment_rate", "type": "number", "required": true, "description": "发货率百分比(total_shipments / total_orders × 100,保留一位小数)" }, { "name": "peak_hour", "type": "string", "required": true, "description": "订单峰值时段,格式 HH:00" }, { "name": "peak_orders", "type": "number", "required": true, "description": "峰值时段订单数" } ] }, { "name": "categories", "type": "array", "required": true, "description": "时段列表,从 08:00 到当前小时(最晚 23:00),格式 ['08:00', '09:00', ...]" }, { "name": "orders", "type": "array", "required": true, "description": "各时段订单数,与 categories 一一对应" }, { "name": "shipments", "type": "array", "required": true, "description": "各时段发货数,与 categories 一一对应" } ] } ], "errors": [ { "code": "fail", "message": "缺少仓库上下文(token 中未解析到有效的 warehouseId),返回 { flag: 'fail', message: '缺少仓库上下文' }" } ] } ] }, { "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.loadWarehouses", "description": "index.loadWarehouses 接口", "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_。当前仅支持已按上述模式配置好的基础授权链接。", "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": [] }, { "method": "index.toOrder", "description": "根据运单号快速查询订单ID及其所属波次下所有订单ID列表。查询流程:1) 通过运单号查询 wms_order_express 表(status=1)获取 order_id 和 warehouse_id;2) 遍历多表(current/history/dispatch)获取 wave_id 和 wave_no;3) 若有有效波次则再遍历多表查询该波次下所有订单的 ID 列表。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号" } ], "response": [ { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "waves", "type": "array", "required": true, "description": "波次列表,无波次时为空数组。每项含 wave_id(波次ID,number)、wave_no(波次号,string)、order_ids(波次下所有订单ID列表,number[])" }, { "name": "waves[].wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "waves[].wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "waves[].order_ids", "type": "array", "required": true, "description": "该波次下所有订单的 ID 列表" } ], "errors": [ { "code": 405, "message": "运单号不能为空" }, { "code": 405, "message": "未找到该运单号对应的订单" } ] } ] }, { "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "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", "required": true, "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "required": true, "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "required": true, "description": "商品明细数组" }, { "name": "expresses", "type": "array", "required": true, "description": "运单信息数组,每个元素包含以下字段:waybill_code(运单号,string)、weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、logistics_code(实际物流公司编码,string)、logistics_name(实际物流公司名称,string)、logistics_interface_id(物流接口ID,number|null)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)、package_material_id(包材ID,number|null)、package_material_name_snapshot(包材名称快照,string|null)" }, { "name": "waybill_codes", "type": "array", "required": true, "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] }, { "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": "更新订单运单称重重量。支持两种模式:1) 订单模式(order_id>0):规则:订单仅一个运单时,直接写入该运单重量;多运单时,必须传 waybill_code 并按运单写入;团购波次批量设置同一重量到波次下所有订单运单,并返回拆单汇总信息(total_weight/split_count/splits/store_name/sys_logistics_name)。2) 运单号模式(order_id=0):从运单号反查订单与波次,散单/非团购波次仅更新单个运单重量,团购波次按 wave_no+business_key 批量设置并返回拆单汇总信息。", "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,必填且必须为数字。订单模式下为正整数,设为0时切换为运单号模式(需配合 waybill_code 使用)。" }, { "name": "waybill_code", "type": "string", "required": false, "source": "body", "description": "运单号。订单模式下:订单仅一个运单时可不传且会被忽略,多运单时必填并需匹配订单下运单。运单号模式(order_id=0)下必填。" }, { "name": "weighing_weight", "type": "number|string", "required": true, "source": "body", "description": "称重重量(g),必填,必须大于 0,必须为正整数。" } ], "response": [ { "name": "order_id", "type": "number", "required": false, "description": "订单ID。订单模式及运单号散单模式返回。" }, { "name": "waybill_code", "type": "string", "required": false, "description": "写入重量的运单号。订单模式及运单号散单模式返回。" }, { "name": "weighing_weight", "type": "number", "required": true, "description": "已写入的称重重量(g)。" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次号。团购批量模式返回。" }, { "name": "business_key", "type": "string", "required": false, "description": "业务键。运单号团购批量模式返回。" }, { "name": "wave_id", "type": "number", "required": false, "description": "波次ID。团购批量模式返回。" }, { "name": "total_weight", "type": "number", "required": false, "description": "所有拆单重量累加(g)。团购批量模式返回。" }, { "name": "split_count", "type": "number", "required": false, "description": "waybill_code 非空的 business_key 数量。团购批量模式返回。" }, { "name": "splits", "type": "array", "required": false, "description": "按 business_key 分组的拆单明细。每项含 business_key(业务键)、weighing_weight(该拆单累加重量)、waybill_code(代表运单号)。团购批量模式返回。" }, { "name": "store_name", "type": "string", "required": false, "description": "货主名称(订单 shop_nick)。团购批量模式返回。" }, { "name": "sys_logistics_name", "type": "string", "required": false, "description": "系统快递名称。团购批量模式返回。" } ], "errors": [ { "code": 400, "message": "order_id 必填且必须为数字(订单模式下为正整数;设为 0 时为运单号模式)" }, { "code": 400, "message": "weighing_weight 必填" }, { "code": 400, "message": "weighing_weight 格式非法,必须为正整数(单位 g)" }, { "code": 400, "message": "weighing_weight 必须大于 0" }, { "code": 400, "message": "多运单订单必须传入 waybill_code" }, { "code": 404, "message": "未找到有效的订单运单记录" }, { "code": 404, "message": "waybill_code 未匹配到该订单下的运单记录" }, { "code": 404, "message": "运单号不存在(运单号模式)" }, { "code": 404, "message": "运单号对应的订单不存在(运单号模式)" }, { "code": 404, "message": "波次下未找到订单(团购批量模式)" }, { "code": 500, "message": "运单模型未初始化" }, { "code": 500, "message": "订单模型未初始化" }, { "code": 500, "message": "波次模型未初始化" }, { "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、export_mode/exportMode;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 一致" }, { "name": "export_mode / exportMode", "type": "string", "required": false, "source": "body", "description": "导出模式:waybill(默认,按运单展开,items_detail 列汇总商品)或 item(按商品明细展开,每商品一行);支持 export_mode 与 exportMode 两种写法" } ], "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "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": "订单不存在或不属于当前仓库" } ] }, { "method": "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", "required": true, "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "required": true, "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "required": true, "description": "商品明细数组" }, { "name": "expresses", "type": "array", "required": true, "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "required": true, "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] } ] }, { "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "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": "同步待处理订单(异步模式)。提交后立即返回 request_id,后台异步执行同步流程。调用方需通过 syncOrderIdsProgress 接口轮询任务进度与最终结果。后台会按 create_channel 分组并行派发同步任务(QM/MANUAL/API);单订单失败静默写入错误状态,不影响整批结果;已同步完成(sync_status='fin')的订单会被自动跳过防重复。SN管理订单和快递未分配订单在同步前即被标记为 error 并跳过派发。派发成功后会更新 sync_status='fin',防止重复同步。", "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": "request_id", "type": "string", "required": true, "description": "异步任务唯一标识,用于 syncOrderIdsProgress 查询进度" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" } ], "errors": [ { "code": 400, "message": "order_ids 不能为空或格式错误" } ] }, { "method": "order.pendingOrder.syncOrderIdsProgress", "description": "查询 syncOrderIds 异步任务的进度与结果。", "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", "description": "syncOrderIds 返回的 request_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": "request_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": "total_count", "type": "number", "required": false, "description": "总订单数" }, { "name": "processed_count", "type": "number", "required": false, "description": "已处理订单数" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库 ID" }, { "name": "result", "type": "object", "required": false, "description": "完成时的同步结果(success 状态时存在),含 success_count / failed_count / dispatch_results 等" }, { "name": "error", "type": "string", "required": false, "description": "失败时的错误信息(failed 状态时存在)" }, { "name": "update_time", "type": "number", "required": false, "description": "最后更新时间戳" } ], "errors": [ { "code": 400, "message": "request_id 参数不能为空" } ] }, { "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": 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": "快递编码 不存在" } ] }, { "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": "shop_nick", "type": "string", "required": false, "source": "body", "description": "店铺名称(自定义),最大长度 200" }, { "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.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 的收件人信息字段", "未识别到的字段返回空字符串" ] }, { "method": "order.pendingOrder.updateAddress", "description": "批量修改待处理订单的收件地址信息。地址字段修改仅允许 post_status='none'(未分配快递)的订单;至少需要提供一个地址字段(name/mobile/tel/zip_code/province/city/area/town/detail_address),空值和纯空白会被忽略。更新成功后写入操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "收件人姓名" }, { "name": "mobile", "type": "string", "required": false, "source": "body", "description": "收件人手机号" }, { "name": "tel", "type": "string", "required": false, "source": "body", "description": "收件人电话" }, { "name": "zip_code", "type": "string", "required": false, "source": "body", "description": "邮编" }, { "name": "province", "type": "string", "required": false, "source": "body", "description": "省份" }, { "name": "city", "type": "string", "required": false, "source": "body", "description": "城市" }, { "name": "area", "type": "string", "required": false, "source": "body", "description": "区/县" }, { "name": "town", "type": "string", "required": false, "source": "body", "description": "镇/街道" }, { "name": "detail_address", "type": "string", "required": false, "source": "body", "description": "详细地址" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新的订单行数(地址更新行数)。仅统计 post_status='none' 的订单地址更新成功数。" }, { "name": "ids", "type": "number[]", "required": true, "description": "请求的订单ID数组(原样返回)" } ], "errors": [ { "code": 400, "message": "ids 不能为空" }, { "code": 400, "message": "至少需要提供一个地址字段进行修改" }, { "code": 400, "message": "仅允许修改 post_status='none'(未分配快递)的订单;若订单已分配快递则地址更新行数为 0,不会报错但实际无更新。" } ] }, { "method": "order.pendingOrder.updateRemark", "description": "批量修改待处理订单的备注(remark)。不受 post_status 限制,可对所有状态的订单生效。更新成功后写入操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" }, { "name": "remark", "type": "string", "required": true, "source": "body", "description": "订单备注/留言,最大500字符,必填" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新的订单行数" }, { "name": "ids", "type": "number[]", "required": true, "description": "请求的订单ID数组(原样返回)" } ], "errors": [ { "code": 400, "message": "ids 不能为空" }, { "code": 400, "message": "ids 仅支持正整数数组" }, { "code": 400, "message": "remark 不能为空" } ] }, { "method": "order.pendingOrder.batchIntercept", "description": "批量提交订单拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'requested' 并写入操作日志(ORDER_INTERCEPT_REQUEST)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 recheck_intercept_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量拦截任务已提交。' 或 '批量拦截任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchInterceptTaskProgress", "description": "查询批量拦截任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已拦截订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、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" } ], "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(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "intercepted_order_count", "type": "number", "required": false, "description": "已拦截订单数(submitted/running/success/failed 时返回)" }, { "name": "intercepted_order_ids", "type": "number[]", "required": false, "description": "已拦截订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_INTERCEPT_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] }, { "method": "order.pendingOrder.batchLock", "description": "批量提交订单锁定请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 lock_status 更新为 'warehouse' 并写入操作日志(ORDER_LOCK)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 order_lock_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量锁定任务已提交。' 或 '批量锁定任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchLockTaskProgress", "description": "查询批量锁定任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已锁定订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、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" } ], "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(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "locked_order_count", "type": "number", "required": false, "description": "已锁定订单数(submitted/running/success/failed 时返回)" }, { "name": "locked_order_ids", "type": "number[]", "required": false, "description": "已锁定订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_LOCK_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] }, { "method": "order.pendingOrder.batchUnlock", "description": "批量提交订单解锁请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 lock_status 更新为 'none' 并写入操作日志(ORDER_UNLOCK)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 order_unlock_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量解锁任务已提交。' 或 '批量解锁任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchUnlockTaskProgress", "description": "查询批量解锁任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已解锁订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、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" } ], "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(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "unlocked_order_count", "type": "number", "required": false, "description": "已解锁订单数(submitted/running/success/failed 时返回)" }, { "name": "unlocked_order_ids", "type": "number[]", "required": false, "description": "已解锁订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_UNLOCK_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] }, { "method": "order.pendingOrder.batchUnintercept", "description": "批量提交解除拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'none' 并写入操作日志(ORDER_INTERCEPT_CANCEL)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 order_unintercept_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量解除拦截任务已提交。' 或 '批量解除拦截任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchUninterceptTaskProgress", "description": "查询批量解除拦截任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已解除拦截订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、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" } ], "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(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "unintercepted_order_count", "type": "number", "required": false, "description": "已解除拦截订单数(submitted/running/success/failed 时返回)" }, { "name": "unintercepted_order_ids", "type": "number[]", "required": false, "description": "已解除拦截订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_UNINTERCEPT_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] } ] }, { "groupName": "订单复核模块", "module": "order.recheckOrder", "list": [ { "method": "order.recheckOrder.scanOrder", "description": "扫描关键词并返回以波次为单位的复核视图。支持运单号、波次号、车号三种匹配模式。运单号/波次号命中(散单)返回扁平化订单列表 list_type='single',车号命中(团单)返回嵌套波次结构 list_type='group'。运单号命中但订单无波次信息时,退回单订单详情模式(list 每项含 detail/items/expresses/logs)。所有模式的 list[] 每项均附带 items_weight(订单商品总重量)与 suggested_package_material(推荐包材信息,无推荐时为 null)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword / value / waybill_no / waybillCode / waybill_code / wave_no / waveNo / cart_code / cartCode", "type": "string", "required": true, "source": "body|query", "description": "扫描关键词;匹配优先级:运单号 → 波次号 → 车号。支持别名 waybillCode/waybill_code(运单号)、waveNo(波次号)、cartCode(车号)" } ], "response": [ { "name": "match_type", "type": "string", "required": true, "description": "命中类型:waybill(运单号命中)/ wave(波次号命中)/ cart(车号命中)" }, { "name": "list_type", "type": "string", "required": true, "description": "列表模式:single(散单扁平列表)/ group(团购嵌套波次列表)" }, { "name": "waybill_no", "type": "string", "required": false, "description": "仅 waybill 命中时返回,匹配到的运单号" }, { "name": "task_id", "type": "number|null", "required": false, "description": "散单有波次信息时返回(来自拣货任务表 wms_wave_pick_task.id),团单车号命中时返回 cartMatchContext 中的任务 ID" }, { "name": "picker_id", "type": "number|null", "required": false, "description": "仅散单模式(有波次信息时)返回,拣货人ID(来自 wms_wave_pick_task.pick_user_id)" }, { "name": "picker_name", "type": "string", "required": false, "description": "仅散单模式(有波次信息时)返回,拣货人名称(来自 wms_wave_pick_task.pick_user_name)" }, { "name": "wave_id", "type": "number", "required": false, "description": "仅散单模式(有波次信息时)返回,波次ID" }, { "name": "wave_no", "type": "string", "required": false, "description": "仅散单模式(有波次信息时)返回,波次号" }, { "name": "wave_type", "type": "number", "required": false, "description": "仅散单模式(有波次信息时)返回,波次类型编码(来自 wms_wave_batch.wave_type)" }, { "name": "pick_mode", "type": "number", "required": false, "description": "拣货模式:1-团购小波次 2-散单单品单件 3-散单先拣后分 4-边拣边分 5-团购大波次。散单模式在顶层返回,团购模式在每个波次视图项内返回" }, { "name": "strategy_id", "type": "number|null", "required": false, "description": "仅散单模式返回,波次策略ID" }, { "name": "strategy_name", "type": "string", "required": false, "description": "仅散单模式返回,波次策略名称" }, { "name": "total_orders", "type": "number", "required": false, "description": "仅散单模式返回,波次内订单总数" }, { "name": "reviewed_count", "type": "number", "required": false, "description": "仅散单模式返回,已复核订单数" }, { "name": "unreviewed_count", "type": "number", "required": false, "description": "仅散单模式返回,未复核订单数" }, { "name": "list", "type": "array", "required": true, "description": "统一列表输出。散单模式(list_type=single)有波次信息时:扁平订单数组;无波次信息时退回单订单详情模式(每项含 detail、items、expresses、logs)。团购模式(list_type=group):波次视图数组(每项含 wave_id、wave_no、wave_type、wave_status、total_orders、processed_orders、creator、create_time、update_time、order_count、pick_mode、box_no、order_ids、orders_detail、stocks[])。所有模式的 list[] 每项均附带 items_weight(订单商品总重量,单位 g)与 suggested_package_material(推荐包材信息,无推荐时为 null)。", "children": [ { "name": "order_id", "type": "number", "description": "[散单有波次] 订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "[散单有波次] 发货单号(优先 delivery_order_code,其次 pre_delivery_order_code)" }, { "name": "waybill_no", "type": "string", "description": "[散单有波次] 运单号(从 order_express 关联表查询)" }, { "name": "pick_status", "type": "string", "description": "[散单有波次] 拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "[散单有波次] 是否已打印(print_status === 'fin')" }, { "name": "is_reviewed", "type": "boolean", "description": "[散单有波次] 是否已复核(recheck_status === 'fin')" }, { "name": "shop_nick", "type": "string", "description": "[散单有波次] 店铺昵称" }, { "name": "items_count", "type": "number", "description": "[散单有波次] 商品种类数" }, { "name": "wave_index", "type": "number", "description": "[散单有波次] 波次内序号(优先从 wms_order_wave_index 读取真实 wave_index,若无则降级为数组临时序号)" }, { "name": "recheck_status", "type": "string", "description": "[散单有波次] 复核状态" }, { "name": "wave_id", "type": "number", "description": "[散单有波次] 波次ID" }, { "name": "wave_no", "type": "string", "description": "[散单有波次] 波次号" }, { "name": "order_type", "type": "string", "description": "[散单有波次] 订单类型" }, { "name": "status", "type": "number", "description": "[散单有波次] 订单状态码" }, { "name": "logistics_name", "type": "string", "description": "[散单有波次] 物流名称" }, { "name": "store_remark", "type": "string", "description": "[散单有波次] 货主备注(来自 wms_store_warehouse.store_remask)" }, { "name": "intercept_status", "type": "string", "description": "[散单有波次] 拦截状态(requested / intercepted_at_warehouse / 空字符串)" }, { "name": "stock", "type": "array", "description": "[散单有波次] 订单商品库存明细", "children": [ { "name": "stock_id", "type": "number", "description": "库存商品ID" }, { "name": "item_code", "type": "string", "description": "商品编码" }, { "name": "item_name", "type": "string", "description": "商品名称" }, { "name": "sku_property", "type": "string", "description": "SKU属性(来自 wms_stock_warehouse.sku_property)" }, { "name": "packing_requirements", "type": "string", "description": "包装要求(来自 wms_stock_warehouse.packing_requirements)" }, { "name": "barcodes", "type": "array", "description": "条码列表(来自 wms_stock_barcodes,若无则回退为 [item_code])" }, { "name": "images", "type": "array", "description": "商品图片URL列表(来自 file_reference 关联查询)" }, { "name": "plan_qty", "type": "number", "description": "计划数量" }, { "name": "has_shared_barcode", "type": "boolean", "description": "是否存在共享条码(同一条码出现在多个不同 stock_id 中)" } ] }, { "name": "detail", "type": "object", "description": "[散单无波次回退] 订单详情对象(来自 order.detail 方法返回)" }, { "name": "items", "type": "array", "description": "[散单无波次回退] 订单商品明细数组" }, { "name": "expresses", "type": "array", "description": "[散单无波次回退] 订单快递信息数组" }, { "name": "logs", "type": "array", "description": "[散单无波次回退] 订单操作日志数组" }, { "name": "wave_id", "type": "number", "description": "[团购波次项] 波次ID" }, { "name": "wave_no", "type": "string", "description": "[团购波次项] 波次号" }, { "name": "wave_type", "type": "number", "description": "[团购波次项] 波次类型编码" }, { "name": "wave_status", "type": "number", "description": "[团购波次项] 波次状态码" }, { "name": "total_orders", "type": "number", "description": "[团购波次项] 波次内订单总数(来自 wms_wave_batch)" }, { "name": "processed_orders", "type": "number", "description": "[团购波次项] 已处理订单数(来自 wms_wave_batch)" }, { "name": "creator", "type": "string", "description": "[团购波次项] 波次创建人" }, { "name": "create_time", "type": "string", "description": "[团购波次项] 波次创建时间" }, { "name": "update_time", "type": "string", "description": "[团购波次项] 波次更新时间" }, { "name": "order_count", "type": "number", "description": "[团购波次项] 波次下实际订单数(COUNT 查询)" }, { "name": "pick_mode", "type": "number", "description": "[团购波次项] 拣货模式(以拣货任务级别为准)" }, { "name": "box_no", "type": "number", "description": "[团购波次项] 箱号(来自 wms_wave_pick_task_wave.box_no)" }, { "name": "order_ids", "type": "array", "description": "[团购波次项] 非拦截订单 ID 数组,仅 list_type='group' 时返回" }, { "name": "orders_detail", "type": "array", "description": "[团购波次项] 非拦截订单详细列表,每项含 order_id、delivery_order_code、waybill_no、pick_status、is_printed、is_reviewed、recheck_status、shop_nick、items_count、wave_index、intercept_status,仅 list_type='group' 时返回", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "waybill_no", "type": "string", "description": "运单号" }, { "name": "pick_status", "type": "string", "description": "拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "是否已打印(print_status === 'fin')" }, { "name": "is_reviewed", "type": "boolean", "description": "是否已复核(recheck_status === 'fin')" }, { "name": "recheck_status", "type": "string", "description": "复核状态" }, { "name": "shop_nick", "type": "string", "description": "店铺昵称" }, { "name": "items_count", "type": "number", "description": "商品种类数" }, { "name": "wave_index", "type": "number", "description": "波次内序号" }, { "name": "intercept_status", "type": "string", "description": "拦截状态(requested / intercepted_at_warehouse / 空字符串)" } ] }, { "name": "orders", "type": "array", "description": "[团购波次项] 波次下订单列表(结构与散单有波次模式订单项一致,含 order_id/delivery_order_code/waybill_no/pick_status/is_printed/is_reviewed/shop_nick/items_count/wave_index/recheck_status/order_type/status/logistics_name/store_remark/intercept_status/stock[])", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "waybill_no", "type": "string", "description": "运单号" }, { "name": "pick_status", "type": "string", "description": "拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "是否已打印" }, { "name": "is_reviewed", "type": "boolean", "description": "是否已复核" }, { "name": "shop_nick", "type": "string", "description": "店铺昵称" }, { "name": "items_count", "type": "number", "description": "商品种类数" }, { "name": "wave_index", "type": "number", "description": "波次内序号" }, { "name": "recheck_status", "type": "string", "description": "复核状态" }, { "name": "order_type", "type": "string", "description": "订单类型" }, { "name": "status", "type": "number", "description": "订单状态码" }, { "name": "logistics_name", "type": "string", "description": "物流名称" }, { "name": "store_remark", "type": "string", "description": "货主备注" }, { "name": "intercept_status", "type": "string", "description": "拦截状态" }, { "name": "stock", "type": "array", "description": "商品库存明细(结构同散单模式)" } ] }, { "name": "items_weight", "type": "number|null", "description": "[全模式] 订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量)" }, { "name": "suggested_package_material", "type": "object|null", "description": "[全模式] 推荐包材信息。根据订单商品结构(items_hash + items_crc)匹配 wms_package_material_item_relation 历史绑定记录,按 bind_count 降序取最优匹配。若 items_hash 为空或无匹配记录则为 null。散单模式每个订单对象包含,团购模式每个波次对象包含;团购模式以波次内首个正常订单的商品指纹匹配包材推荐", "children": [ { "name": "id", "type": "number", "description": "包材ID(wms_package_material.id)" }, { "name": "code", "type": "string", "description": "包材编码" }, { "name": "name", "type": "string", "description": "包材名称" }, { "name": "spec", "type": "string", "description": "包材规格" }, { "name": "type", "type": "string", "description": "包材类型" }, { "name": "weight", "type": "number", "description": "包材自身重量(g)" }, { "name": "length", "type": "number", "description": "长(cm)" }, { "name": "width", "type": "number", "description": "宽(cm)" }, { "name": "height", "type": "number", "description": "高(cm)" }, { "name": "bind_count", "type": "number", "description": "历史绑定次数(推荐排序依据)" } ] } ] } ], "errors": [ { "code": 400, "message": "扫描关键词不能为空" }, { "code": 404, "message": "未找到对应订单" }, { "code": 400, "message": "订单未拣货,不允许复核。" } ] }, { "method": "order.recheckOrder.confirmRecheck", "description": "按订单 ID 确认复核并记录复核任务到 wms_recheck_task(入参兼容 id/orderId)。确认复核后,若该订单所属波次拣货任务下所有订单均已复核完成,则自动解绑车任务:清空 wms_wave_pick_task 的车绑定信息(current_cart_id、current_cart_code_snapshot)、停用 wms_pick_task_cart_binding 绑定记录(is_active=0 并记录解绑人和时间)并释放 wms_pick_cart(清空 current_task_id、bind_user_id)。解绑失败仅记录 warn 日志,不影响复核主流程。", "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", "required": true, "description": "订单 ID" }, { "name": "waybill_no", "type": "string", "required": true, "description": "运单号" }, { "name": "recheck_status", "type": "string", "required": true, "description": "复核结果状态(固定为 'fin')" }, { "name": "recheck_time", "type": "string", "required": true, "description": "复核时间(ISO 字符串)" }, { "name": "review_no", "type": "string", "required": true, "description": "复核任务编号" } ], "errors": [ { "code": 400, "message": "订单ID不能为空" }, { "code": 404, "message": "未找到对应订单" }, { "code": 400, "message": "订单未拣货,不允许复核。" } ] }, { "method": "order.recheckOrder.confirmIntercept", "description": "确认拦截:通过订单ID直接匹配订单,将其拦截状态更新为 intercepted_at_warehouse(仓库已拦截)。仅拦截当前指定订单,不波及波次内其他订单。操作成功后写入操作日志(ORDER_INTERCEPT_CONFIRM),日志写入失败不影响主流程。", "isNeedAuth": false, "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": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "order_no", "type": "string", "required": true, "description": "订单号(优先 delivery_order_code,其次 pre_delivery_order_code)" }, { "name": "intercept_status", "type": "string", "required": true, "description": "拦截状态(固定为 'intercepted_at_warehouse')" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间(ISO 字符串)" } ], "errors": [ { "code": 400, "message": "order_id 无效", "description": "order_id 无效(为空或非正整数)" }, { "code": 404, "message": "未找到对应订单" }, { "code": 500, "message": "拦截状态更新失败,请稍后重试", "description": "数据库更新影响行数为 0 时返回" } ] }, { "method": "order.recheckOrder.recheckOrderList", "description": "复核订单列表查询,通过入参 list_type 区分散单模式与团购模式。散单模式(single,默认)返回待复核订单列表(每项为一个订单,排除 pick_status='none' 和 recheck_status='fin'),团购模式(group)返回波次维度的复核汇总列表(每项为一个波次及其订单复核统计,含 review_assignment_status 计算字段)。统一使用 list 字段名输出,均支持分页与筛选。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "list_type", "type": "string", "required": false, "source": "body", "description": "列表模式:single(散单模式,默认)/ group(团购模式)" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件。散单模式支持 keyword(运单号/订单号模糊搜索)、wave_no(精确匹配)、recheck_status、pick_status;团购模式支持 wave_no(模糊搜索)、wave_type、wave_status" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize(默认 page=1, pageSize=20)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "散单模式(list_type=single):订单数组,每项含 order_id、delivery_order_code、order_type、wave_id、wave_no、pick_status、recheck_status、shop_nick、logistics_name、items_count、items_total、status、create_at、pick_time、recheck_time。团购模式(list_type=group):波次汇总数组,每项含 wave_id、wave_no、wave_type、wave_status、total_orders、processed_orders、creator、create_time、update_time、order_count、reviewed_count、unreviewed_count、review_assignment_status(unreviewed/partially_reviewed/reviewed)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ], "errors": [] }, { "method": "order.recheckOrder.scanTask", "description": "按拣货任务 ID 拉取复核扫描视图。根据任务的 pick_mode 区分散单/团单模式,返回与 scanOrder 一致的数据结构,用于前端刷新数据。散单模式(pick_mode 2/3/4)扁平化任务下所有波次的订单列表(按 order_id 去重,未复核优先、wave_index 升序),顶层携带拣货人/任务等汇总信息(包括 picker_id、picker_name、pick_mode、total_orders、reviewed_count、unreviewed_count);团购模式(pick_mode 1/5)返回任务下所有团购波次及订单的分组列表(list_type='group')。", "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(对应 wms_wave_pick_task.id)" } ], "response": [ { "name": "match_type", "type": "string", "required": true, "description": "固定为 'task',表示通过任务 ID 匹配" }, { "name": "list_type", "type": "string", "required": true, "description": "列表模式:single(散单扁平列表)/ group(团购嵌套波次列表),由拣货任务的 pick_mode 决定" }, { "name": "task_id", "type": "number", "required": true, "description": "拣货任务 ID" }, { "name": "picker_id", "type": "number|null", "required": false, "description": "拣货人 ID(来自 wms_wave_pick_task.pick_user_id),散单模式返回" }, { "name": "picker_name", "type": "string", "required": false, "description": "拣货人名称(来自 wms_wave_pick_task.pick_user_name),散单模式返回" }, { "name": "pick_mode", "type": "number", "required": false, "description": "拣货模式:1-团购小波次 2-散单单品单件 3-散单先拣后分 4-边拣边分 5-团购大波次" }, { "name": "wave_id", "type": "number", "required": false, "description": "散单模式固定为 0,团购模式不返回" }, { "name": "wave_no", "type": "string", "required": false, "description": "散单模式固定为空字符串,团购模式不返回" }, { "name": "wave_type", "type": "number", "required": false, "description": "波次类型编码(取任务下第一个有效波次的 wave_type),散单模式返回" }, { "name": "strategy_id", "type": "number|null", "required": false, "description": "散单模式固定为 null(任务级别不绑定单一策略)" }, { "name": "strategy_name", "type": "string", "required": false, "description": "散单模式固定为空字符串(任务级别不绑定单一策略)" }, { "name": "total_orders", "type": "number", "required": false, "description": "任务下订单总数(去重后),散单模式返回" }, { "name": "reviewed_count", "type": "number", "required": false, "description": "已复核订单数,散单模式返回" }, { "name": "unreviewed_count", "type": "number", "required": false, "description": "未复核订单数,散单模式返回" }, { "name": "list", "type": "array", "required": true, "description": "统一列表输出。散单模式(list_type=single):扁平订单数组(每项结构与 scanOrder 散单有波次模式一致,含 order_id/delivery_order_code/waybill_no/pick_status/is_printed/is_reviewed/shop_nick/items_count/wave_index/recheck_status/order_type/status/logistics_name/store_remark/intercept_status/stock[])。团购模式(list_type=group):波次视图数组(结构与 scanOrder 团购模式一致,每项含 wave_id/wave_no/wave_type/wave_status/total_orders/processed_orders/creator/create_time/update_time/order_count/pick_mode/box_no/orders[])", "children": [ { "name": "order_id", "type": "number", "description": "[散单] 订单 ID" }, { "name": "delivery_order_code", "type": "string", "description": "[散单] 发货单号" }, { "name": "waybill_no", "type": "string", "description": "[散单] 运单号" }, { "name": "pick_status", "type": "string", "description": "[散单] 拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "[散单] 是否已打印" }, { "name": "is_reviewed", "type": "boolean", "description": "[散单] 是否已复核" }, { "name": "shop_nick", "type": "string", "description": "[散单] 店铺昵称" }, { "name": "items_count", "type": "number", "description": "[散单] 商品种类数" }, { "name": "wave_index", "type": "number", "description": "[散单] 波次内序号" }, { "name": "recheck_status", "type": "string", "description": "[散单] 复核状态" }, { "name": "wave_id", "type": "number", "description": "[散单] 波次 ID" }, { "name": "wave_no", "type": "string", "description": "[散单] 波次号" }, { "name": "order_type", "type": "string", "description": "[散单] 订单类型" }, { "name": "status", "type": "number", "description": "[散单] 订单状态码" }, { "name": "logistics_name", "type": "string", "description": "[散单] 物流名称" }, { "name": "store_remark", "type": "string", "description": "[散单] 货主备注" }, { "name": "intercept_status", "type": "string", "description": "[散单] 拦截状态" }, { "name": "stock", "type": "array", "description": "[散单] 订单商品库存明细(含 stock_id/item_code/item_name/sku_property/packing_requirements/barcodes/images/plan_qty/has_shared_barcode)" }, { "name": "wave_id", "type": "number", "description": "[团购波次项] 波次 ID" }, { "name": "wave_no", "type": "string", "description": "[团购波次项] 波次号" }, { "name": "wave_type", "type": "number", "description": "[团购波次项] 波次类型编码" }, { "name": "wave_status", "type": "number", "description": "[团购波次项] 波次状态码" }, { "name": "total_orders", "type": "number", "description": "[团购波次项] 波次内订单总数" }, { "name": "processed_orders", "type": "number", "description": "[团购波次项] 已处理订单数" }, { "name": "creator", "type": "string", "description": "[团购波次项] 波次创建人" }, { "name": "create_time", "type": "string", "description": "[团购波次项] 波次创建时间" }, { "name": "update_time", "type": "string", "description": "[团购波次项] 波次更新时间" }, { "name": "order_count", "type": "number", "description": "[团购波次项] 波次下实际订单数" }, { "name": "pick_mode", "type": "number", "description": "[团购波次项] 拣货模式" }, { "name": "box_no", "type": "number", "description": "[团购波次项] 箱号" }, { "name": "orders", "type": "array", "description": "[团购波次项] 波次下订单列表(结构与散单模式订单项一致)" } ] } ], "errors": [ { "code": 400, "message": "task_id 无效", "description": "task_id 为空或非正整数" }, { "code": 404, "message": "未找到对应拣货任务" } ] }, { "method": "order.recheckOrder.batchQuickRecheck", "description": "批量快捷复核:传入订单 IDs 列表,对每个有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string", "required": true, "source": "body|query", "description": "订单 ID 列表,支持数组或以逗号分隔的字符串" } ], "response": [ { "name": "success", "type": "array", "required": true, "description": "复核成功的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" } ] }, { "name": "failed", "type": "array", "required": true, "description": "复核失败的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "reason", "type": "string", "description": "失败原因(未分配储位 / 没有分配快递 / 没有同步 / 已拦截 / 未找到对应订单 / 复核失败: xxx)" } ] }, { "name": "success_count", "type": "number", "required": true, "description": "成功数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "失败数量" } ], "errors": [ { "code": 400, "message": "订单ID列表不能为空" } ] }, { "method": "order.recheckOrder.queryRecheckOrderSingleList", "description": "散单模式复核列表查询,按订单维度返回待复核订单(排除 pick_status='none' 和 recheck_status='fin'),支持分页与关键词/波次号/复核状态筛选。与 recheckOrderList 不同:本方法仅处理散单模式,不包含团购分支。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件。支持 keyword(运单号/订单号模糊搜索)、wave_no(精确匹配)、recheck_status、pick_status" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize(默认 page=1, pageSize=20)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "散单复核订单列表,每项含 order_id、delivery_order_code、order_type、wave_id、wave_no、pick_status、recheck_status、shop_nick、logistics_name、items_count、items_total、items_weight、weight_type、waybill_code、status、create_at、recheck_time" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ], "errors": [] } ] }, { "groupName": "订单打包模块", "module": "order.packing", "list": [ { "method": "order.packing.list", "description": "打包任务列表查询。按仓库维度查询打包任务,支持分页、筛选、排序。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "description": "分页参数 { page, pageSize },默认 page=1, pageSize=20", "children": [ { "name": "page", "type": "number", "required": false, "description": "页码" }, { "name": "pageSize", "type": "number", "required": false, "description": "每页条数" } ] }, { "name": "sort", "type": "object", "required": false, "description": "排序参数 { sortField, sortOrder }", "children": [ { "name": "sortField", "type": "string", "required": false, "description": "排序字段,支持:id、order_id、workbench_id、wave_id、pack_quantity、pack_mode、status、start_time、end_time、create_time、update_time" }, { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向:ASC / DESC,默认 DESC" } ] }, { "name": "where", "type": "object", "required": false, "description": "筛选条件", "children": [ { "name": "status", "type": "number", "required": false, "description": "任务状态:0=待处理 1=打包中 2=已完成 3=异常" }, { "name": "pack_mode", "type": "number", "required": false, "description": "打包模式:1=散单 2=团购" }, { "name": "waybill_code", "type": "string", "required": false, "description": "运单号(模糊匹配)" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次号(模糊匹配)" }, { "name": "order_id", "type": "number", "required": false, "description": "订单ID(精确匹配)" }, { "name": "workbench_id", "type": "number", "required": false, "description": "工作台ID(精确匹配)" }, { "name": "quickWhere", "type": "string", "required": false, "description": "快捷搜索:波次号模糊匹配 + 运单号通过 express→order→wave 链路解析" }, { "name": "start_time_start", "type": "string", "required": false, "description": "开始打包时间范围起始(ISO 8601)" }, { "name": "start_time_end", "type": "string", "required": false, "description": "开始打包时间范围结束(ISO 8601)" }, { "name": "has_video", "type": "number", "required": false, "description": "是否包含录像:1=有录像 2=无录像" }, { "name": "video_enable", "type": "number", "required": false, "description": "录像是否可用:1=可用(存在 video_url 非空且 status!=failed 的记录) 2=不可用" } ] } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "打包任务列表,每项含 id、order_id、warehouse_id、workbench_id、wave_id、wave_no、waybill_code、pack_quantity、item_quantity、sku_count、pack_mode、status、start_time、end_time、operator_text、device_ids、remark、meta、create_time、update_time、workbench_name、workbench_type、workbench_barcode、has_video、video_enable、videos[]、expresses[]" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ], "errors": [] }, { "method": "order.packing.get", "description": "打包任务详情查询。按 id + warehouse_id 查询单条打包任务记录,含工作台、视频和运单关联信息。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "打包任务详情,含 id、order_id、warehouse_id、workbench_id、wave_id、wave_no、waybill_code、pack_quantity、item_quantity、sku_count、pack_mode、status、start_time、end_time、operator_text、device_ids、remark、meta、create_time、update_time、workbench_name、workbench_type、workbench_barcode、has_video、video_enable、videos[]、expresses[]" } ], "errors": [ { "code": 400, "description": "参数校验失败(如缺少 id)" }, { "code": 404, "description": "打包任务不存在或无权访问" } ] }, { "method": "order.packing.setEndTime", "description": "设置打包任务结束时间。若任务状态不是已完成(2),则同步更新状态为已完成。前端默认值:若任务已有结束时间则默认为当前时间,否则默认为开始时间+5分钟。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" }, { "name": "end_time", "type": "string", "required": true, "description": "结束时间(ISO 8601 格式,如 2026-07-27T11:00:00.000Z)。前端默认值:若任务已有结束时间→当前时间;无结束时间→开始时间+5分钟" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" }, { "name": "end_time", "type": "string", "required": true, "description": "更新后的结束时间" }, { "name": "status", "type": "number", "required": true, "description": "更新后的任务状态" } ], "errors": [ { "code": 400, "description": "参数校验失败(如缺少 id 或 end_time、用户未绑定仓库)" }, { "code": 404, "description": "打包任务不存在或无权访问" } ] }, { "method": "order.packing.forceRecord", "description": "强制重新录制打包任务视频。将任务推送到录制电脑,通过打印服务触发重新录制。内部会重置视频状态为 created 并清空 video_url。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" } ], "response": [ { "name": "pack_task_id", "type": "number", "required": true, "description": "打包任务ID" }, { "name": "computer_id", "type": "number", "required": true, "description": "录制电脑ID" } ], "errors": [ { "code": 400, "description": "参数校验失败(如缺少 id、用户未绑定仓库、无录制电脑、录制电脑不在线)" }, { "code": 404, "description": "打包任务不存在或无权访问" }, { "code": 500, "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": "分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量g,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;若指定 return_order_ids=true 则额外包含 order_ids" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "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": "items_weight", "type": "number", "description": "订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null" }, { "name": "weight_type", "type": "string", "description": "重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)" }, { "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", "message": "未识别到当前仓库上下文或 where 中包含非法/禁止字段(如 warehouse_id)或存在别名冲突" }, { "code": "500", "message": "查询失败或内部错误" } ] }, { "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": "散单候选分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量g,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;返回的 group_count 均小于 same_order_quantity(或仓库配置的 min_group_order_fetch_quantity);若指定 return_order_ids=true 则额外包含 order_ids" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "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": "cart_name", "type": "string", "description": "拣货车名称(通过 current_cart_id 关联 wms_pick_cart 表获取,未绑定拣货车时为空字符串)" }, { "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": "wave_list", "type": "array", "description": "关联波次列表(通过 wms_wave_pick_task_wave 关联查询,按 id 升序排列)", "children": [ { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "box_no", "type": "number", "description": "框号" }, { "name": "status", "type": "number", "description": "波次关联状态:0-待拣 1-已拣 2-异常" }, { "name": "bind_time", "type": "string", "description": "绑定时间(ISO 字符串)" }, { "name": "pick_time", "type": "string", "description": "拣货完成时间(ISO 字符串)" } ] } ] }, { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "page_size", "type": "number", "required": true, "description": "每页大小" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.wave.wavePickTaskCancel", "description": "取消拣货任务(批量)。可取消的状态:0=待开始、1=拣货中、2=待复核(拣货完成)、3=已完成,状态9(已取消)或其他状态不允许取消。同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。对于status=2或3的任务,取消时会自动回退订单拣货状态:wms_wave_pick_task_order.pick_status(1→0)、order_delivery.pick_status(fin→padding)。入参仅支持 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", "required": false, "description": "成功取消的任务数量" }, { "name": "task_ids", "type": "array", "required": false, "description": "处理的任务ID数组(若后端返回)" }, { "name": "task_nos", "type": "array", "required": false, "description": "处理的任务编号数组(若后端返回)" }, { "name": "task_id", "type": "number", "required": false, "description": "任务ID(历史兼容,若后端仍返回)" }, { "name": "task_no", "type": "string", "required": false, "description": "任务编号(历史兼容,若后端仍返回)" } ], "errors": [ { "code": "400", "message": "任务状态不允许取消(仅允许status=0/1/2/3)或入参缺失" }, { "code": "403", "message": "仅允许取消本人创建的任务(wavePickTaskCancelSelf 接口)" }, { "code": "404", "message": "任务不存在" }, { "code": "500", "message": "内部错误或事务回滚失败" } ] }, { "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": "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": "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": "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ], "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ], "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "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", "required": true, "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "required": true, "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "required": true, "description": "商品明细数组" }, { "name": "expresses", "type": "array", "required": true, "description": "运单信息数组,每个元素包含以下字段:waybill_code(运单号,string)、weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、logistics_code(实际物流公司编码,string)、logistics_name(实际物流公司名称,string)、logistics_interface_id(物流接口ID,number|null)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)、package_material_id(包材ID,number|null)、package_material_name_snapshot(包材名称快照,string|null)" }, { "name": "waybill_codes", "type": "array", "required": true, "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] } ] }, { "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "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 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" }, { "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": "重量(单位 g)" } ] }, { "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": "内部错误" } ] }, { "method": "order.print.getOrderPrintData", "description": "按订单ID拉取平台打印中间态数据,与 getWavePlatformPrintData 返回结构一致。不限制打印锁定状态,所有订单(包括已锁定)统一返回。仓库ID统一从当前上下文获取,无需调用方传入。自动过滤快递未完全分配的订单(post_status !== 'fin'),返回 waveGroups(波次 -> 平台 -> 订单)结构。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids", "type": "array", "required": true, "source": "body", "description": "订单ID列表(支持数字或字符串,内部自动去重与归一化,必须为非空数组)" } ], "response": [ { "name": "summary", "type": "object", "required": true, "description": "汇总信息", "children": [ { "name": "total_waves", "type": "number", "required": true, "description": "通过过滤的波次总数" }, { "name": "total_orders", "type": "number", "required": true, "description": "所有平台下订单总数" }, { "name": "total_platforms", "type": "number", "required": true, "description": "所有波次内平台分组总数(累加)" } ] }, { "name": "wave_ids", "type": "array", "required": true, "description": "通过过滤的波次ID数组" }, { "name": "waveGroups", "type": "array", "required": true, "description": "主返回结构:按波次分组(波次 -> 平台 -> 订单)", "children": [ { "name": "wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "order_count", "type": "number", "required": true, "description": "该波次下订单总数" }, { "name": "platforms", "type": "array", "required": true, "description": "按平台和系统快递分组后的订单列表", "children": [ { "name": "platform", "type": "string", "required": true, "description": "平台编码" }, { "name": "platform_name", "type": "string", "required": true, "description": "平台名称" }, { "name": "order_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": "orders", "type": "array", "required": true, "description": "该分组内的订单列表(逐单中间态)", "children": [ { "name": "wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "order_no", "type": "string", "required": true, "description": "订单号(delivery_order_code 或 source_order_codes)" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "platform", "type": "string", "required": true, "description": "平台编码" }, { "name": "platform_name", "type": "string", "required": true, "description": "平台名称" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "print_data", "type": "object", "required": true, "description": "打印中间态(详见 printer_data_builder.buildPlatformRequestSkeleton 输出)" } ] } ] } ] }, { "name": "ext", "type": "object", "required": true, "description": "扩展字段", "children": [ { "name": "missing_order_ids", "type": "array", "required": true, "description": "传入但数据库中不存在的 order_id 列表" }, { "name": "filtered_order_ids", "type": "array", "required": true, "description": "被过滤掉的订单(快递未完全分配),每项含 order_id、reason" } ] } ], "errors": [ { "code": "400", "message": "order_ids 必填,且必须为非空数组", "description": "order_ids 必填,且必须为非空数组" }, { "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(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" }, { "name": "subject_config.auto_outbound_rules", "type": "object", "required": true, "description": "自动出库规则配置。全部条件满足时自动标记待出库" }, { "name": "subject_config.auto_outbound_rules.enabled", "type": "boolean", "required": true, "description": "是否启用自动出库,默认 false" }, { "name": "subject_config.auto_outbound_rules.require_recheck", "type": "boolean", "required": true, "description": "是否要求已复核(recheck_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pack", "type": "boolean", "required": true, "description": "是否要求已打包(pack_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_weigh", "type": "boolean", "required": true, "description": "是否要求已称重(weighing_weight>0),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_sync", "type": "boolean", "required": true, "description": "是否要求已同步(sync_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_print", "type": "boolean", "required": true, "description": "是否要求已打印(print_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pick", "type": "boolean", "required": true, "description": "是否要求已拣货(pick_status=fin),默认 true" }, { "name": "subject_config.sender_name", "type": "string", "required": false, "description": "仓库默认发件人姓名,默认空字符串" }, { "name": "subject_config.sender_tel", "type": "string", "required": false, "description": "仓库默认发件人联系电话,默认空字符串" }, { "name": "subject_config.province_name", "type": "string", "required": false, "description": "仓库默认发件省份,默认空字符串" }, { "name": "subject_config.city_name", "type": "string", "required": false, "description": "仓库默认发件城市,默认空字符串" }, { "name": "subject_config.district_name", "type": "string", "required": false, "description": "仓库默认发件区/县,默认空字符串" }, { "name": "subject_config.town_name", "type": "string", "required": false, "description": "仓库默认发件镇/街道,默认空字符串" }, { "name": "subject_config.address", "type": "string", "required": false, "description": "仓库默认发件详细地址,默认空字符串" } ], "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(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" }, { "name": "subject_config.auto_outbound_rules", "type": "object", "required": false, "source": "body.subject_config", "description": "自动出库规则配置。全部条件满足时自动标记待出库" }, { "name": "subject_config.auto_outbound_rules.enabled", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否启用自动出库,默认 false" }, { "name": "subject_config.auto_outbound_rules.require_recheck", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已复核(recheck_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pack", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已打包(pack_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_weigh", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已称重(weighing_weight>0),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_sync", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已同步(sync_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_print", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已打印(print_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pick", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已拣货(pick_status=fin),默认 true" }, { "name": "subject_config.sender_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件人姓名,默认空字符串,最大长度 50" }, { "name": "subject_config.sender_tel", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件人联系电话,默认空字符串,最大长度 20" }, { "name": "subject_config.province_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件省份,默认空字符串,最大长度 50" }, { "name": "subject_config.city_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件城市,默认空字符串,最大长度 50" }, { "name": "subject_config.district_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件区/县,默认空字符串,最大长度 50" }, { "name": "subject_config.town_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件镇/街道,默认空字符串,最大长度 50" }, { "name": "subject_config.address", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件详细地址,默认空字符串,最大长度 200" } ], "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、has_bound_item 等商品筛选字段。示例:where.barcode={operator:like,value:69}; where.prohibited_type={operator:eq,value:liquid}; where.has_bound_item={operator:eq,value:true}(已绑定外部商品)/ where.has_bound_item={operator:eq,value:false}(未绑定外部商品)。" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.externalList", "description": "外仓商品列表查询。传入 warehouse_id 按仓库维度查,不传则按当前货主维度查(store_id);where/分页语义与 stock.warehouse.list 一致;where.keyword 支持模糊搜索(item_code/item_name/goods_code)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "仓库ID(可选,不传则取当前用户上下文)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,与 stock.warehouse.list 一致" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,与 stock.warehouse.list 语义一致。支持 keyword 快捷搜索:where.keyword={operator:like,value:'关键字'}" } ], "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)。支持导入条码(barcode),新建和更新均生效,条码写入 wms_stock_barcodes 表。", "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": "条码 / bar_code / barCode / barcodeList / barcode_list / barcode", "type": "string", "required": false, "description": "条码列表,逗号分隔字符串,如 \"6901234567890,6901234567891\"。与导出格式一致。新建和更新均支持,条码存储在 wms_stock_barcodes 表。" }, { "name": "store_id / storeId", "type": "number", "required": false, "source": "body", "description": "可选,货主/仓库 ID;未传入时使用当前上下文(ctx.user.store_id)" } ] } ], "response": [ { "name": "total_count", "type": "number", "required": true, "description": "解析到的总条目数" }, { "name": "created_count", "type": "number", "required": true, "description": "成功创建的新商品数" }, { "name": "updated_count", "type": "number", "required": true, "description": "成功更新的商品数" }, { "name": "fail_count", "type": "number", "required": true, "description": "导入失败数" }, { "name": "created_ids", "type": "array", "required": true, "description": "创建成功的商品 ID 列表" }, { "name": "updated_ids", "type": "array", "required": true, "description": "更新成功的商品 ID 列表" }, { "name": "fail_items", "type": "array", "required": true, "description": "失败项明细数组,每项包含原始输入与错误信息" } ], "errors": [ { "code": "400", "message": "导入数据不能为空" }, { "code": "400", "message": "缺少仓库上下文" }, { "code": "400", "message": "导入行数据无效" }, { "code": "500", "message": "导入失败" } ] }, { "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(正整数,单位 g);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": "部分商品不存在或无权修改: " }, { "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 条。新增 mode=\"combo\" 时切换为组合商品搜索模式。", "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 限制)。mode=\"combo\" 时模糊匹配 combo_code / combo_name / custom_code" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID,传入时仅返回指定货主的商品" }, { "name": "mode", "type": "string", "required": false, "source": "body", "description": "查询模式。传 \"combo\" 时搜索组合商品,不传或为空时保持原有 stock 搜索行为" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "当 mode=\"combo\" 时,按组合商品ID精确查询" }, { "name": "custom_code", "type": "string", "required": false, "source": "body", "description": "当 mode=\"combo\" 时,按自定义编码模糊查询" }, { "name": "with_stock", "type": "boolean", "required": false, "source": "body", "default": false, "description": "是否返回关联库存数据(wms_storage),为 true 时每条商品新增 storage[] 字段。注意:mode=\"combo\" 时不生效" }, { "name": "is_batch", "type": "boolean", "required": false, "source": "body", "default": false, "description": "是否按批次明细返回库存,仅 with_stock=true 时生效。false(默认)按库位分组汇总;true 逐条返回批次明细。注意:mode=\"combo\" 时不生效" } ], "response": [ { "name": "code", "type": "number", "description": "业务状态码,200 表示成功", "required": false }, { "name": "data", "type": "array", "description": "商品列表,每项包含以下字段。mode=\"combo\" 时返回组合商品结构", "children": [ { "name": "id", "type": "number", "description": "商品库存ID(stock_warehouse.id)。mode=\"combo\" 时返回组合商品ID", "required": false }, { "name": "item_code", "type": "string", "description": "商品编码。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "goods_code", "type": "string", "description": "货物编码。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "item_name", "type": "string", "description": "商品名称。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "sku_property", "type": "string", "description": "SKU 规格。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "stock_unit", "type": "string", "description": "库存单位。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "quantity", "type": "number", "description": "库存数量。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "locked_quantity", "type": "number", "description": "锁定数量。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "brand_name", "type": "string", "description": "品牌名称。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "item_type", "type": "string", "description": "商品类型。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "barcodes", "type": "array", "description": "商品条形码列表(string[])。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "store_stock", "type": "object", "description": "关联的货主签约信息(LEFT JOIN),含 store_id、store_remask;无签约时为 null。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "is_shelf_life_mgmt", "type": "boolean", "description": "是否启用效期管理(true=启用)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "shelf_life_days", "type": "number", "description": "商品标准效期/保质期(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "inbound_min_days", "type": "number", "description": "入库后最小可出库天数(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "outbound_min_days", "type": "number", "description": "出库前需保留的最小天数(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "remaining_threshold_days", "type": "number", "description": "剩余天数阈值,低于该值视为即将过期(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "combo_code", "type": "string", "description": "组合商品编码,仅 mode=\"combo\" 时返回", "required": false }, { "name": "combo_name", "type": "string", "description": "组合商品名称,仅 mode=\"combo\" 时返回", "required": false }, { "name": "custom_code", "type": "string", "description": "自定义编码,仅 mode=\"combo\" 时返回", "required": false }, { "name": "items", "type": "array", "description": "子商品数组,仅 mode=\"combo\" 时返回。每项含 item_goods_sku_id(子商品ID)、item_quantity(子商品数量)", "children": [ { "name": "item_goods_sku_id", "type": "number", "description": "子商品SKU ID", "required": false }, { "name": "item_quantity", "type": "number", "description": "子商品数量", "required": false } ], "required": false }, { "name": "simpleNotation", "type": "string", "description": "子商品简写表示,格式为 stock_id|数量,多条用换行分隔。仅 mode=\"combo\" 时返回", "required": false }, { "name": "nameNotation", "type": "string", "description": "子商品名称表示,格式为【数量】商品名称,多条用换行分隔。仅 mode=\"combo\" 时返回", "required": false }, { "name": "storage", "type": "array", "description": "关联库存明细,仅 with_stock=true 时返回。is_batch=false 时按库位分组汇总,is_batch=true 时逐条返回批次明细。注意:mode=\"combo\" 时不返回", "children_grouped": { "description": "is_batch=false(默认):按库位分组汇总,每条包含以下字段", "fields": [ { "name": "space_id", "type": "number", "description": "库位ID", "required": false }, { "name": "inventory_type", "type": "string", "description": "库存类型", "required": false }, { "name": "quantity", "type": "number", "description": "该库位总库存数量(合并同库位)", "required": false }, { "name": "locked_quantity", "type": "number", "description": "该库位总锁定数量", "required": false }, { "name": "available_quantity", "type": "number", "description": "可用数量(quantity - locked_quantity)", "required": false }, { "name": "space", "type": "object", "description": "库位信息子对象,含 id、space_code、custom_name", "required": false } ] }, "children_batch": { "description": "is_batch=true:逐条批次明细,每条包含以下字段", "fields": [ { "name": "id", "type": "number", "description": "storage 记录ID", "required": false }, { "name": "stock_id", "type": "number", "description": "关联的商品库存ID", "required": false }, { "name": "space_id", "type": "number", "description": "库位ID", "required": false }, { "name": "batch_no", "type": "string", "description": "批次号", "required": false }, { "name": "inventory_type", "type": "string", "description": "库存类型", "required": false }, { "name": "quantity", "type": "number", "description": "库存数量", "required": false }, { "name": "locked_quantity", "type": "number", "description": "锁定数量", "required": false }, { "name": "available_quantity", "type": "number", "description": "可用数量", "required": false }, { "name": "production_date", "type": "string", "description": "生产日期", "required": false }, { "name": "expiry_date", "type": "string", "description": "过期日期", "required": false }, { "name": "inbound_time", "type": "string", "description": "入库时间", "required": false }, { "name": "inbound_order_no", "type": "string", "description": "入库单号", "required": false }, { "name": "supplier_batch_no", "type": "string", "description": "供应商批次号", "required": false }, { "name": "created_at", "type": "string", "description": "记录创建时间", "required": false }, { "name": "space", "type": "object", "description": "库位信息子对象,含 id、space_code、custom_name", "required": false } ] }, "required": false } ], "required": false }, { "name": "total", "type": "number", "description": "本次返回的记录条数(≤50)", "required": false } ], "errors": [] }, { "method": "stock.transaction.list", "description": "商品出入库流水列表查询(wms_stock_transaction),支持 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": "分页参数,包含 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,支持以下字段:", "children": [ { "name": "start_time", "type": "string", "required": false, "description": "开始时间(闭区间下限),created_at >= start_time" }, { "name": "end_time", "type": "string", "required": false, "description": "结束时间(闭区间上限),created_at <= end_time" }, { "name": "store_ids", "type": "array", "required": false, "description": "货主ID数组,为空或未传表示不筛选" }, { "name": "stock_ids", "type": "array", "required": false, "description": "商品库存ID数组,为空或未传表示不筛选" }, { "name": "transaction_type", "type": "string", "required": false, "description": "流水类型:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定" }, { "name": "order_type", "type": "string", "required": false, "description": "单据类型筛选" }, { "name": "order_no", "type": "string", "required": false, "description": "单据号筛选(支持模糊匹配)" }, { "name": "batch_no", "type": "string", "required": false, "description": "批次号筛选" }, { "name": "entry_order_id", "type": "number", "required": false, "description": "入库单ID筛选" }, { "name": "receiving_id", "type": "number", "required": false, "description": "收货单ID筛选" }, { "name": "order_id", "type": "number", "required": false, "description": "发货单ID筛选" } ] }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象,支持 sortField / sortOrder 与 sort_field / sort_order 下划线别名兼容", "children": [ { "name": "sortField", "type": "string", "required": false, "description": "排序字段,白名单:created_at、quantity、stock_id、store_id。非法字段回退默认排序(created_at DESC)" }, { "name": "sort_field", "type": "string", "required": false, "description": "排序字段下划线别名(兼容 sort.sort_field),规则同 sortField" }, { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向,ASC / DESC(大小写不敏感),非法值回退 DESC" }, { "name": "sort_order", "type": "string", "required": false, "description": "排序方向下划线别名(兼容 sort.sort_order),规则同 sortOrder" } ] } ], "response": [ { "name": "list", "type": "array", "description": "流水记录列表", "children": [ { "name": "id", "type": "number", "description": "流水记录ID" }, { "name": "created_at", "type": "string", "description": "流水创建时间" }, { "name": "transaction_type", "type": "string", "description": "流水类型:INBOUND / OUTBOUND / TRANSFER_OUT / TRANSFER_IN / LOCK" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "stock_id", "type": "number", "description": "商品库存ID" }, { "name": "quantity", "type": "number", "description": "变动数量" }, { "name": "before_quantity", "type": "number", "description": "变更前库存" }, { "name": "after_quantity", "type": "number", "description": "变更后库存" }, { "name": "before_locked_quantity", "type": "number", "description": "变更前锁定库存" }, { "name": "after_locked_quantity", "type": "number", "description": "变更后锁定库存" }, { "name": "batch_no", "type": "string", "description": "批次号" }, { "name": "order_type", "type": "string", "description": "单据类型" }, { "name": "order_no", "type": "string", "description": "单据号" }, { "name": "order_id", "type": "number", "description": "发货单ID" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "entry_order_id", "type": "number", "description": "入库单ID" }, { "name": "operator_name", "type": "string", "description": "操作人名称" }, { "name": "remark", "type": "string", "description": "备注" } ] }, { "name": "pagination", "type": "object", "description": "分页信息,包含 page、pageSize、total" } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] }, { "method": "stock.transaction.storeList", "description": "货主侧商品出入库流水列表查询(wms_stock_transaction),按货主 store_id 限定数据范围,支持 where 条件筛选与分页", "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": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,包含 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,支持以下字段:", "children": [ { "name": "start_time", "type": "string", "required": false, "description": "开始时间(闭区间下限),created_at >= start_time" }, { "name": "end_time", "type": "string", "required": false, "description": "结束时间(闭区间上限),created_at <= end_time" }, { "name": "warehouse_ids", "type": "array", "required": false, "description": "仓库ID数组,为空或未传表示不按仓库筛选(但仅返回当前货主有权限的仓库数据)" }, { "name": "stock_ids", "type": "array", "required": false, "description": "商品库存ID数组,为空或未传表示不筛选" }, { "name": "transaction_type", "type": "string", "required": false, "description": "流水类型:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定" }, { "name": "order_type", "type": "string", "required": false, "description": "单据类型筛选" }, { "name": "order_no", "type": "string", "required": false, "description": "单据号筛选(支持模糊匹配)" }, { "name": "batch_no", "type": "string", "required": false, "description": "批次号筛选" }, { "name": "entry_order_id", "type": "number", "required": false, "description": "入库单ID筛选" }, { "name": "receiving_id", "type": "number", "required": false, "description": "收货单ID筛选" }, { "name": "order_id", "type": "number", "required": false, "description": "发货单ID筛选" } ] }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象,支持 sortField / sortOrder 与 sort_field / sort_order 下划线别名兼容", "children": [ { "name": "sortField", "type": "string", "required": false, "description": "排序字段,白名单:created_at、quantity、stock_id、warehouse_id。非法字段回退默认排序(created_at DESC)" }, { "name": "sort_field", "type": "string", "required": false, "description": "排序字段下划线别名(兼容 sort.sort_field),规则同 sortField" }, { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向,ASC / DESC(大小写不敏感),非法值回退 DESC" }, { "name": "sort_order", "type": "string", "required": false, "description": "排序方向下划线别名(兼容 sort.sort_order),规则同 sortOrder" } ] } ], "response": [ { "name": "list", "type": "array", "description": "流水记录列表", "children": [ { "name": "id", "type": "number", "description": "流水记录ID" }, { "name": "created_at", "type": "string", "description": "流水创建时间" }, { "name": "transaction_type", "type": "string", "description": "流水类型:INBOUND / OUTBOUND / TRANSFER_OUT / TRANSFER_IN / LOCK" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "stock_id", "type": "number", "description": "商品库存ID" }, { "name": "quantity", "type": "number", "description": "变动数量" }, { "name": "before_quantity", "type": "number", "description": "变更前库存" }, { "name": "after_quantity", "type": "number", "description": "变更后库存" }, { "name": "before_locked_quantity", "type": "number", "description": "变更前锁定库存" }, { "name": "after_locked_quantity", "type": "number", "description": "变更后锁定库存" }, { "name": "batch_no", "type": "string", "description": "批次号" }, { "name": "order_type", "type": "string", "description": "单据类型" }, { "name": "order_no", "type": "string", "description": "单据号" }, { "name": "order_id", "type": "number", "description": "发货单ID" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "entry_order_id", "type": "number", "description": "入库单ID" }, { "name": "operator_name", "type": "string", "description": "操作人名称" }, { "name": "remark", "type": "string", "description": "备注" } ] }, { "name": "pagination", "type": "object", "description": "分页信息,包含 page、pageSize、total" } ], "errors": [ { "code": 400, "message": "store_id 不能为空" }, { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] } ] }, { "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.wavePickComplete", "description": "按波次ID一键完成整个波次的拣货。内部先按 wave_id 定位波次,复用 query 的去重与任务创建逻辑:若波次已有当前用户的活动任务则直接复用并完成;已有他人活动任务返回 409;已完成则返回 already_completed;否则新建任务(source=2 后台抓取)后在内部调用 wavePickTaskComplete(mode=1 全部确认)完成拣货并回写任务进度。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_id", "type": "number", "required": true, "source": "body", "description": "波次ID(wms_wave_batch.wave_id)" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "拣货任务ID" }, { "name": "status", "type": "string", "required": true, "description": "操作结果:completed(拣货完成)或 already_completed(波次已存在完成任务)" }, { "name": "tip", "type": "string", "required": true, "description": "提示文案" }, { "name": "confirmed_order_ids", "type": "array", "required": false, "description": "已确认完成的订单ID列表" }, { "name": "is_completed", "type": "boolean", "required": false, "description": "任务是否已全部完成" }, { "name": "progress", "type": "object", "required": false, "description": "任务进度(total_orders / picked_orders / pending_orders)" } ], "errors": [ { "code": 400, "message": "参数错误(wave_id 为空/非正整数、缺少仓库上下文、波次信息不完整、波次下无可用订单)。" }, { "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)。提交后根据是否全部完成自动推进任务状态。后台抓取创建的任务(source=2)必须先绑定拣货车才能提交,否则返回 400。", "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、任务下无可确认订单等)。后台抓取任务(source=2)未绑定拣货车时拒绝提交:\"后台抓取任务必须先绑定拣货车才能提交\"。" }, { "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": "查询收货单列表,支持分页和多条件筛选。支持 filterDepleted 参数过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。支持 entry_order_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": "分页参数,支持 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}。" }, { "name": "filterDepleted", "type": "boolean", "required": false, "source": "body", "description": "是否过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满,即 available=0)。默认 false。" }, { "name": "entry_order_id", "type": "number", "required": false, "source": "body", "description": "按入库单商品交集过滤。传入入库单 ID 后,只返回至少有一条收货明细的 system_product_id 在入库单明细中存在的收货单。与 filterDepleted 可组合使用。不传则不过滤。" } ], "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", "message": "查询失败" } ] }, { "method": "storage.receiving.getStoreReceivingList", "description": "货主侧收货单列表查询,以当前平台激活的货主 store_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": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;支持 quickWhere、status、warehouse_id、日期区间等字段。" }, { "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_quantity、total_locked、total_available、total_items)" } ], "errors": [ { "code": "500", "message": "查询失败" }, { "code": "0", "message": "未获取到货主平台激活上下文,请先切换至货主角色" } ] }, { "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": "实测箱重(单位与系统重量一致,如 g)" } ], "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": "实测箱重(单位与系统重量一致,如 g),默认 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": "箱重(单位 g)" }, { "name": "weight", "type": "number", "description": "商品重量(单位 g)" }, { "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": "实测箱重(单位与系统重量一致,如 g)" }, { "name": "weight", "type": "number", "required": false, "source": "body", "description": "毛重/重量(单位 g)" } ], "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": "实测箱重(单位与系统重量一致,如 g)" }, { "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,单位同系统重量,例如 g)。新增字段为可选,旧客户端可忽略。" ], "errors": [] } ] }, { "groupName": "入库单", "module": "storage.entry", "list": [ { "method": "storage.entry.list", "description": "入库单列表查询。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(通过 wms_entry_order_receiving 表查询实现)。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。", "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(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、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 字段,暂不支持该筛选条件,请先完成表结构升级\"。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(虚拟字段,不直接对应数据库列,内部通过 wms_entry_order_receiving 表查询实现)。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。" }, { "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)" }, { "name": "list[].receivingBindings", "type": "array", "required": false, "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" }, { "name": "list[].hasReceiving", "type": "boolean", "required": false, "description": "是否存在收货单绑定" } ], "errors": [ { "code": "400", "message": "筛选条件格式错误", "description": "筛选条件格式错误" }, { "code": "500", "message": "查询失败", "description": "查询失败" } ] }, { "method": "storage.entry.listStore", "description": "货主侧入库单列表查询:以货主维度(store_id)过滤入库单,货主登录后仅能查看自己货主下的入库单。与 storage.entry.list 共享底层逻辑,但主维度为 store_id 而非 warehouse_id。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 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": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头)。" }, { "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)" }, { "name": "list[].receivingBindings", "type": "array", "required": false, "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" }, { "name": "list[].hasReceiving", "type": "boolean", "required": false, "description": "是否存在收货单绑定" } ], "errors": [ { "code": "400", "message": "筛选条件格式错误", "description": "筛选条件格式错误" }, { "code": "500", "message": "查询失败", "description": "查询失败" } ] }, { "method": "storage.entry.get", "description": "查询入库单详情。通过入库单 ID 定位,关联 Store、EntryItems、EntryOrderReceiving→Receiving,并通过仓库商品详情、直接入库进度、收货单可用明细进行数据合并。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。", "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": "entryOrder", "type": "object", "required": true, "description": "入库单详情,包含 items 数组、receivingBindings(主表级收货单关联数组)。items 每项含 external_item_code / external_item_id / warehouse_item_code / warehouse_item_name / warehouse_item_spec / count / received_quantity / confirm_quantity / warehouse_quantity / warehouse_locked_quantity / warehouse_is_batch_mgmt / warehouse_is_shelf_life_mgmt / warehouse_image_url / warehouse_is_images / barcodes / direct_inbound_quantity / remaining_quantity / available_receiving_details" }, { "name": "entryOrder.items[].external_item_code", "type": "string", "required": true, "description": "外部商品编码(源自 EntryItems.item_code)" }, { "name": "entryOrder.items[].external_item_id", "type": "number", "required": true, "description": "外部商品ID(源自 EntryItems.item_id)" }, { "name": "entryOrder.items[].warehouse_item_code", "type": "string", "required": true, "description": "仓库商品编码(StockWarehouse.item_code),无匹配时为空字符串" }, { "name": "entryOrder.items[].warehouse_item_name", "type": "string", "required": true, "description": "仓库商品名称(StockWarehouse.item_name),无匹配时为空字符串" }, { "name": "entryOrder.items[].warehouse_item_spec", "type": "string", "required": true, "description": "仓库商品规格(StockWarehouse.sku_property),无匹配时为空字符串" }, { "name": "entryOrder.items[].count", "type": "number", "required": true, "description": "计划入库数量" }, { "name": "entryOrder.items[].received_quantity", "type": "number", "required": true, "description": "已收货数量(收货单途径)" }, { "name": "entryOrder.items[].confirm_quantity", "type": "number", "required": true, "description": "已确认收货数量" }, { "name": "entryOrder.items[].warehouse_quantity", "type": "number", "required": true, "description": "仓库当前库存总量(StockWarehouse.quantity),无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_locked_quantity", "type": "number", "required": true, "description": "仓库锁定数量(StockWarehouse.locked_quantity),无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_is_batch_mgmt", "type": "string", "required": true, "description": "是否批次管理(StockWarehouse.is_batch_mgmt),Y/N;无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_is_shelf_life_mgmt", "type": "string", "required": true, "description": "是否效期管理(StockWarehouse.is_shelf_life_mgmt),Y/N;无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_image_url", "type": "string", "required": true, "description": "商品图片 URL,当前固定返回空字符串 ''" }, { "name": "entryOrder.items[].warehouse_is_images", "type": "string", "required": true, "description": "是否有图片(StockWarehouse.is_images),Y/N;无匹配时为 null" }, { "name": "entryOrder.items[].barcodes", "type": "array", "required": true, "description": "条码列表,每项含 { id, barcode, sku_property };无匹配时为空数组 []" }, { "name": "entryOrder.items[].direct_inbound_quantity", "type": "number", "required": true, "description": "导入/PDA 已入库数量(InboundDirectLog 按 stock_id 聚合),无记录时为 0" }, { "name": "entryOrder.items[].remaining_quantity", "type": "number", "required": true, "description": "剩余可入库数量 = max(0, count - received_quantity),最小为 0" }, { "name": "entryOrder.items[].available_receiving_details", "type": "array", "required": true, "description": "可匹配的收货单明细及剩余可用量。每项含 receiving_id / receiving_number / receiving_detail_id / actual_quantity / allocated_quantity / available_quantity。仅返回收货单状态未完成且未完全入库的明细。无匹配时为空数组 []" }, { "name": "entryOrder.receivingBindings", "type": "array", "required": true, "description": "主表级收货单关联数组,每项含 id / receiving_id / receiving(receiving 含 id / receiving_number / status / storage_status / created_at)" } ], "errors": [ { "code": "400", "message": "id 参数不能为空" }, { "code": "0", "message": "入库单不存在或无权访问" }, { "code": "200", "message": "查询成功" } ] }, { "method": "storage.entry.getStore", "description": "货主侧查询入库单详情。与 get 共享底层逻辑,但以货主维度(store_id)校验权限(不使用 warehouse_id),货主登录后仅能查看自己货主下的入库单明细。返回结构与 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": "entryOrder", "type": "object", "required": true, "description": "入库单基本信息(id、entry_order_code、order_status、store_remask)" }, { "name": "items", "type": "array", "required": true, "description": "商品明细列表,每项含 id、stock_id、planned、completed、stock(商品详情)、bindings(库位绑定信息)" }, { "name": "receivingBindings", "type": "array", "required": false, "description": "主表级收货单关联数组,每项含 id / receiving_id / receiving(receiving 含 id / receiving_number / status / storage_status / created_at)" } ], "errors": [ { "code": "400", "message": "id 参数不能为空" }, { "code": "404", "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.cancel", "description": "作废入库单(支持单条或批量作废)。CREATED(已创建待审核)和 PENDING(已审核)状态的入库单可以直接作废;已完成(COMPLETED)入库单不允许作废。", "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", "message": "参数错误/参数不合法:需传入非空的 id 或 ids;ids 必须为数字数组且不得包含非法或重复值;已完成(COMPLETED)入库单不允许作废" }, { "code": "404", "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.addItem", "description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态需传 receiving_detail_id 绑定收货明细;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_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": "quantity", "type": "number", "required": false, "source": "body", "description": "本次入库数量(正整数)。传入 receiving_detail_id 时可选,自动计算收货明细可用数量;非绑定模式必填" }, { "name": "inbound_type", "type": "string", "required": true, "source": "body", "description": "入库方式:import(导入入库)、pda(PDA入库)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(如导入文件名、PDA操作备注等)" }, { "name": "space_id", "type": "number", "required": false, "source": "body", "description": "存放库位ID(单条模式),关联 wms_location_space.id。绑定收货明细时必填;为空时 commit 默认使用库位 1" }, { "name": "receiving_detail_id", "type": "number", "required": false, "source": "body", "description": "收货单明细ID(PDA 上架绑定模式),传入后触发收货明细预占绑定,quantity 自动计算" }, { "name": "allocated_quantity", "type": "number", "required": false, "source": "body", "description": "预分配数量(单条模式,可选,默认等于 quantity)" }, { "name": "items", "type": "array", "required": false, "source": "body", "description": "批量模式:商品列表,每项包含 stock_id(商品SKU ID, number, 必填)、quantity(入库数量, number, 绑定模式可选)、inbound_type(import/pda, string, 必填)、space_id(库位ID, number, 绑定模式必填)、remark(备注, string, 可选)、receiving_detail_id(收货明细ID, number, 可选)、allocated_quantity(预分配数量, number, 可选)。传入 items 时忽略顶层的 stock_id/quantity/inbound_type/remark/space_id。" } ], "response": [ { "name": "id", "type": "number", "required": false, "description": "单条模式返回:新增的入库记录ID" }, { "name": "stock_id", "type": "number", "required": false, "description": "商品SKU ID" }, { "name": "quantity", "type": "number", "required": false, "description": "本次入库数量" }, { "name": "inbound_type", "type": "string", "required": false, "description": "入库方式" }, { "name": "space_id", "type": "number", "required": false, "description": "存放库位ID" }, { "name": "plan_quantity", "type": "number", "required": false, "description": "入库单中该商品计划数量" }, { "name": "existing_before", "type": "number", "required": false, "description": "添加前已有入库总量" }, { "name": "existing_after", "type": "number", "required": false, "description": "添加后入库总量" }, { "name": "remaining", "type": "number", "required": false, "description": "剩余可入库数量" }, { "name": "receivingBindResult", "type": "object", "required": false, "description": "收货单绑定结果(仅绑定模式返回),含 binding_id、receiving_detail_id、allocated_quantity、status" }, { "name": "count", "type": "number", "required": false, "description": "批量模式:写入项数" }, { "name": "total_quantity", "type": "number", "required": false, "description": "批量模式:入库总数量" }, { "name": "items", "type": "array", "required": false, "description": "批量模式:每项入库记录详情(结构同单条模式)" } ], "errors": [ { "code": 400, "message": "entry_order_id 必填" }, { "code": 400, "message": "items[].stock_id 必填 / items[].quantity 必须为正整数 / items[].inbound_type 必须为 import 或 pda" }, { "code": 400, "message": "已作废入库单不允许操作 / 已完成的入库单不允许操作" }, { "code": 400, "message": "入库单已绑定收货单且状态为 CREATED,请先审核后再进行上架操作" }, { "code": 400, "message": "入库单未绑定收货单,无法上架(PENDING)" }, { "code": 400, "message": "随机入库需要选定收货单明细提交,缺少 receiving_detail_id(PENDING)" }, { "code": 400, "message": "绑定收货明细时必须指定 space_id" }, { "code": 400, "message": "入库数量超过计划:商品计划 X,已入库 Y,本次 Z,合计 W" }, { "code": 400, "message": "收货明细可用数量不足:实际数量 X,已占用 Y,可用 Z" }, { "code": 400, "message": "入库单中不存在该商品" }, { "code": 404, "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.commit", "description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 InboundDirectLog 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。不足量提交时未入库商品跳过。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "entry_order_code", "type": "string", "required": true, "description": "入库单号" }, { "name": "order_status", "type": "string", "required": true, "description": "入库单状态(固定为 COMPLETED)" }, { "name": "sync_status", "type": "string", "required": true, "description": "同步状态(固定为 SUCCESS)" }, { "name": "items_count", "type": "number", "required": true, "description": "入库商品种类数" }, { "name": "total_quantity", "type": "number", "required": true, "description": "入库总数量" } ], "errors": [ { "code": 400, "message": "entry_order_id 必填" }, { "code": 400, "message": "已作废入库单不允许完成 / 入库单已完成请勿重复提交 / 暂无导入/PDA 入库记录请先添加商品 / 入库单无明细" }, { "code": 404, "message": "入库单不存在或无权访问" }, { "code": 500, "message": "库存写入异常 / 同步回传失败" } ] }, { "method": "storage.entry.removeItem", "description": "移除一条导入/PDA 入库记录(仅限未提交的入库单,即状态非 CANCELLED/COMPLETED)。移除后该商品的可入库余量自动恢复。", "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(wms_inbound_direct_log.id)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "已移除的入库记录ID" }, { "name": "stock_id", "type": "number", "required": true, "description": "商品SKU ID" }, { "name": "quantity", "type": "number", "required": true, "description": "移除的入库数量" }, { "name": "inbound_type", "type": "string", "required": true, "description": "入库方式" } ], "errors": [ { "code": 400, "message": "id 必填 / 已作废入库单不允许操作 / 已完成的入库单不允许移除记录" }, { "code": 404, "message": "入库记录不存在 / 关联入库单不存在或无权访问" } ] }, { "method": "storage.entry.quickInbound", "description": "快捷直入(虚拟入库):将入库单所有商品按明细数量一键直入到虚拟库位(space_id=2),跳过收货/质检流程,入库单状态变为COMPLETED。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED。事务外异步回传奇门/API。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "entry_order_code", "type": "string", "required": true, "description": "入库单号" }, { "name": "order_status", "type": "string", "required": true, "description": "入库单状态(COMPLETED)" }, { "name": "sync_status", "type": "string", "required": true, "description": "同步状态(SUCCESS)" }, { "name": "items_count", "type": "number", "required": true, "description": "入库明细条目数" }, { "name": "total_quantity", "type": "number", "required": true, "description": "入库总数量" } ], "errors": [ { "code": 400, "message": "id 必填" }, { "code": 404, "message": "入库单不存在或无权访问" }, { "code": 400, "message": "已作废入库单不允许快捷入库" }, { "code": 400, "message": "入库单已完成,请勿重复提交" }, { "code": 400, "message": "入库单状态不允许快捷直入,当前状态:非CREATED(如PENDING等)" }, { "code": 400, "message": "请先添加入库明细" } ] }, { "method": "storage.entry.receivingCompare", "description": "入库单与收货单商品对照预览:给定入库单ID和收货单ID(支持多个),返回入库商品与收货商品的逐行对照视图,含匹配状态(matched/entry_only)和汇总统计。纯只读接口。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单ID" }, { "name": "receiving_id", "type": "number", "required": false, "source": "body", "description": "收货单ID,单个时使用,与 receiving_ids 二选一" }, { "name": "receiving_ids", "type": "array", "required": false, "source": "body", "description": "收货单ID数组,优先使用;与 receiving_id 二选一,传了此参数则忽略 receiving_id" } ], "response": [ { "name": "entry_order_id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "entry_order_code", "type": "string", "required": true, "description": "入库单号" }, { "name": "comparisons", "type": "array", "required": true, "description": "各收货单对照结果列表", "children": [ { "name": "receiving_id", "type": "number", "required": true, "description": "收货单ID" }, { "name": "receiving_number", "type": "string", "required": true, "description": "收货单号" }, { "name": "status", "type": "string", "required": true, "description": "对比状态:matched-匹配成功, error-校验失败" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 status=error 时),如 RECEIVING_NOT_FOUND" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 status=error 时)" }, { "name": "comparison", "type": "array", "required": false, "description": "逐行对照列表(仅 status=matched 时),每项含 entry_item_id/stock_id/warehouse_item_code/warehouse_item_name/warehouse_item_spec/entry_count/entry_received/receiving_detail_id/receiving_product_code/receiving_product_name/receiving_actual_quantity/receiving_allocated/receiving_available/match_status" }, { "name": "receiving_only", "type": "array", "required": false, "description": "仅收货单有的商品列表(仅 status=matched 时),每项含 receiving_detail_id/receiving_product_code/receiving_product_name/receiving_actual_quantity/receiving_allocated/receiving_available" }, { "name": "summary", "type": "object", "required": false, "description": "该收货单的汇总统计(仅 status=matched 时),含 total_entry_items/matched_items/entry_only_items/receiving_only_items" } ] }, { "name": "errors", "type": "array", "required": false, "description": "校验失败的收货单列表(status=error 的记录也会在此汇总)" }, { "name": "total_summary", "type": "object", "required": true, "description": "总体汇总统计", "children": [ { "name": "total_receivings", "type": "number", "description": "请求的收货单总数" }, { "name": "matched_count", "type": "number", "description": "匹配成功的收货单数" }, { "name": "error_count", "type": "number", "description": "校验失败的收货单数" } ] } ], "errors": [ { "code": 400, "message": "entry_order_id 必填" }, { "code": 400, "message": "receiving_ids 或 receiving_id 必填" }, { "code": 404, "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.bindReceiving", "description": "将收货单绑定到入库单(仅建立主表级关联,不做明细数量分配)。校验入库单状态(需为 CREATED 或 PENDING)、收货单有效性(存在、同仓库、未取消)后,逐个建立 wms_entry_order_receiving 绑定记录。支持部分成功:校验通过的写入绑定,不通过的在 failed 列表中返回原因。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单ID" }, { "name": "receiving_ids", "type": "array", "required": true, "source": "body", "description": "要绑定的收货单ID列表,每项为 integer" } ], "response": [ { "name": "success", "type": "array", "required": true, "description": "绑定成功列表,每项包含 receiving_id、receiving_number" }, { "name": "failed", "type": "array", "required": true, "description": "绑定失败列表,每项包含 receiving_id、error_code、message", "items": { "type": "object", "properties": { "receiving_id": { "type": "number", "description": "收货单ID" }, "receiving_number": { "type": "string", "description": "收货单号(部分失败项可能不返回)" }, "error_code": { "type": "string", "description": "错误码,可能值:RECEIVING_NOT_FOUND(收货单不存在或已删除)、RECEIVING_NOT_REVIEWED(收货单未审核)、WAREHOUSE_MISMATCH(收货单与入库单仓库不一致)、RECEIVING_CANCELLED(收货单已取消)、OWNER_MISMATCH(收货单与入库单货主不一致)、BIND_ERROR(绑定过程异常)" }, "message": { "type": "string", "description": "中文错误描述" } } } }, { "name": "success_count", "type": "number", "required": true, "description": "成功数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "失败数量" } ], "errors": [ { "code": 400, "message": "参数校验失败:entry_order_id 必填 / receiving_ids 必填且为非空数组 / 入库单状态不允许绑定(当前状态非 CREATED/PENDING)" }, { "code": 404, "message": "入库单不存在" }, { "code": "OWNER_MISMATCH", "message": "收货单与入库单货主不一致" }, { "code": "RECEIVING_NOT_REVIEWED", "message": "收货单未审核" } ] }, { "method": "storage.entry.reviewEntry", "description": "审核入库单(CREATED → PENDING),仅允许已绑定收货单的入库单推进状态", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "isNeedLog": true, "headers": [], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success/failure" }, { "name": "code", "type": "number", "required": true, "description": "200 成功 / 400 失败" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "data.order_status", "type": "string", "required": true, "description": "审核后状态(PENDING)" } ], "errors": [ { "code": 400, "message": "id 必填" }, { "code": 400, "message": "入库单不存在" }, { "code": 400, "message": "当前状态[xxx]不允许审核,仅 CREATED 可审核" }, { "code": 400, "message": "入库单未绑定收货单,请先绑定收货单后再审核" } ] }, { "method": "storage.entry.containerList", "description": "PDA 上架时拉取入库单已绑定收货单中指定商品的可用容器列表(未绑定的收货明细)。返回匹配明细的 detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status,以及商品详情 stock。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" }, { "name": "stock_id", "type": "number", "required": true, "source": "body", "description": "商品 stock_id(即 wms_stock_warehouse.id)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "可用容器(收货明细)列表" }, { "name": "list[].detail_id", "type": "number", "required": true, "description": "收货明细 ID" }, { "name": "list[].receiving_id", "type": "number", "required": true, "description": "收货单 ID" }, { "name": "list[].barcode", "type": "string", "required": true, "description": "商品条码" }, { "name": "list[].product_name", "type": "string", "required": true, "description": "商品名称" }, { "name": "list[].actual_quantity", "type": "number", "required": true, "description": "实收数量" }, { "name": "list[].receiving_status", "type": "string", "required": true, "description": "收货单状态" }, { "name": "list[].stock", "type": "object", "required": true, "description": "商品详情(通过 getStockDetails 获取,含 item_code、item_name、sku_property、barcodes 等缓存字段)" }, { "name": "total", "type": "number", "required": true, "description": "匹配总数" } ], "errors": [ { "code": 0, "message": "用户未绑定仓库" }, { "code": 0, "message": "entry_order_id 不能为空" }, { "code": 0, "message": "stock_id 不能为空" }, { "code": 0, "message": "入库单不存在或无权访问" }, { "code": 500, "message": "服务器查询失败" } ] }, { "method": "storage.entry.queryEntryLogs", "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(必填)" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量,默认 20" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "操作日志列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": 400, "message": "id 不能为空" }, { "code": 500, "message": "查询失败" } ] } ] }, { "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": "收货单快捷入库:将已审核的收货单(completed + is_review=true)明细按 stock_id(system_product_id)分组合并数量后,直接创建入库单(SCRK,自动审批到 PENDING),写入 wms_entry_order_receiving 主表级绑定,并更新收货单及其明细的入库状态(storage_status)。要求货主仓库签约配置 policy_config.allow_receiving_quick_putaway=1 开启快捷入库功能。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "receiving_id", "type": "number", "required": true, "source": "body", "description": "收货单ID(必填)" } ], "response": [ { "name": "entry_order_id", "type": "number", "description": "创建的入库单ID" }, { "name": "entry_order_code", "type": "string", "description": "入库单号(SCRK + 年月日 + 4位流水号)" }, { "name": "order_status", "type": "string", "description": "入库单状态(PENDING)" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "total_lines", "type": "number", "description": "入库单明细行数(按 stock_id 合并后的行数)" }, { "name": "total_quantity", "type": "number", "description": "入库总数量" } ], "errors": [ { "code": 400, "message": "receiving_id 必填" }, { "code": 400, "message": "无法获取当前仓库信息" }, { "code": 404, "message": "收货单不存在或无权访问" }, { "code": 400, "message": "收货单已作废,不允许快捷入库" }, { "code": 400, "message": "收货单状态不允许快捷入库,仅 completed 状态可操作" }, { "code": 400, "message": "收货单未审核,不允许快捷入库" }, { "code": 400, "message": "货主仓库签约关系不存在" }, { "code": 400, "message": "货主未开启收货单快捷入库功能" }, { "code": 400, "message": "收货单无明细,无法创建入库单" }, { "code": 400, "message": "收货单中所有明细均未关联系统商品,无法创建入库单" }, { "code": 400, "message": "以下商品在当前仓库中不存在或已失效" }, { "code": 500, "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(默认合并模式),仅按 stock_id 分组聚合,跨库位、跨库存类型汇总", "list": [ { "stock_id": "商品库存ID", "warehouse_id": "仓库ID(MIN 聚合值)", "store_id": "货主ID(MIN 聚合值)", "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)" } } ], "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": "stock.report", "list": [ { "method": "stock.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数组)、stock_id(商品库存ID,单数)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配,支持 SKU ID/item_code/item_name/goods_code/barcode)。仅返回在时间区间内存在流水的数据(无流水键不返回)。" }, { "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": "where.stock_id", "type": "number", "required": false, "source": "body", "description": "商品库存ID(单数),精确过滤指定商品;与 stock_ids 二选一,与 keyword 互斥" }, { "name": "where.stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID数组,精确过滤指定商品列表;与 stock_id 二选一,与 keyword 互斥", "list": [] }, { "name": "where.keyword", "type": "string", "required": false, "source": "body", "description": "商品关键字,支持按 SKU ID(纯数字精确匹配)、商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)模糊匹配;与 stock_id / stock_ids 互斥" }, { "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": "stock.report.searchStore", "description": "货主侧库存报表查询:以货主维度统计商品出入库(入库和订单出库),不涉及库位维度。与 search 共享核心逻辑,但主维度为 store_id。", "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(闭区间上限)、warehouse_ids(仓库ID数组,可选过滤)、stock_id(商品库存ID,单数)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配,支持 SKU ID/item_code/item_name/goods_code/barcode)。仅返回在时间区间内存在流水的数据。" }, { "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.warehouse_ids", "type": "array", "required": false, "source": "body", "description": "仓库ID数组,用于过滤特定仓库(空或未传表示不过滤)", "list": [] }, { "name": "where.stock_id", "type": "number", "required": false, "source": "body", "description": "商品库存ID(单数),精确过滤指定商品;与 stock_ids 二选一,与 keyword 互斥" }, { "name": "where.stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID数组,精确过滤指定商品列表;与 stock_id 二选一,与 keyword 互斥", "list": [] }, { "name": "where.keyword", "type": "string", "required": false, "source": "body", "description": "商品关键字,支持按 SKU ID(纯数字精确匹配)、商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)模糊匹配;与 stock_id / stock_ids 互斥" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象。支持 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": "匹配到的报表行列表,已按 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": "stock_id", "type": "integer", "description": "库存商品ID(wms_stock_warehouse.id)" }, { "name": "store_id", "type": "integer", "description": "货主ID" }, { "name": "warehouse_id", "type": "integer", "description": "仓库ID" }, { "name": "store_name", "type": "string", "description": "货主名称" }, { "name": "warehouse_name", "type": "string", "description": "仓库名称" }, { "name": "item_name", "type": "string", "description": "商品名称" }, { "name": "item_code", "type": "string", "description": "商品编码" }, { "name": "barcode", "type": "string", "description": "条码" }, { "name": "begin_total", "type": "number", "description": "期初库存" }, { "name": "inbound_total", "type": "number", "description": "入库总量" }, { "name": "outbound_total", "type": "number", "description": "出库总量" }, { "name": "end_total", "type": "number", "description": "期末库存" }, { "name": "space_id", "type": "integer", "description": "库位ID(where.by_space=true 时返回)" }, { "name": "space_name", "type": "string", "description": "库位名称(where.by_space=true 时返回)" } ] } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" }, { "code": 400, "message": "用户未绑定货主" } ] }, { "method": "stock.report.export", "description": "提交库存报表导出异步任务(与 stock.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": "stock.report.exportStore", "description": "货主侧提交库存报表导出异步任务(与 stock.report.searchStore 使用相同查询条件),立即返回任务受理信息,不直接返回文件。可通过 stock.report.exportTaskProgress 查询进度。", "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、warehouse_ids。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间" }, { "name": "where.warehouse_ids", "type": "array", "required": false, "source": "body", "description": "仓库ID数组,用于过滤特定仓库", "list": [] }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名" }, { "name": "export_mode", "type": "string", "required": false, "source": "body", "description": "导出模式:'item' 导出含锁定类型的全部变更记录" }, { "name": "exportMode", "type": "string", "required": false, "source": "body", "description": "导出模式(驼峰写法,同 export_mode)" } ], "response": [ { "name": "data.task_id", "type": "string", "required": true, "description": "导出异步任务ID,用于后续查询进度" }, { "name": "data.status", "type": "string", "required": true, "description": "任务受理状态:submitted" }, { "name": "data.progress", "type": "number", "required": true, "description": "任务进度:0" }, { "name": "data.message", "type": "string", "required": true, "description": "任务受理消息" }, { "name": "data.update_time", "type": "number", "required": true, "description": "任务更新时间戳(ms)" } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] }, { "method": "stock.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": "storage.management", "list": [ { "method": "storage.management.replenishmentDemand", "description": "分拣缺货补货需求计算(仓库级别)。自动从用户上下文获取仓库,查询所有未完成储位分配的订单,计算每个SKU在分拣区与存货区的库存量、订单需求量、分拣区缺口、建议补货量及可补货库位。支持分页与排序。", "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,默认 page=1 pageSize=20" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder。sortField 可选值:stock_id / pick_zone_quantity / storage_zone_quantity / total_demand / shortage / replenishment_needed,默认 shortage;sortOrder 可选 ASC / DESC,默认 DESC" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "补货需求明细列表", "children": [ { "name": "stock_id", "type": "number", "required": true, "description": "SKU ID" }, { "name": "stock_code", "type": "string", "required": true, "description": "SKU 编码" }, { "name": "stock_name", "type": "string", "required": true, "description": "SKU 名称" }, { "name": "pick_zone_quantity", "type": "number", "required": true, "description": "分拣区可用库存(allow_allocation=1且is_active=1的库位上的可用库存)" }, { "name": "storage_zone_quantity", "type": "number", "required": true, "description": "存货区可用库存(其余库位上的可用库存)" }, { "name": "total_demand", "type": "number", "required": true, "description": "订单总需求量(汇总自订单明细 plan_qty)" }, { "name": "shortage", "type": "number", "required": true, "description": "分拣区缺口 = max(0, total_demand - pick_zone_quantity)" }, { "name": "replenishment_needed", "type": "number", "required": true, "description": "建议补货量 = min(shortage, storage_zone_quantity)" }, { "name": "replenishment_status", "type": "string", "required": true, "description": "补货状态枚举:replenishable=存货区足够覆盖缺口,移库可解决;true_shortage=存货区不足以覆盖缺口或两区均无库存,需采购" }, { "name": "replenishment_locations", "type": "array", "required": true, "description": "存货区可补货库位列表(最多5条,按可用库存降序)", "children": [ { "name": "space_code", "type": "string", "required": true, "description": "库位编码" }, { "name": "space_name", "type": "string", "required": true, "description": "库位展示名称(优先自定义名称 custom_name,无自定义名称时回退为库位编码 space_code)" }, { "name": "available_quantity", "type": "number", "required": true, "description": "该库位可用库存数量" } ] } ] }, { "name": "summary", "type": "object", "required": true, "description": "汇总信息", "children": [ { "name": "total_skus", "type": "number", "required": true, "description": "涉及的SKU总数" }, { "name": "total_shortage_skus", "type": "number", "required": true, "description": "存在缺口的SKU数" }, { "name": "total_replenishment_needed", "type": "number", "required": true, "description": "总建议补货量" }, { "name": "total_true_shortage_skus", "type": "number", "required": true, "description": "真正缺货的SKU数(分拣区与存货区均无库存)" } ] }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息", "children": [ { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "pageSize", "type": "number", "required": true, "description": "每页条数" }, { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "totalPages", "type": "number", "required": true, "description": "总页数" } ] } ], "errors": [ { "code": 500, "message": "缺少仓库上下文" }, { "code": 200, "message": "无待处理订单时返回空列表(list: [], summary: { total_skus: 0, total_shortage_skus: 0, total_replenishment_needed: 0, total_true_shortage_skus: 0 })" } ] } ] }, { "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": "查询当前主体可见的签约列表(当前主体在 store_id 方,对方在 warehouse_id 方)", "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[].counterparty_role", "type": "string", "description": "对方主体角色:warehouse 或 store" }, { "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[].warehouse_use_status", "type": "number", "description": "仓库侧启用状态:0=禁用 1=启用" }, { "name": "data.list[].store_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": "发起或确认签约(当前主体始终为 store_id 方/消费方,对方为 warehouse_id 方/提供方,支持仓库签仓库)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "counterparty_id", "type": "number", "required": true, "source": "body", "description": "对方主体 ID(兼容 warehouse_id / store_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": "warehouse_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": "storeWarehouse.warehouse", "list": [ { "method": "storeWarehouse.warehouse.list", "description": "仓库侧查询签约列表(支持查询外部合作仓库),当前仓库在 store_id 方(消费方),对方在 warehouse_id 方(提供方)", "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,最大 200" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "搜索关键字,模糊匹配己方备注名、对方备注名、己方公司名、对方公司名" }, { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "对方主体 ID(兼容 counterparty_id)" }, { "name": "auth_status", "type": "number", "required": false, "source": "body", "description": "授权状态筛选:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" }, { "name": "use_status", "type": "number", "required": false, "source": "body", "description": "己方启用状态:0=禁用 1=启用" } ], "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": "己方主体名称" }, { "name": "data.list[].warehouse_id", "type": "number", "description": "对方主体 ID" }, { "name": "data.list[].warehouse_name", "type": "string", "description": "对方主体名称" }, { "name": "data.list[].counterparty_id", "type": "number", "description": "对方主体 ID(同 warehouse_id)" }, { "name": "data.list[].counterparty_name", "type": "string", "description": "对方主体名称" }, { "name": "data.list[].counterparty_role", "type": "string", "description": "对方主体角色:warehouse(外部合作仓库)或 store(货主)" }, { "name": "data.list[].remask", "type": "string", "description": "己方对本次签约的备注名" }, { "name": "data.list[].use_status", "type": "number", "description": "己方启用状态:0=禁用 1=启用" }, { "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[].auth_end", "type": "string|null", "description": "授权结束时间" }, { "name": "data.list[].print_quantity", "type": "number", "description": "面单余额数量" }, { "name": "data.list[].has_qimen_config", "type": "boolean", "description": "是否已配置奇门" }, { "name": "data.list[].needs_my_confirm", "type": "boolean", "description": "是否需要当前仓库确认签约(对方发起且状态为申请中)" }, { "name": "data.total", "type": "number", "description": "总记录数" }, { "name": "data.page", "type": "number", "description": "当前页码" }, { "name": "data.page_size", "type": "number", "description": "每页条数" }, { "name": "data.current_subject", "type": "object", "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" } ], "errors": [ { "code": 500, "message": "获取签约列表失败" } ] } ] }, { "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": "出库模块", "module": "order", "list": [ { "method": "order.wave.batchList", "description": "波次列表查询。仅使用当前登录操作者仓库上下文(禁止传入 warehouse_id/warehouseId)。支持 where 白名单过滤,固定查询 wave_status=0/1;返回波次基础信息及分配状态汇总(storage_assignment_status / express_assignment_status / print_assignment_status / pick_assignment_status / review_assignment_status)。支持 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- 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 / pick_assignment_status / review_assignment_status / unreviewed_order_count)。其中 pick_assignment_status 按订单 pick_status 聚合判定,取值:未拣货/部分拣货/已拣货/拣货异常。每条记录新增字段 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": "查询失败" } ] }, { "method": "order.pendingOrder.downloadCreateTemplate", "description": "下载创建订单的 Excel 导入模板。返回 base64 编码的 xlsx 文件,前端解码后作为 .xlsx 附件下载。表头中标注 * 的列为必填项(橙色背景),可选列为灰色背景,包含示例数据行和填写说明工作表。多行相同订单号的行组成一个完整订单,每行代表一条商品明细。模板共 25 列(A-Y):店铺名称(shop_nick)位于第2列B列,紧接*订单号(delivery_order_code)之后;其余必填列为*收件人姓名(name)、*手机号(mobile)、*详细地址(detail_address)、*商品编码(item_code)、*计划数量(plan_qty);非必填列依次为货主ID(store_id)、电话(tel)、省份(province)、城市(city)、区/县(area)、镇/街道(town)、邮编(zip_code)、快递编码(logistics_code)、快递名称(logistics_name)、系统平台编码(sys_platform_code)、来源平台编码(source_platform_code)、来源订单号(source_order_codes)、订单类型(order_type)、是否紧急(is_urgency)、是否需要发票(invoice_flag)、商品名称(item_name)、行号(order_line_no)、实际价格(actual_price)。", "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": "建议保存的文件名,固定为 创建订单导入模板.xlsx" }, { "name": "mime", "type": "string", "required": true, "description": "文件 MIME 类型,固定为 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" } ], "errors": [] }, { "method": "order.pendingOrder.manualWaybill", "description": "手工录入运单号。为指定待处理订单创建一条运单记录(wms_order_express 表),仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作。完成后自动更新订单表的 print_status 与 post_status 为 'fin',表示外部已打印。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number", "required": true, "source": "body", "description": "订单 ID,必须为正整数" }, { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号,非空字符串" }, { "name": "logistics_interface_name", "type": "string", "required": false, "source": "body", "description": "物流接口名称(选填),手工填入的值,trim 后为空则传 null" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "创建的运单记录 ID" }, { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "business_key", "type": "number", "required": true, "description": "递增的业务键,同一订单下从 1 开始递增" }, { "name": "logistics_interface_name", "type": "string", "required": false, "description": "写入的物流接口名称,未传时为 null" }, { "name": "create_at", "type": "string", "required": true, "description": "创建时间" } ], "errors": [ { "code": 400, "message": "order_id 必须为正整数" }, { "code": 400, "message": "waybill_code(运单号)不能为空" }, { "code": 400, "message": "订单不存在或不属于当前仓库" }, { "code": 400, "message": "订单当前步骤不在允许范围,仅允许待处理状态(step 1/2/3)的订单手工录入运单号" }, { "code": 400, "message": "订单已标记待出库,不允许手工录入运单号" }, { "code": 500, "message": "内部错误:OrderExpress 模型未加载或数据库写入失败" } ] }, { "method": "order.pendingOrder.allocateSubOrderNumber", "description": "分配子单号(异步任务模式)。为指定订单按 business_key(从 2 开始)全量传入 createWaybillCodePipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发安全:已分配(status=1)自动跳过,未分配 INSERT status=0 占位后分配。请求立即返回 task_id(sub_ 前缀),后续通过 allocateSubOrderNumberProgress 按 task_id 或 business_key 查询进度与结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number", "required": true, "source": "body", "description": "订单 ID,必须为正整数" }, { "name": "sub_order_count", "type": "number", "required": true, "source": "body", "description": "子单号数量,>= 1。business_key 从 2 开始递增,如 count=1 则创建 business_key=2,count=3 则创建 2/3/4" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(sub_ 前缀),用于查询进度" }, { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/partial/failed" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比:5/50/80/100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明" }, { "name": "result", "type": "object", "required": true, "description": "分配结果摘要,含 total_count/skip_count/pending_count/business_keys/skipped_business_keys/pending_business_keys/details 等字段" } ], "errors": [ { "code": 400, "message": "order_id 必须为正整数" }, { "code": 400, "message": "sub_order_count 必须为正整数且 >= 1" }, { "code": 400, "message": "订单不存在或不属于当前仓库" }, { "code": 400, "message": "订单当前步骤不在允许范围,仅允许待处理状态(step 1/2/3)的订单分配子单号" }, { "code": 400, "message": "订单已标记待出库,不允许分配子单号" }, { "code": 500, "message": "内部错误:OrderExpress 模型未加载或运单分配链路异常" } ] }, { "method": "order.pendingOrder.allocateSubOrderNumberProgress", "description": "查询子单号分配任务进度。可按 task_id 查询整体进度,也可传入 business_key 进一步过滤该业务ID对应的分配详情与最终结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": true, "source": "body", "description": "任务 ID(返回的 task_id),支持 task_id 或 taskId 两种写法" }, { "name": "business_key", "type": "number", "required": false, "source": "body", "description": "子单号业务ID(可选),传入后返回该 business_key 对应的分配详情。支持 business_key 或 businessKey 两种写法" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/partial/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明" }, { "name": "result", "type": "object", "required": true, "description": "分配结果。若传了 business_key,额外返回 filtered_business_key 与 matched_detail" } ], "errors": [ { "code": 500, "message": "查询缓存异常" } ] }, { "method": "order.bindExpressPackageMaterialByWaybill", "description": "按运单号绑定包材。仅需传入运单号与包材ID,系统自动根据运单号反查对应订单运单记录并绑定包材,无需传入订单ID。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号,必填。" }, { "name": "package_material_id", "type": "number|string", "required": true, "source": "body", "description": "包材ID,必填。" } ], "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": 404, "message": "运单号不存在" }, { "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__ 并清空敏感字段;若存在 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": "重量(单位 g)" }, { "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": [] }, { "method": "setting.packageMaterial.search", "description": "包材关键字搜索,按 material_code / material_name 模糊匹配,最多返回 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": "搜索关键字,模糊匹配 material_code、material_name;为空时返回前 50 条启用中的包材" } ], "response": [ { "name": "data[]", "type": "array", "required": true, "description": "包材列表,每项包含 id(包材ID)、material_code(包材编码)、material_name(包材名称)、material_type(包材类型)、spec(规格)、status(状态)" } ], "errors": [ { "code": 500, "message": "服务器错误" } ] } ] }, { "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": [] } ] }, { "groupName": "组合商品模块", "module": "comboGoods", "list": [ { "method": "comboGoods.list", "description": "组合商品列表查询(分页),支持按 combo_code/combo_name/status/warehouse_id 筛选。返回含 custom_code(自定义编码)、simpleNotation(stock_id|数量)和 nameNotation(【数量】商品名称)简记字段", "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,默认 page=1 pageSize=20" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,支持 combo_code(精确匹配)、combo_name(模糊匹配)、status(等值)、warehouse_id(等值)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "组合商品列表,每项包含 id、combo_code、combo_name、combo_sku_id、custom_code、status、warehouse_id、remark、creator_id、editor_id、created_at、updated_at、items(子商品明细数组)、simpleNotation、nameNotation", "children": [ { "name": "id", "type": "number", "description": "组合商品ID" }, { "name": "combo_code", "type": "string", "description": "组合商品编码" }, { "name": "combo_name", "type": "string", "description": "组合商品名称" }, { "name": "combo_sku_id", "type": "number", "description": "组合商品SKU ID" }, { "name": "custom_code", "type": "string", "description": "自定义编码,可为 null" }, { "name": "status", "type": "number", "description": "状态:1=启用 0=停用" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "remark", "type": "string", "description": "备注" }, { "name": "creator_id", "type": "number", "description": "创建人ID" }, { "name": "editor_id", "type": "number", "description": "最后编辑人ID" }, { "name": "created_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" }, { "name": "items", "type": "array", "description": "子商品明细列表,每项含 id、combo_id、item_goods_sku_id、item_quantity、sort_order" }, { "name": "simpleNotation", "type": "string", "description": "简记字符串,格式:stock_id|数量,stock_id2|数量" }, { "name": "nameNotation", "type": "string", "description": "商品名称简记,格式:【数量】商品名称+【数量】商品名称" } ] }, { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "pageSize", "type": "number", "required": true, "description": "每页大小" } ], "errors": [ { "code": "500", "message": "查询失败" } ] }, { "method": "comboGoods.create", "description": "创建组合商品(含明细一次性提交)。校验:combo_code唯一性、custom_code按货主唯一(排除已删除记录)、所有子商品在wms_stock_warehouse中合法有效(is_valid=Y 且未删除)、所有子商品必须属于同一货主(store_id一致)。创建过程在事务中完成,保证主表和明细表的原子写入。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "combo_code", "type": "string", "required": true, "source": "body", "description": "组合商品编码,必填,全局唯一" }, { "name": "combo_name", "type": "string", "required": true, "source": "body", "description": "组合商品名称,必填" }, { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "仓库ID,可选" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注,可选" }, { "name": "custom_code", "type": "string", "required": false, "source": "body", "description": "自定义编码,可选。传入时校验按货主唯一(排除已删除记录)" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "子商品明细数组,每项含 item_goods_sku_id(number, 必填)和 item_quantity(number, 必填, 正整数)以及 sort_order(number, 可选, 排序号)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新建的组合商品ID" }, { "name": "combo_code", "type": "string", "required": true, "description": "组合商品编码" }, { "name": "combo_name", "type": "string", "required": true, "description": "组合商品名称" }, { "name": "custom_code", "type": "string", "required": false, "description": "自定义编码,未传入时为 null" } ], "errors": [ { "code": "400", "message": "组合商品编码不能为空" }, { "code": "400", "message": "组合商品名称不能为空" }, { "code": "400", "message": "子商品列表不能为空" }, { "code": "400", "message": "组合商品编码 \"{code}\" 已存在(409语义)" }, { "code": "400", "message": "自定义编码 \"{code}\" 已被货主其他组合商品使用" }, { "code": "400", "message": "以下子商品不存在或已停用:{ids}" }, { "code": "400", "message": "所有子商品必须属于同一个货主,不允许跨货主组合" }, { "code": "500", "message": "创建组合商品主记录失败" } ] }, { "method": "comboGoods.update", "description": "编辑组合商品(含明细替换)。校验同 create。传入 items 则先删旧明细再批量插入新明细,事务保证原子性。支持部分更新:不传的字段保持原值不变。custom_code 校验按货主唯一(排除已删除记录和自身)。", "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": "combo_name", "type": "string", "required": false, "source": "body", "description": "组合商品名称,可选" }, { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "仓库ID,可选" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注,可选" }, { "name": "custom_code", "type": "string", "required": false, "source": "body", "description": "自定义编码,可选。传入非空值时校验按货主唯一(排除已删除记录和自身 id)" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:1=启用 0=停用,可选" }, { "name": "items", "type": "array", "required": false, "source": "body", "description": "子商品明细数组,可选。传入非空数组时先删除旧明细再批量插入新明细;不传或传空数组则保持原明细不变。每项含 item_goods_sku_id(number)和 item_quantity(number)以及 sort_order(number, 可选)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "更新后的组合商品ID" } ], "errors": [ { "code": "400", "message": "组合商品ID不能为空" }, { "code": "404", "message": "组合商品不存在" }, { "code": "400", "message": "自定义编码 \"{code}\" 已被货主其他组合商品使用" }, { "code": "400", "message": "以下子商品不存在或已停用:{ids}" }, { "code": "400", "message": "所有子商品必须属于同一个货主,不允许跨货主组合" }, { "code": "500", "message": "更新失败" } ] }, { "method": "comboGoods.delete", "description": "删除组合商品(软删除,将 status 置为 0)", "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": "id", "type": "number", "required": true, "description": "已软删除的组合商品ID" } ], "errors": [ { "code": "400", "message": "组合商品ID不能为空" }, { "code": "404", "message": "组合商品不存在" }, { "code": "500", "message": "删除失败" } ] }, { "method": "comboGoods.search", "description": "关键字搜索组合商品(供手工建单选择)。模糊匹配 custom_code、combo_code 或 combo_name,仅返回启用状态(status=1)的记录,默认20条上限100条。custom_code 匹配项优先排在前面。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": true, "source": "body", "description": "搜索关键字,模糊匹配 custom_code、combo_code 和 combo_name" }, { "name": "limit", "type": "number", "required": false, "source": "body", "description": "最大返回条数,默认20,最大100" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "搜索结果列表,每项包含 id、combo_code、combo_name、custom_code、combo_sku_id、status、warehouse_id、items、simpleNotation、nameNotation" }, { "name": "total", "type": "number", "required": true, "description": "本次返回的记录条数" } ], "errors": [ { "code": "400", "message": "搜索关键字不能为空" }, { "code": "500", "message": "搜索失败" } ] } ] }, { "groupName": "收货管理", "module": "storage.receiving", "list": [ { "method": "storage.receiving.getAvailableInboundQuantity", "description": "[已删除] 按 stock_id 查询可入库数量。该方法已从代码中删除,不再可用。原依赖已弃用的 wms_entry_receiving_binding(明细绑定表),入库单与收货单的关系已改为通过 wms_entry_order_receiving 主表级关联。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [], "response": [], "errors": [] }, { "method": "storage.receiving.scanDetail", "description": "PDA 上架扫码定位收货明细:扫描商品条码/箱唛/托盘唛,快速定位收货明细。同一条码可能匹配多条收货明细,以列表 { list, total } 格式返回所有匹配结果。若 barcode 为纯数字优先按明细 ID 精确匹配,否则按商品条码精确匹配。PDA专用。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" }, { "name": "barcode", "type": "string", "required": true, "source": "body", "description": "扫描条码,支持:收货明细 ID(托盘唛头)、商品条码" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "匹配的收货明细列表" }, { "name": "list[].detail_id", "type": "number", "required": true, "description": "收货明细 ID" }, { "name": "list[].receiving_id", "type": "number", "required": true, "description": "收货单 ID" }, { "name": "list[].barcode", "type": "string", "required": true, "description": "商品条码" }, { "name": "list[].product_name", "type": "string", "required": true, "description": "商品名称" }, { "name": "list[].actual_quantity", "type": "number", "required": true, "description": "实收数量" }, { "name": "list[].receiving_status", "type": "string", "required": true, "description": "收货单状态" }, { "name": "list[].stock", "type": "object", "required": true, "description": "商品详情(通过 getStockDetails 获取,含 item_code、item_name、sku_property、barcodes 等缓存字段)" }, { "name": "total", "type": "number", "required": true, "description": "匹配总数" } ], "errors": [ { "code": 0, "message": "用户未绑定仓库" }, { "code": 0, "message": "入库单ID不能为空" }, { "code": 0, "message": "扫描条码不能为空" }, { "code": 0, "message": "入库单不存在或无权访问" }, { "code": 0, "message": "该入库单尚未关联收货单" }, { "code": 0, "message": "未找到可用的收货明细" }, { "code": 0, "message": "未找到匹配的收货明细" }, { "code": 500, "message": "服务器扫描查询失败" } ] }, { "method": "storage.receiving.export", "description": "提交收货单导出任务(仓库维度,异步)。导出为 Excel 文件,包含两个 Sheet:Sheet1=收货单列表(ID/单号/货主/状态/明细匹配状态/入库状态/来货方式/车牌号/快递单号/装卸方式/商品种类/总数量/总箱数/总托盘数/审核状态/创建人/备注/收货时间/创建时间/更新时间),Sheet2=收货单明细(收货单号/收货单ID/明细ID/商品名称/商品条码/系统商品ID/实收数量/箱数/托盘数/收货状态/入库状态/已入库数量/批次号/生产日期/到期日期/备注/创建时间)。筛选和排序规则与 getReceivingList 一致,按当前仓库维度(ctx.user.store_id)过滤。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件(与 getReceivingList 一致),支持 quickWhere(模糊搜索收货单号/货主名称/快递单号/创建人/车牌号)等字段" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField(id/receiving_number/status/created_at/updated_at/store_id/warehouse_id)和 sortOrder(ASC/DESC),默认按 created_at DESC" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID,用于轮询进度" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted-已提交 / running-执行中 / success-成功 / failed-失败" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度,0-100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态描述" }, { "name": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [ { "code": 0, "message": "用户未绑定仓库" } ] }, { "method": "storage.receiving.exportTaskProgress", "description": "查询收货单导出任务进度(仓库维度)。提交导出任务后,通过 task_id 轮询此接口获取实时进度和最终下载地址。任务缓存 TTL 为 30 分钟。", "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(下划线写法),与 taskId 二选一" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法),与 task_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": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "download_url", "type": "string", "required": false, "description": "Excel 文件下载地址(success 时有效)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [] }, { "method": "storage.receiving.storeExport", "description": "提交货主侧收货单导出任务(货主维度,异步)。以当前平台激活的货主 store_id 为维度导出。导出为 Excel 文件,包含两个 Sheet:Sheet1=收货单列表,Sheet2=收货单明细(字段同 export)。筛选和排序规则与 getStoreReceivingList 一致,需当前用户已切换至货主角色。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件(与 getStoreReceivingList 一致),支持 quickWhere(模糊搜索收货单号/货主名称/快递单号/创建人/车牌号)等字段" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField(id/receiving_number/status/created_at/updated_at/store_id/warehouse_id)和 sortOrder(ASC/DESC),默认按 created_at DESC" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID,用于轮询进度" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted-已提交 / running-执行中 / success-成功 / failed-失败" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度,0-100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态描述" }, { "name": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [ { "code": 0, "message": "未获取到货主平台激活上下文,请先切换至货主角色" } ] }, { "method": "storage.receiving.storeExportTaskProgress", "description": "查询货主侧收货单导出任务进度。复用 exportTaskProgress 的缓存查询逻辑,任务 ID 前缀不同。任务缓存 TTL 为 30 分钟。", "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(下划线写法),与 taskId 二选一" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法),与 task_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": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "download_url", "type": "string", "required": false, "description": "Excel 文件下载地址(success 时有效)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [] } ] }, { "groupName": "工作台模块", "module": "workbench", "list": [ { "method": "workbench.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": "筛选条件,支持 name(模糊)、barcode(模糊)、status(等值)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "工作台列表", "children": [ { "name": "id", "type": "number", "description": "工作台ID" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "name", "type": "string", "description": "工作台名称" }, { "name": "barcode", "type": "string", "description": "工作台条码" }, { "name": "status", "type": "number", "description": "状态:0-禁用 1-启用" }, { "name": "remark", "type": "string", "description": "备注" }, { "name": "created_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" } ] }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ], "errors": [ { "code": "400", "description": "参数格式错误或缺少仓库上下文" } ] }, { "method": "workbench.detail", "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": "data", "type": "object", "required": true, "description": "工作台详情对象" } ], "errors": [ { "code": "400", "description": "工作台ID不能为空" }, { "code": "404", "description": "工作台不存在或无权访问" } ] }, { "method": "workbench.create", "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": "barcode", "type": "string", "required": false, "source": "body", "description": "工作台条码(可选,仓库内唯一)" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:0-禁用 1-启用,默认1" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "新建的工作台对象" } ], "errors": [ { "code": "400", "description": "工作台名称不能为空" }, { "code": "400", "description": "条码已存在(仓库内唯一约束)" } ] }, { "method": "workbench.update", "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(必填)" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "工作台名称" }, { "name": "barcode", "type": "string", "required": false, "source": "body", "description": "工作台条码" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "更新后的工作台对象" } ], "errors": [ { "code": "400", "description": "工作台ID不能为空" }, { "code": "404", "description": "工作台不存在或无权操作" } ] }, { "method": "workbench.delete", "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(必填)" } ], "response": [], "errors": [ { "code": "400", "description": "工作台ID不能为空" }, { "code": "404", "description": "工作台不存在或无权操作" } ] }, { "method": "workbench.checkBarcode", "description": "检查条码在仓库内是否已存在", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "barcode", "type": "string", "required": true, "source": "body", "description": "条码(必填)" }, { "name": "excludeId", "type": "number", "required": false, "source": "body", "description": "排除的工作台ID(更新时避免自身冲突)" } ], "response": [ { "name": "exists", "type": "boolean", "required": true, "description": "是否存在:true=已存在 false=可用" } ], "errors": [ { "code": "400", "description": "条码不能为空" } ] }, { "method": "workbench.business", "description": "工作台业务入口(免登录免鉴权,入参 name + data,业务逻辑待实现)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "业务名称(用于分发具体逻辑)" }, { "name": "data", "type": "object", "required": false, "source": "body", "description": "业务数据(透传)" } ], "response": [ { "name": "name", "type": "string", "required": true, "description": "回显业务名称" }, { "name": "received", "type": "boolean", "required": true, "description": "是否已接收" } ], "errors": [] }, { "method": "workbench.bindCamera", "description": "工作台绑定/解绑摄像头,校验工作台与摄像头归属后更新 device_ids", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "工作台ID" }, { "name": "camera_ids", "type": "array", "required": false, "source": "body", "description": "摄像头ID数组,传空数组或 null 表示解绑所有摄像头" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "name", "type": "string", "required": true, "description": "工作台名称" }, { "name": "device_ids", "type": "array", "required": false, "description": "绑定后的摄像头ID列表" } ], "errors": [ { "code": "400", "message": "工作台ID不能为空" }, { "code": "400", "message": "摄像头 xxx 不存在或无权操作" }, { "code": "404", "message": "工作台不存在或无权操作" } ] } ] }, { "groupName": "录像服务器模块", "module": "camera_server", "list": [ { "method": "camera_server.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": "筛选:name(模糊)、status(等值)" } ], "response": [], "errors": [] }, { "method": "camera_server.detail", "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": [], "errors": [ { "code": "404", "description": "不存在或无权访问" } ] }, { "method": "camera_server.create", "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": "brand", "type": "string", "required": false, "source": "body", "description": "品牌" }, { "name": "public_ip", "type": "string", "required": false, "source": "body", "description": "公网IP" }, { "name": "internal_ip", "type": "string", "required": false, "source": "body", "description": "内网IP" }, { "name": "port", "type": "number", "required": false, "source": "body", "description": "端口号" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "账号" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "密码" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "400", "description": "名称不能为空" } ] }, { "method": "camera_server.update", "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(必填)" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "名称" }, { "name": "brand", "type": "string", "required": false, "source": "body", "description": "品牌" }, { "name": "public_ip", "type": "string", "required": false, "source": "body", "description": "公网IP" }, { "name": "internal_ip", "type": "string", "required": false, "source": "body", "description": "内网IP" }, { "name": "port", "type": "number", "required": false, "source": "body", "description": "端口号" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "账号" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "密码" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] }, { "method": "camera_server.delete", "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" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] } ] }, { "groupName": "摄像头模块", "module": "camera", "list": [ { "method": "camera.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": "筛选:server_id(等值)、custom_name(模糊)、status(等值)" } ], "response": [], "errors": [] }, { "method": "camera.detail", "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": [], "errors": [ { "code": "404", "description": "不存在或无权访问" } ] }, { "method": "camera.create", "description": "新增摄像头", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "server_id", "type": "number", "required": true, "source": "body", "description": "所属服务器ID(必填)" }, { "name": "channel_id", "type": "number", "required": true, "source": "body", "description": "通道编号(必填)" }, { "name": "channel_name", "type": "string", "required": false, "source": "body", "description": "通道名称" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "自定义名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "400", "description": "server_id/channel_id 不能为空" } ] }, { "method": "camera.update", "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(必填)" }, { "name": "server_id", "type": "number", "required": false, "source": "body", "description": "所属服务器ID" }, { "name": "channel_id", "type": "number", "required": false, "source": "body", "description": "通道编号" }, { "name": "channel_name", "type": "string", "required": false, "source": "body", "description": "通道名称" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "自定义名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] }, { "method": "camera.delete", "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" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] } ] }, { "groupName": "商品流水模块", "module": "stock.transaction", "list": [ { "method": "stock.transaction.export", "description": "提交商品出入库流水导出异步任务(仓库侧)。与 stock.transaction.list 使用相同查询条件,立即返回任务受理信息,不直接返回文件。", "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(结束时间)、store_ids(货主ID数组)、stock_ids(商品库存ID数组)、transaction_type(流水类型 INBOUND/OUTBOUND/LOCK/UNLOCK)、order_type(单据类型)、order_no(单据号,模糊匹配)、batch_no(批次号)、entry_order_id(入库单ID)、receiving_id(收货单ID)、order_id(发货单ID)。仓库范围自动取自 ctx.user.store_id。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间" }, { "name": "where.store_ids", "type": "array", "required": false, "source": "body", "description": "货主ID数组" }, { "name": "where.stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID数组" }, { "name": "where.transaction_type", "type": "string", "required": false, "source": "body", "description": "流水类型:INBOUND/OUTBOUND/LOCK/UNLOCK" }, { "name": "where.order_type", "type": "string", "required": false, "source": "body", "description": "单据类型" }, { "name": "where.order_no", "type": "string", "required": false, "source": "body", "description": "单据号(模糊匹配)" }, { "name": "where.batch_no", "type": "string", "required": false, "source": "body", "description": "批次号" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数。sortField 白名单:created_at/quantity/stock_id/store_id/warehouse_id;sortOrder 支持 ASC/DESC" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名" } ], "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" }, { "name": "message", "type": "string", "required": true, "description": "受理消息" }, { "name": "update_time", "type": "number", "required": true, "description": "更新时间戳" } ], "errors": [] }, { "method": "stock.transaction.exportStore", "description": "提交商品出入库流水导出异步任务(货主侧)。与 stock.transaction.storeList 使用相同查询条件,需传 store_id,立即返回任务受理信息。", "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": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time、end_time、warehouse_ids(仓库ID数组)、stock_ids(商品库存ID数组)、transaction_type、order_type、order_no、batch_no、entry_order_id、receiving_id、order_id。兼容 warehouse_id 单数。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数。sortField 白名单:created_at/quantity/stock_id/store_id/warehouse_id" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名" } ], "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" }, { "name": "message", "type": "string", "required": true, "description": "受理消息" }, { "name": "update_time", "type": "number", "required": true, "description": "更新时间戳" } ], "errors": [] }, { "method": "stock.transaction.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": "更新时间戳" } ], "errors": [] } ] } ] } }