From c5c16a12a2b1ce3e9ba939f4b5750c364467deb7 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Tue, 18 Aug 2026 17:11:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(setting.expressInterface):=20=E8=A1=A5?= =?UTF-8?q?=E5=85=A8=20update=20=E6=8E=A5=E5=8F=A3=E8=AF=A6=E7=BB=86?= =?UTF-8?q?=E5=85=A5=E5=8F=82=E4=B8=8E=E5=93=8D=E5=BA=94=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - params 由 3 个扩展为 31 个全量可更新字段(含 town_name/townName、is_enabled/isEnabled 等驼峰别名与空值处理规则) - description 补充仅更新传入字段、id 兼容 interface_id/interfaceId、shop_id 同步刷新 token 等说明 - response 按 normalizeInterfaceRow 补全 37 个字段,errors 补充 10 条错误码 - 版本 0.3.28 -> 0.3.29,updatedAt 更新为 2026-08-18,并新增变更记录 --- methods/changes/system.json | 15 ++ methods/system.json | 471 +++++++++++++++++++++++++++++++++++- 2 files changed, 477 insertions(+), 9 deletions(-) diff --git a/methods/changes/system.json b/methods/changes/system.json index cb9ea6e..8f6d6a9 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,19 @@ [ + { + "version": "2026.08.18-setting.expressInterface.update-doc-params", + "date": "2026-08-18", + "type": "enhanced", + "summary": "补全 setting.expressInterface.update 接口文档:入参由 3 个字段扩展为全量可更新字段(含 town_name/townName、is_enabled/isEnabled、providertype 等),并补充全量响应字段与错误码说明。", + "methods": [ + "setting.expressInterface.update" + ], + "notes": [ + "入参按 app/service/systems/setting/expressInterface.js update() 与包装层 app/service/systemMethods/setting/expressInterface.js update() 实际支持的字段补齐,含驼峰别名(shopId/townName/isEnabled 等),仅传入的字段被更新", + "响应按 normalizeInterfaceRow 返回结构补齐全量字段", + "仅文档变更,无代码改动" + ], + "module": "setting.expressInterface" + }, { "version": "2026.08.18-order-lock-status-guard-and-list-yn", "date": "2026-08-18", diff --git a/methods/system.json b/methods/system.json index 0c531be..9ee3452 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.28", - "updatedAt": "2026-08-15", + "version": "0.3.29", + "updatedAt": "2026-08-18", "headers": [ { "name": "platform", @@ -15325,7 +15325,7 @@ }, { "method": "setting.expressInterface.update", - "description": "更新快递接口,支持 shop_id/shopId 入参(可空)。", + "description": "更新快递接口。至少传入一个可更新字段,仅更新传入的字段;id 兼容 interface_id / interfaceId 入参;shop_id 可空,传入时会同步刷新接口 token;name/express_code/platform_code/sys_express_code 变更会触发系统快递编码重新解析。更新成功后返回该记录的完整字段。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -15342,32 +15342,485 @@ "type": "number", "required": true, "source": "body", - "description": "id" + "description": "快递接口ID,兼容 interface_id / interfaceId" + }, + { + "name": "name", + "type": "string", + "required": false, + "source": "body", + "description": "接口名称" + }, + { + "name": "express_code", + "type": "string", + "required": false, + "source": "body", + "description": "快递编码(存大写);与 platform_code / sys_express_code 任一变更时重新解析系统快递编码" + }, + { + "name": "platform_code", + "type": "string", + "required": false, + "source": "body", + "description": "平台编码(PDD/CAINIAO/DY/KS/SPH/XHS/JD/QT)" + }, + { + "name": "sys_express_code", + "type": "string", + "required": false, + "source": "body", + "description": "系统快递编码(支持 sysExpressCode);未传时按 express_code + platform_code 自动匹配" }, { "name": "shop_id", "type": "number", "required": false, "source": "body", - "description": "shop_id" + "description": "店铺ID(支持 shopId),正整数可空;传入该字段会同步刷新接口 token" + }, + { + "name": "platform_shop_id", + "type": "number", + "required": false, + "source": "body", + "description": "平台店铺ID(支持 platformShopId),正整数可空" + }, + { + "name": "template_id", + "type": "string", + "required": false, + "source": "body", + "description": "模板ID(支持 templateId),空字符串按 null 处理" + }, + { + "name": "paymode", + "type": "number", + "required": false, + "source": "body", + "description": "付款方式(支持 payMode)" + }, + { + "name": "brandno", + "type": "string", + "required": false, + "source": "body", + "description": "品牌编码(支持 brandNo),空字符串按 null 处理" + }, + { + "name": "providertype", + "type": "string", + "required": false, + "source": "body", + "description": "服务商类型编码(支持 providerType),空字符串按 null 处理" + }, + { + "name": "providerid", + "type": "number", + "required": false, + "source": "body", + "description": "服务商ID(支持 providerId)" + }, + { + "name": "sender_name", + "type": "string", + "required": false, + "source": "body", + "description": "寄件人(支持 senderName)" + }, + { + "name": "sender_tel", + "type": "string", + "required": false, + "source": "body", + "description": "寄件电话(支持 senderTel)" + }, + { + "name": "weight", + "type": "number", + "required": false, + "source": "body", + "description": "排序权重,可空" + }, + { + "name": "weight_type", + "type": "number", + "required": false, + "source": "body", + "description": "重量类型(支持 weightType),可空" + }, + { + "name": "viewer", + "type": "string", + "required": false, + "source": "body", + "description": "验视员/查看者" + }, + { + "name": "client_id", + "type": "string", + "required": false, + "source": "body", + "description": "客户ID(支持 clientId)" + }, + { + "name": "ispickup", + "type": "number", + "required": false, + "source": "body", + "description": "是否上门取件(支持 isPickup),1是 0否" + }, + { + "name": "shipperno", + "type": "string", + "required": false, + "source": "body", + "description": "发货编号/寄件网点编码(支持 shipperNo)" + }, + { + "name": "template_url", + "type": "string", + "required": false, + "source": "body", + "description": "打印模板URL(支持 templateUrl)" + }, + { + "name": "province_name", + "type": "string", + "required": false, + "source": "body", + "description": "寄件人省份(支持 provinceName)" + }, + { + "name": "city_name", + "type": "string", + "required": false, + "source": "body", + "description": "寄件人城市(支持 cityName)" + }, + { + "name": "district_name", + "type": "string", + "required": false, + "source": "body", + "description": "寄件人区县(支持 districtName)" }, { "name": "address", "type": "string", "required": false, "source": "body", - "description": "发件人详细地址(可选),使用 index.getShopExpressList 返回的 detail 字段值,非 full_address" + "description": "发件人详细地址,使用 index.getShopExpressList 返回的 detail 字段值,非 full_address" + }, + { + "name": "town_name", + "type": "string", + "required": false, + "source": "body", + "description": "寄件人镇/街道(支持 townName)" + }, + { + "name": "site_code", + "type": "string", + "required": false, + "source": "body", + "description": "网点编码(支持 siteCode)" + }, + { + "name": "product_type", + "type": "string", + "required": false, + "source": "body", + "description": "产品类型/编码(支持 productType)" + }, + { + "name": "shop_name", + "type": "string", + "required": false, + "source": "body", + "description": "平台店铺名称(支持 shopName)" + }, + { + "name": "ext_data", + "type": "object", + "required": false, + "source": "body", + "description": "扩展数据 JSON 对象(支持 extData)" + }, + { + "name": "is_enabled", + "type": "number", + "required": false, + "source": "body", + "description": "是否启用(支持 isEnabled),1启用 0停用" } ], "response": [ { "name": "id", "type": "number", - "description": "id", - "required": true + "required": true, + "description": "主键ID" + }, + { + "name": "name", + "type": "string", + "required": true, + "description": "接口名称" + }, + { + "name": "express_code", + "type": "string", + "required": true, + "description": "快递编码" + }, + { + "name": "sys_express_code", + "type": "string", + "required": true, + "description": "系统快递编码" + }, + { + "name": "warehouse_id", + "type": "number", + "required": false, + "description": "仓库ID" + }, + { + "name": "shop_id", + "type": "number", + "required": false, + "description": "店铺ID,未绑定时为 null" + }, + { + "name": "platform_shop_id", + "type": "number", + "required": false, + "description": "平台店铺ID" + }, + { + "name": "template_id", + "type": "string", + "required": false, + "description": "模板ID" + }, + { + "name": "paymode", + "type": "number", + "required": false, + "description": "付款方式" + }, + { + "name": "brandno", + "type": "string", + "required": false, + "description": "品牌编码" + }, + { + "name": "providertype", + "type": "string", + "required": false, + "description": "服务商类型编码" + }, + { + "name": "providerid", + "type": "number", + "required": false, + "description": "服务商ID" + }, + { + "name": "platform_code", + "type": "string", + "required": true, + "description": "平台编码(PDD/CAINIAO/DY/KS/SPH/XHS/JD/QT)" + }, + { + "name": "sender_name", + "type": "string", + "required": false, + "description": "寄件人" + }, + { + "name": "sender_tel", + "type": "string", + "required": false, + "description": "寄件电话" + }, + { + "name": "weight", + "type": "number", + "required": false, + "description": "排序权重" + }, + { + "name": "weight_type", + "type": "number", + "required": false, + "description": "重量类型" + }, + { + "name": "viewer", + "type": "string", + "required": false, + "description": "验视员/查看者" + }, + { + "name": "client_id", + "type": "string", + "required": false, + "description": "客户ID" + }, + { + "name": "is_enabled", + "type": "number", + "required": false, + "description": "是否启用(1启用 0禁用)" + }, + { + "name": "is_share", + "type": "number", + "required": false, + "description": "是否共享" + }, + { + "name": "ispickup", + "type": "number", + "required": false, + "description": "是否上门取件" + }, + { + "name": "shipperno", + "type": "string", + "required": false, + "description": "发货编号/寄件网点编码" + }, + { + "name": "template_url", + "type": "string", + "required": false, + "description": "打印模板URL" + }, + { + "name": "ext_data", + "type": "object", + "required": false, + "description": "扩展数据(JSON对象)" + }, + { + "name": "province_name", + "type": "string", + "required": false, + "description": "寄件人省份" + }, + { + "name": "city_name", + "type": "string", + "required": false, + "description": "寄件人城市" + }, + { + "name": "district_name", + "type": "string", + "required": false, + "description": "寄件人区县" + }, + { + "name": "address", + "type": "string", + "required": false, + "description": "发件人详细地址" + }, + { + "name": "town_name", + "type": "string", + "required": false, + "description": "寄件人镇/街道" + }, + { + "name": "site_code", + "type": "string", + "required": false, + "description": "网点编码" + }, + { + "name": "product_type", + "type": "string", + "required": false, + "description": "产品类型/编码" + }, + { + "name": "shop_name", + "type": "string", + "required": false, + "description": "店铺名称" + }, + { + "name": "express", + "type": "object", + "required": false, + "description": "关联的系统快递对象(未关联时为 null)" + }, + { + "name": "express_name", + "type": "string", + "required": false, + "description": "快递名称(扁平字段)" + }, + { + "name": "express_polyapi_extra_info", + "type": "string", + "required": false, + "description": "PolyAPI扩展信息(扁平字段)" + }, + { + "name": "express_pdd_code", + "type": "string", + "required": false, + "description": "拼多多快递编码(扁平字段)" } ], - "errors": [] + "errors": [ + { + "code": "400", + "message": "id 参数不能为空" + }, + { + "code": "400", + "message": "至少需要提供一个可更新字段" + }, + { + "code": "400", + "message": "name 参数不能为空" + }, + { + "code": "400", + "message": "express_code 参数不能为空" + }, + { + "code": "400", + "message": "platform_code 参数不能为空" + }, + { + "code": "400", + "message": "字段校验失败(字段为空、长度超限或数值/JSON 格式非法)" + }, + { + "code": "400", + "message": "express_code 未匹配到系统快递编码" + }, + { + "code": "400", + "message": "platform_code 未匹配到打印平台编码" + }, + { + "code": "404", + "message": "快递接口不存在或无权限操作" + }, + { + "code": "404", + "message": "当前仓库下未找到对应店铺,无法同步快递接口 token" + } + ] }, { "method": "setting.expressInterface.delete",