编辑订单

批量编辑【订单管理】模块中“待审核”状态的自发货订单仓库、物流方式、报关信息及订单包裹预估规格。

接口信息

请求参数

特殊属性编码

请求示例

仅编辑仓库和物流方式：

{
    "order_list": [
        {
            "global_order_no": "103741652556357632",
            "logistics": {
                "sys_wid": 1300,
                "logistics_type_id": 4406
            }
        }
    ]
}

仅编辑报关：

{
    "order_list": [
        {
            "global_order_no": "103741652556357632",
            "modify_declared": 1,
            "declared_info": [
                {
                    "sku": "LOCAL-SKU-001",
                    "id": 12345,
                    "cn_name": "棉质上衣",
                    "en_name": "Cotton top",
                    "unit_price": "12.50",
                    "currency_code": "USD",
                    "weight": "300",
                    "quantity": 2,
                    "special_attr": ["7"]
                }
            ]
        }
    ]
}

仅编辑包裹规格：

{
    "order_list": [
        {
            "global_order_no": "103741652556357632",
            "logistics": {
                "pre_pkg_length": "30",
                "pre_pkg_width": "20",
                "pre_pkg_height": "10",
                "pre_weight": "900"
            }
        }
    ]
}

同时编辑物流、包裹规格和报关：

{
    "order_list": [
        {
            "global_order_no": "103741652556357632",
            "logistics": {
                "sys_wid": 1300,
                "logistics_type_id": 4406,
                "pre_pkg_length": 30,
                "pre_pkg_width": 20,
                "pre_pkg_height": 10,
                "pre_weight": 900
            },
            "modify_declared": 1,
            "declared_info": [
                {
                    "sku": "LOCAL-SKU-001",
                    "id": 12345,
                    "cn_name": "棉质上衣",
                    "en_name": "Cotton top",
                    "unit_price": "12.50",
                    "currency_code": "USD",
                    "weight": "300",
                    "quantity": 2,
                    "special_attr": ["7"]
                }
            ]
        }
    ]
}

返回结果

Json Object

当前接口全部成功时使用默认成功码 0，不是 UPDATE_ORDER_SUCCESS 枚举定义的 10002。接口没有成功明细列表及成功/失败数量字段，公共响应字段不能作为订单处理计数。响应中的系统订单号为 long，客户端也应采用支持大整数的方式解析。公共鉴权、请求解析和服务异常等错误不局限于上述三个业务结果码，应同时读取实际错误信息。

返回成功示例

{
    "code": 0,
    "message": "订单更新成功",
    "data": {
        "error_details": []
    },
    "request_id": "ad9c1a8625c74f3ea0525e216374e31a1676514819613",
    "response_time": "2026-09-08 10:00:00"
}

返回部分成功示例

{
    "code": 10001,
    "message": "订单更新部分成功",
    "data": {
        "error_details": [
            {
                "global_order_no": 103741652556357633,
                "error_message": "报关明细【LOCAL-SKU-002】：英文报关名en_name不能为空"
            }
        ]
    },
    "request_id": "ad9c1a8625c74f3ea0525e216374e31a1676514819613",
    "response_time": "2026-09-08 10:00:00"
}

返回失败示例

{
    "code": 10000,
    "message": "订单更新失败",
    "data": {
        "error_details": [
            {
                "global_order_no": 103741652556357632,
                "error_message": "pre_pkg_length、pre_pkg_width、pre_pkg_height、pre_weight必须一起提交且不能为null"
            }
        ]
    },
    "request_id": "ad9c1a8625c74f3ea0525e216374e31a1676514819613",
    "response_time": "2026-09-08 10:00:00"
}

常见错误

附加说明

1. 每个订单至少提交一种有效编辑内容。仅传订单号、空 logistics，或未开启报关编辑时单独传 declared_info，均不构成有效编辑。批量请求中每个订单可以采用不同编辑组合；业务参数不合法的订单不调用 OMS，错误写入 data>>error_details，同批其他合格订单继续处理。仅“物流＋报关”时删除四个 pre_pkg_* 字段；仅“包裹规格＋报关”时删除 sys_wid、logistics_type_id；仅“物流＋包裹规格”时删除 modify_declared、declared_info。
   
   
2. 仅编辑包裹规格时，无需传 sys_wid、logistics_type_id，原仓库和物流方式保持不变，不执行 Java 仓库、物流方式资料查询与校验。仅编辑物流方式时可省略 sys_wid，保留原仓库，但该行为依赖 OMS 已发布“不传 wid 保留原仓库”的修复。不传规格时仍走原有包裹和运费重算流程。仅传 sys_wid 而不传有效 logistics_type_id 不支持。Java 仅透传正数 sys_wid；请使用省略 sys_wid 表示保持原仓库，不要传 0、负数或 null 清空仓库。不需要传 logistics_provider_id，OMS 会根据物流方式查询物流商。
   
   
3. 四项包裹规格使用 BigDecimal 接收，可传 JSON 数字或数字字符串，例如 9.5、"9.5"。四项均未传或均为 null 时不编辑规格；任一项非 null 时四项必须完整且均非 null。四项允许 0，但不接受负数、空字符串或非数字文本，null 不表示清空规格。仅编辑规格时使用订单已有物流信息尝试计算运费；订单尚未选择有效物流方式时，不保证能得到有效报价。小数处理沿用 OMS 现状，不承诺任意小数精度的原样保存、展示及运费试算。
   
   
4. 报关采用整单列表覆盖语义，不是按 SKU 单行增量更新。需要保留的全部报关明细必须提交；漏传的原有明细可能被删除。编辑原有明细应携带原 id，省略 id 或传 0 会按新增行处理，原行可能被删除后重建。declared_info 不支持空列表清空，每个元素也不能为 null。special_attr 未传或传空数组时，OMS 按空数组保存；需要保留原特殊属性时应一并提交。本期不扩展 OMS 独有的其他报关字段；若原订单存在当前 OpenAPI DTO 未开放的报关扩展信息，不能将本接口视为只修改个别字段且自动保留其他字段的补丁接口。页面合并报关行与普通按 SKU 报关行结构不同，不能直接复制页面合并行数据到本接口。
   
   
5. 所有编辑组合要求订单 status=4（待审核），且 status_sub 不为 1、2、5、8；空子状态不被该判断排除，行为与 v2/updateOrder 一致。OMS 仍会执行订单锁、状态和业务校验；报关编辑还受预发货、自动分仓等限制。JSON 格式错误、字段无法反序列化、根列表为空或超过 50 条、缺少系统订单号等请求级错误，可能在逐单处理前被框架拒绝，不能保证按逐单错误结构返回。每个订单通常只返回首先发现的错误。
   
   
6. pre_weight 是订单包裹总重量，declared_info>>weight 是报关明细重量，二者不能互相替代。接口不回写本地 SKU 的报关资料或包装规格。仅保存包裹规格会跳过 SKU 包裹重算，但仍走现有运费试算；保存成功不等于报价成功。后续不带规格的报关编辑、仓库/物流编辑或重新配对，仍可能触发原计算流程并覆盖人工规格。仓库内建表中的四项规格为 DECIMAL(20,2)，OMS 长宽高模型取值保留一位小数，当前不增加统一精度和上限校验，也不承诺重复提交一定会产生更新。
   
   
7. 同一订单的包裹保存、报关和物流编辑在 OMS 同一数据库事务中处理，事务内失败会回滚该订单本次数据库修改。批量请求不使用跨订单整体事务，已成功的其他订单不会随失败订单回滚。
   
   
8. Java 调用 OMS 路径为 POST /openapi/order/edit。Java 的 order_list>>global_order_no、logistics、modify_declared、declared_info 分别映射 OMS 的 global_order_no、logistics_info、modify_declared、declared_info；其中 logistics>>sys_wid 映射 logistics_info>>wid，其他物流字段同名映射。公司和操作人上下文由 Java 服务补充。仅编辑报关时，Java 向 OMS 发送 logistics_info 空对象，避免空成员触发物流编辑；OMS 从 logistics_info 提取四项规格，构造内部 openapi_package_info，该字段不是外部请求参数。
   
   
9. 发布前需确认 OMS 已支持包裹四项提取和校验、锁内状态校验、事务内保存及人工修改快照；包裹保存不使用依赖 logistics_provider_id、logistics_type_id 的 SET_LOGISTICS 日志分支；未提供 wid 或 wid 为 null 时跳过仓库编辑并保留原仓库。应先发布 OMS 支持及修复，再发布 Java 字段开放和报关校验。本期不新增数据库迁移，本文不代表目标环境已部署完成或通过联调验收。