17.5.0 版本更新

版本信息

版本范围：17.5.0

文档日期：2026-08-24

适用范围：开放平台调用方

变更类型：兼容性新增与兼容性优化

本版本变更概览

17.5.0 版本为订单、退货单和客户对账单补充了客户往来自定义字段能力，并新增自定义字段元数据查询接口。

本次主要变化如下：

订单创建和对外订单编辑接口支持订单级和订单明细级自定义字段。

退货单创建、编辑支持退货级和退货明细级自定义字段。

订单、退货单的列表和详情接口返回对应层级的自定义字段。

客户对账单列表和详情将订单、退货、对账单自定义字段拆分为独立数组返回，调用方无需再根据单据来源判断同一字段的实际层级。

新增 GET /openApiV2/Common/CustomizeFieldList，供调用方查询字段 ID、名称、业务层级、字段类型和单选项。

数值字段支持后台配置的多位小数精度；数值及计算结果统一使用字符串返回，避免 JSON number 精度损失。

业务接口响应中的字段值项统一返回 id/name/value/select_id，调用方展示字段名称时无需再次查询。

接口变更明细

1. `POST /openApiV2/Order/Create`

接口名称：创建订单

变更类型：新增入参

新增入参：

customize_fields

说明：订单级自定义字段，固定对应 customize_type=3

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

commodity_list[].customize_fields

说明：订单商品明细级自定义字段，固定对应 customize_type=4

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

2. `GET /openApiV2/Order/pageList`

接口名称：获取订单列表

变更类型：新增返回字段

新增返回字段：

data.list[].customize_fields

说明：订单级自定义字段，customize_type=3

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

3. `GET /openApiV2/Order/detail`

接口名称：获取订单详情

变更类型：新增返回字段

新增返回字段：

data.order.customize_fields

说明：订单级自定义字段，customize_type=3

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.commodity_list[].customize_fields

说明：订单商品明细级自定义字段，customize_type=4

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

4. `POST /openApiV2/Order/Modify`

接口名称：编辑订单（不支持重复商品）

变更类型：新增入参

新增入参：

customize_fields

说明：订单级自定义字段，固定对应 customize_type=3

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

commodity_list[].customize_fields

说明：订单商品明细级自定义字段，固定对应 customize_type=4

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

编辑语义：字段缺失或传 null 表示不修改；显式传 [] 表示清空该层级手工字段；传非空数组时按字段 ID 与已有手工字段合并，未提交的已有字段保留

特殊规则：该接口不支持订单重复商品；计算字段由系统计算，客户端提交值会被忽略

5. `POST /openApiV2/OrderReturn/Create`

接口名称：创建退货单

变更类型：新增入参

新增入参：

customize_fields

说明：退货级自定义字段，固定对应 customize_type=17

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

commodity_list[].customize_fields

说明：退货商品明细级自定义字段，固定对应 customize_type=18

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

特殊规则：仅退款单只支持 type=17，不支持 type=18

6. `GET /openApiV2/OrderReturn/pageList`

接口名称：退货单列表

变更类型：新增返回字段

新增返回字段：

data.list[].customize_fields

说明：退货级自定义字段，customize_type=17

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

特殊规则：未启用退货自定义字段能力时返回空数组

7. `GET /openApiV2/OrderReturn/detail`

接口名称：退货单详情

变更类型：新增返回字段

新增返回字段：

data.order.customize_fields

说明：退货级自定义字段，customize_type=17

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.detail[].customize_fields

说明：退货商品明细级自定义字段，customize_type=18

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

特殊规则：仅退款单的明细级自定义字段返回空数组

8. `POST /openApiV2/OrderReturn/edit`

接口名称：编辑退货单

变更类型：新增入参

新增入参：

customize_fields

说明：退货级自定义字段，固定对应 customize_type=17

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

commodity_list[].customize_fields

说明：退货商品明细级自定义字段，固定对应 customize_type=18

数据结构：CustomizeFieldInput[]

版本说明：17.5.0 新增

编辑语义：字段缺失或传 null 表示不修改；显式传 [] 表示清空该层级手工字段

特殊规则：仅退款单不支持 type=18

9. `GET /openApiV2/AccountBill/PageList`

接口名称：客户对账列表

变更类型：新增返回字段

新增返回字段：

data.list[].order_customize_fields

说明：关联订单的订单级自定义字段，customize_type=3；无关联订单或无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.list[].return_customize_fields

说明：关联退货单的退货级自定义字段，customize_type=17；非退货/退款来源或无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.list[].account_bill_customize_fields

说明：当前客户对账单级自定义字段，customize_type=6；无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

返回规则：三个数组彼此独立，不再使用单个 customize_fields 按来源切换字段层级

10. `GET /openApiV2/AccountBill/Detail`

接口名称：客户对账详情

变更类型：新增返回字段

新增返回字段：

data.order.order_customize_fields

说明：关联订单的订单级自定义字段，customize_type=3；无关联订单或无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.order.return_customize_fields

说明：关联退货单的退货级自定义字段，customize_type=17；非退货/退款来源或无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.order.account_bill_customize_fields

说明：当前客户对账单级自定义字段，customize_type=6；无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.bill_item[].order_commodity_customize_fields

说明：关联订单商品的明细级自定义字段，customize_type=4；无关联订单商品或无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

data.bill_item[].return_commodity_customize_fields

说明：关联退货商品的明细级自定义字段，customize_type=18；非退货来源、仅退款或无字段时为空数组

数据结构：CustomizeFieldValue[]

版本说明：17.5.0 新增

返回规则：顶层三个数组、明细两个数组彼此独立，不再使用单个 customize_fields 按来源切换字段层级

11. `GET /openApiV2/Common/CustomizeFieldList`

接口名称：获取自定义字段列表

变更类型：新增接口

查询参数：

customize_type

说明：自定义字段业务层级

可选值：3、4、6、17、18

版本说明：17.5.0 新增

返回字段：

data[].id

说明：自定义字段 ID

版本说明：17.5.0 新增

data[].name

说明：自定义字段名称

版本说明：17.5.0 新增

data[].customize_type

说明：字段所属业务层级

版本说明：17.5.0 新增

data[].type

说明：字段类型，1-文本、2-单选、3-数值计算、4-数值

版本说明：17.5.0 新增

data[].options

说明：单选项列表；非单选字段为空数组

版本说明：17.5.0 新增

边界说明：当前接口不直接返回 decimal_scale 或计算公式；数值精度和计算逻辑由服务端字段配置维护

自定义字段统一契约

请求结构 `CustomizeFieldInput`

{
  "id": 101,
  "value": "123.4567",
  "select_id": 0
}

字段	类型	必填	说明
`id`	integer	是	自定义字段 ID，必须属于当前接口层级
`value`	string/null	否	字段值；数值建议使用字符串提交，按后台精度配置归一化
`select_id`	integer	否	单选项 ID；非单选字段传 `0` 或省略

请求规则：

customize_fields 必须是数组、null 或不传；数组成员必须是对象。

同一层级内字段 ID 不得重复，字段不能跨层级提交。

单选项必须属于当前字段；非单选字段的 select_id 按 0 处理。

数值字段支持后台配置的多位小数精度，建议使用字符串提交避免精度丢失。

数值计算字段由系统计算；客户端提交的计算字段项整体忽略，不作为最终结果保存。

编辑接口中：缺失或 null 表示不修改，[] 表示清空手工字段，非空数组表示覆盖提交的手工字段。

响应结构 `CustomizeFieldValue`

{
  "id": 101,
  "name": "客户折扣",
  "value": "12.34567",
  "select_id": 0
}

字段	类型	说明
`id`	integer	自定义字段 ID
`name`	string	自定义字段名称，可直接用于展示
`value`	string	字段值；单选返回选项名称，数值及计算结果按字符串返回
`select_id`	integer	单选项 ID；非单选字段为 `0`

没有可返回字段时，业务接口统一返回：

{
  "customize_fields": []
}

自定义字段业务层级

customize_type	字段级别	主要使用位置
3	订单级	订单顶层、销售订单来源对账单顶层
4	订单明细级	订单商品行、销售订单来源对账明细
6	客户对账单级	非订单、非退货来源的客户对账单顶层
17	退货级	退货单顶层、退货或仅退款来源对账单顶层
18	退货明细级	退货商品行、退货来源对账明细

对接方建议

调用写入接口前，先通过 Common/CustomizeFieldList 获取当前层级可用字段和单选项，不要硬编码字段 ID。

读取业务接口时按 id/name/value/select_id 四字段解析；对新增字段保持向前兼容，不要因出现未知字段 ID 而报错。

数值和计算字段的 value 始终按字符串处理，不要先转为浮点数再参与金额或精度敏感计算。

计算字段由系统维护，调用方只读展示，不提交计算结果作为可信值。

编辑场景必须区分参数缺失、null 和空数组，避免误清空历史自定义字段。

未启用退货自定义字段能力时，退货级和退货明细级字段可能返回空数组。

版本信息#

本版本变更概览#

接口变更明细#

1. POST /openApiV2/Order/Create#

2. GET /openApiV2/Order/pageList#

3. GET /openApiV2/Order/detail#

4. POST /openApiV2/Order/Modify#

5. POST /openApiV2/OrderReturn/Create#

6. GET /openApiV2/OrderReturn/pageList#

7. GET /openApiV2/OrderReturn/detail#

8. POST /openApiV2/OrderReturn/edit#

9. GET /openApiV2/AccountBill/PageList#

10. GET /openApiV2/AccountBill/Detail#

11. GET /openApiV2/Common/CustomizeFieldList#

自定义字段统一契约#

请求结构 CustomizeFieldInput#

响应结构 CustomizeFieldValue#

自定义字段业务层级#

对接方建议#

版本信息

本版本变更概览

接口变更明细

1. `POST /openApiV2/Order/Create`

2. `GET /openApiV2/Order/pageList`

3. `GET /openApiV2/Order/detail`

4. `POST /openApiV2/Order/Modify`

5. `POST /openApiV2/OrderReturn/Create`

6. `GET /openApiV2/OrderReturn/pageList`

7. `GET /openApiV2/OrderReturn/detail`

8. `POST /openApiV2/OrderReturn/edit`

9. `GET /openApiV2/AccountBill/PageList`

10. `GET /openApiV2/AccountBill/Detail`

11. `GET /openApiV2/Common/CustomizeFieldList`

自定义字段统一契约

请求结构 `CustomizeFieldInput`

响应结构 `CustomizeFieldValue`

自定义字段业务层级

对接方建议