17.2.0版本更新

一、基本信息

版本范围：17.2.0

文档日期：2026-04-28

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

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

二、变更概览

本次更新主要包含以下内容：

新增订单第三方单号查询能力

新增独立的实收变更创建接口

优化原实收变更创建接口，支持重复商品场景

创建订单、批量创建订单支持按需触发下单后通知

出库详情查询支持控制相同商品是否合并

兼容性说明：

本次更新默认保持历史行为不变

新增参数均为非必填

未使用新增参数时，原有接口调用逻辑不受影响

三、详细变更

1. 新增订单第三方单号查询接口

接口路径：GET /openApiV2/Order/ThirdPartyOrderList

变更类型：新增接口

适用场景：根据第三方单号或系统订单号进行映射查询

请求参数：

参数名	类型	必填	说明
`third_party_order_no`	string	否	第三方单号
`order_no`	string	否	系统订单号
`page`	int	否	页码，最小值 1
`page_size`	int	否	每页数量，范围 1-100

返回字段：

字段名	说明
`third_party_order_no`	第三方单号
`order_no`	系统订单号

说明：

支持按第三方单号精确查询

支持按系统订单号精确查询

支持分页返回

2. 原创建实收变更接口能力增强

接口路径：POST /openApiV2/Order/CreateModify

变更类型：兼容性优化

变更说明：

该接口原有能力保留

现在明确支持重复商品场景

仍以 order_commodity_id 作为订单商品唯一标识

请求商品字段要求：

参数名	类型	必填	说明
`order_commodity_id`	int	是	订单商品ID
`change_quantity`	number	是	变更后的实收数量，不能小于 0
`remark`	string	否	商品备注，最大 100 字符

适用建议：

当订单中存在重复商品，且需要准确定位到具体订单商品行时，建议使用本接口

3. 新增独立的创建实收变更接口

接口路径：POST /openApiV2/Order/CreateChangeReceipts

变更类型：新增接口

变更说明：

新增一个面向“非重复商品场景”的实收变更接口

支持通过商品ID，或商品编码 + 单位来识别商品

不支持重复商品场景

请求商品字段要求：

参数名	类型	必填	说明
`commodity_id`	int	否	商品ID，与 `commodity_code` 二选一必传
`commodity_code`	string	否	商品编码，与 `commodity_id` 二选一必传
`unit`	string	条件必填	当仅传 `commodity_code` 时必填
`change_quantity`	number	是	变更后的实收数量，不能小于 0
`remark`	string	否	商品备注，最大 100 字符

适用建议：

当调用方只掌握商品主数据，而不掌握 order_commodity_id 时，可优先使用本接口

若订单中可能存在重复商品，请改用 CreateModify

4. 创建订单接口新增通知开关

接口路径：POST /openApiV2/Order/Create

变更类型：兼容性新增

新增参数：

参数名	类型	必填	默认值	说明
`place_order_notice`	int	否	`0`	创建订单后是否触发下单后通知，`0`-否，`1`-是

说明：

不传该参数时，保持默认不触发通知

传入 1 时，创建成功后会触发下单后的异步通知流程

5. 批量创建订单接口新增通知开关

接口路径：POST /openApiV2/Order/BatchCreate

变更类型：兼容性新增

新增参数：

参数名	类型	必填	默认值	说明
`place_order_notice`	int	否	`0`	批量创建订单后是否触发下单后通知，`0`-否，`1`-是

说明：

不传该参数时，保持默认不触发通知

传入 1 时，批量创建成功后会触发下单后的异步通知流程

6. 出库详情接口新增相同商品合并开关

接口路径：GET /openApiV2/out/detail

变更类型：兼容性新增

新增参数：

参数名	类型	必填	默认值	说明
`commodity_merge`	int	否	`1`	相同商品是否合并返回，`0`-不合并，`1`-合并

说明：

默认值为 1，即默认按商品维度合并同商品明细

当传入 0 时，返回原始逐条明细

合并时会对数量、金额以及库区库位等展示信息进行聚合

7. 旧版 OpenAPI 出库查询同步支持商品合并开关

接口路径：GET /openApi/OutOpen/Query

变更类型：兼容性新增

新增参数：

参数名	类型	必填	默认值	说明
`commodity_merge`	int	否	`1`	相同商品是否合并返回，`0`-不合并，`1`-合并

说明：

为保持新旧开放接口能力一致，旧版出库查询同步支持该参数

默认行为与更新前保持一致

8. 新增采购确认收货接口

接口路径：POST /openApiV2/Purchase/Receipt

变更类型：新增接口

适用场景：采购单审核通过后，开放平台调用方可直接发起确认收货并生成入库单

请求参数：

参数名	类型	必填	说明
`purchase_id`	int	条件必填	采购单ID，与 `purchase_no` 二选一必传
`purchase_no`	string	条件必填	采购单编号，与 `purchase_id` 二选一必传
`in_type`	int	否	入库类型，默认 `2`，支持值 `1/2`
`commodity_list`	array	是	收货商品列表
`commodity_list[].purchase_order_com_id`	int	否	采购明细ID，传入时优先用于定位采购明细
`commodity_list[].commodity_id`	int	否	商品ID，与 `commodity_code` 二选一必传
`commodity_list[].commodity_code`	string	否	商品编码，与 `commodity_id` 二选一必传
`commodity_list[].unit`	string	条件必填	当仅传 `commodity_code` 时必填
`commodity_list[].receive_quantity`	number	是	收货数量，不能小于 0
`commodity_list[].receive_price`	number	是	收货单价，不能小于 0
`commodity_list[].batch_no`	string	否	预算批次号
`commodity_list[].business_batch_no`	string	否	业务批次号
`commodity_list[].production_date`	string	否	生产日期，未传时默认当天日期

返回字段：

字段名	说明
`in_id`	生成的入库单ID
`in_no`	生成的入库单编号

说明：

集采采购单需先审核通过，否则不支持确认收货

联营采购单不支持手动收货

若商品无法唯一识别或存在重复商品，接口会校验失败

9. 采购单收货保存接口补充批次与效期字段支持

接口路径：POST /openApiV2/Purchase/ReceiveSave

变更类型：兼容性新增

新增参数：

参数名	类型	必填	说明
`commodity_list[].business_batch_no`	string	否	业务批次号，长度不能超过 64 个字符
`commodity_list[].expired_date`	string	否	到期日期，需符合日期时间格式校验

说明：

commodity_list[].batch_no 仍作为预算批次号使用

新增参数均为非必填，不传时保持原有收货保存逻辑不变

四、调用方影响说明

可无感升级的场景

仅使用现有订单创建、批量创建、出库详情等接口，且不需要新增能力时，可不做任何改动

未传新增参数时，接口仍按原逻辑处理

建议关注的场景

需要建立“第三方单号 -> 系统订单号”映射关系的调用方，建议接入 ThirdPartyOrderList

订单存在重复商品时，建议使用 CreateModify

只掌握商品主数据且订单不存在重复商品时，可接入 CreateChangeReceipts

若出库单明细对账依赖逐条记录，请在出库详情接口中显式传入 commodity_merge=0

若需要在开放平台下单后立即联动通知流程，请在创建订单接口中显式传入 place_order_notice=1

若需要开放平台直接完成采购确认收货并获取入库单号，可接入 POST /openApiV2/Purchase/Receipt

若仍使用 POST /openApiV2/Purchase/ReceiveSave，且业务侧需要记录业务批次或效期信息，可补充传入 business_batch_no、expired_date

五、兼容性结论

本次更新不涉及签名算法调整

本次更新不涉及鉴权方式调整

本次更新不涉及旧字段删除

本次更新不涉及旧接口下线

本次更新属于兼容性版本更新

六、建议验证项

验证第三方单号查询是否能正确返回订单号映射

验证重复商品订单在 CreateModify 场景下是否能准确定位商品行

验证 CreateChangeReceipts 在商品编码 + 单位模式下是否可正常创建实收变更

验证 place_order_notice=1 时是否能触发预期通知

验证出库详情在 commodity_merge=0/1 两种模式下的返回差异是否符合预期

验证 Purchase/Receipt 在 purchase_id、purchase_no 两种定位方式下都能正常完成确认收货并返回 in_id、in_no

验证 Purchase/Receipt 对重复商品、联营采购单、未审核集采采购单的拦截是否符合预期

验证 Purchase/ReceiveSave 传入 business_batch_no、expired_date 时校验与保存逻辑是否符合预期

七、附注

如需正式对外发送，可补充测试环境时间、生产环境发布时间、对接联系人等信息后直接使用

一、基本信息#

二、变更概览#

三、详细变更#

1. 新增订单第三方单号查询接口#

2. 原创建实收变更接口能力增强#

3. 新增独立的创建实收变更接口#

4. 创建订单接口新增通知开关#

5. 批量创建订单接口新增通知开关#

6. 出库详情接口新增相同商品合并开关#

7. 旧版 OpenAPI 出库查询同步支持商品合并开关#

8. 新增采购确认收货接口#

9. 采购单收货保存接口补充批次与效期字段支持#

四、调用方影响说明#

可无感升级的场景#

建议关注的场景#

五、兼容性结论#

六、建议验证项#

七、附注#

一、基本信息

二、变更概览

三、详细变更

1. 新增订单第三方单号查询接口

2. 原创建实收变更接口能力增强

3. 新增独立的创建实收变更接口

4. 创建订单接口新增通知开关

5. 批量创建订单接口新增通知开关

6. 出库详情接口新增相同商品合并开关

7. 旧版 OpenAPI 出库查询同步支持商品合并开关

8. 新增采购确认收货接口

9. 采购单收货保存接口补充批次与效期字段支持

四、调用方影响说明

可无感升级的场景

建议关注的场景

五、兼容性结论

六、建议验证项

七、附注