docs(setting.expressInterface): 补全 update 接口详细入参与响应文档

- 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,并新增变更记录
This commit is contained in:
liufumingren 2026-08-18 17:11:22 +08:00
parent 3817948b35
commit c5c16a12a2
2 changed files with 477 additions and 9 deletions

View File

@ -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",

View File

@ -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",