POST create 提交批量订单

地址：/api/order-batch/create　·　说明：一次性提交多笔订单，返回批次 ID 与校验统计。

异步处理：提交后立即返回批次 ID，订单将异步处理，请用 detail 查询处理进度与结果（建议轮询至批次状态为「处理完成」）。单条订单失败不影响同批次其它订单。

发货地址（二选一）：整批发货地址有两种传法，任选其一：
① 传 vendor_address_id（已保存地址，与本系统「上传 Excel 打单」一致）；
② 直接传 shipper_* 发件人字段（见下方「发件人字段」表），其中 shipper_name / shipper_street1 / shipper_country / shipper_state / shipper_city 必填。
两者都不传将返回参数错误。

注意：通过上传 Excel 打单创建批次时，只支持 vendor_address_id，不接受 shipper_* 字段；shipper_* 仅适用于本接口（API 数组提交）。

参数说明

参数	必填	类型	说明
`vendor_address_id`	二选一	int	发货地址 ID（整批统一使用该发货地址）；*与下方 `shipper_` 二选一*（未传时须传 shipper_ 字段）
`orders`	是	array	订单数组（支持 JSON 数组请求体，或表单字段中的 JSON 字符串），元素字段见下表
`shipping_code`	是	string	批次渠道编码（必填）；与 shipping_service 须同时填写；整批统一，对批次内全部订单生效
`shipping_service`	是	string	批次服务编码（必填）；与 shipping_code 成对填写；整批统一，对批次内全部订单生效
`remark`	选填	string	批次备注

发件人字段 shipper_*（与 vendor_address_id 二选一）

整批发件人信息。若未传 vendor_address_id，则须直接传以下字段；其中 shipper_name / shipper_street1 / shipper_country 必填（其余选填），等价于使用一份「临时」发件地址，仅作用于本批次。

参数	必填	类型	说明
`shipper_name`	二选一时必填	string	发件人姓名（未传 vendor_address_id 时必填）
`shipper_company`	选填	string	发件公司
`shipper_telphone`	选填	string	联系电话
`shipper_email`	选填	string	邮箱
`shipper_country`	二选一时必填	string	国家（如 `US`；未传 vendor_address_id 时必填）
`shipper_state`	二选一时必填	string	州 / 省（未传 vendor_address_id 时必填）
`shipper_city`	二选一时必填	string	城市（未传 vendor_address_id 时必填）
`shipper_street1`	二选一时必填	string	街道地址第一行（未传 vendor_address_id 时必填）
`shipper_street2`	选填	string	街道地址第二行
`shipper_zipcode`	选填	string	邮编

orders[] 元素字段

参数	必填	类型	说明
`recipient_name`	是	string	收件人姓名
`recipient_street1`	是	string	收件地址第一行
`recipient_city`	是	string	收件城市
`recipient_state`	是	string	收件州 / 省
`recipient_country`	是	string	收件国家（二字码，如 `US`）
`weight` / `length` / `width` / `height`	是	number	重量与长宽高，均须大于 0
`reference`	选填	string	订单参考号
`recipient_company`	选填	string	收件公司
`recipient_street2`	选填	string	收件地址第二行
`recipient_telphone`	选填	string	收件人电话
`recipient_zipcode`	选填	string	收件邮编
`package_name`	选填	string	包裹品名
`weight_unit`	选填	string	重量单位：`kg` / `g` / `lb` / `oz`，默认 `lb`
`length_unit`	选填	string	尺寸单位：`cm` / `m` / `in`，默认 `in`
`ship_date`	选填	string	发货日期
`is_signature`	选填	int	是否需要签名；`1`/`yes` 视为是，其余为否
`is_insurances`	选填	int	是否需要保险；`1`/`yes` 视为是，其余为否
`remark`	选填	string	订单备注

注意：shipping_code 与 shipping_service 必须成对出现—— 渠道在批次级统一设置，对批次内全部订单生效；两者须同时填写，只填其一将返回参数错误。

请求示例

POST /api/order-batch/create
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "vendor_address_id": 12,
    "shipping_code": "iusps",
    "shipping_service": "zdgj",
    "remark": "batch 20260921",
    "orders": [
        {
            "reference": "ORDER-20260921-001",
            "recipient_name": "Jane",
            "recipient_street1": "456 Oak Ave",
            "recipient_city": "New York",
            "recipient_state": "NY",
            "recipient_country": "US",
            "recipient_zipcode": "10001",
            "weight": 3.3,
            "length": 12,
            "width": 10,
            "height": 5,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

请求示例 ②（直接传 shipper_*，不传 vendor_address_id）

POST /api/order-batch/create
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "shipping_code": "iusps",
    "shipping_service": "zdgj",
    "remark": "batch 20260921-shipper",
    "shipper_name": "John Doe",
    "shipper_company": "ACME Co.",
    "shipper_telphone": "+1 213 555 0100",
    "shipper_country": "US",
    "shipper_state": "CA",
    "shipper_city": "Los Angeles",
    "shipper_street1": "123 Main St",
    "shipper_street2": "Suite 200",
    "shipper_zipcode": "90001",
    "orders": [
        {
            "reference": "ORDER-20260921-001",
            "recipient_name": "Jane",
            "recipient_street1": "456 Oak Ave",
            "recipient_city": "New York",
            "recipient_state": "NY",
            "recipient_country": "US",
            "recipient_zipcode": "10001",
            "weight": 3.3,
            "length": 12,
            "width": 10,
            "height": 5,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

返回示例

{
    "success": true,
    "message": "Batch submitted, processing asynchronously. Poll detail by batch_id.",
    "code": 200,
    "data": {
        "batch_id": 88,
        "batch_no": "B20260921153000ab12",
        "total_count": 2,
        "success_count": 1,
        "fail_count": 1
    }
}

data 字段	类型	说明
`batch_id`	int	批次 ID，用于 `detail` 查询处理结果
`batch_no`	string	批次编号
`total_count`	int	提交总条数
`success_count`	int	校验通过、进入处理的条数
`fail_count`	int	校验未通过的条数（原因见 `detail` 明细）

📦 接口文档 🌐 English Version