5-3. 编辑订单

接口名称

编辑运单详情

接口地址

/api/shipper/v1/parcel/order/edit

请求方式

POST

请求头

参数	类型	必填	说明
sessionId	String	是	登录会话ID
language	String	是	语言
Content-Type	String	是	application/json

语言取值：

值	说明
zh_CN	中文
en_US	英文

请求参数

一、订单基础信息 (OrderInfo)

字段	类型	必填	校验规则	说明
facility	String	是	必填	发件人网点代码，"*"表示默认网点
channel	Number	是	必填	服务渠道ID，联动获取服务选项和付税方式
serviceOption	String	否		服务选项代码，根据选择的channel动态获取
billingPartyName	String	否		付款方名称
platform	String	否		电子商务平台
lockerService	Boolean	否		储物柜服务（仅addressCountry='RU'时显示）
authorityToLeave	Boolean	否		授权放置（ATL），仅channel∈2,3,42,585,586,587时显示

二、收件人地址信息 (RecipientAddressInfo)

字段	类型	必填	校验规则	说明
recipientName	String	是	必填	收件人姓名
recipientCompany	String	否		收件人公司
phone	String	否		收件人电话
email	String	否		收件人邮箱
addressLine1	String	是	必填	地址第一行
addressLine2	String	否		地址第二行
addressLine3	String	否		地址第三行
city	String	是	必填	城市
state	String	否		省/州
postcode	String	是	必填	邮编

注意：收件人地址信息会被组装成address对象提交，需包含addressId（编辑时必传）

三、包裹信息 (ParcelInfo)

字段	类型	必填	校验规则	说明
trackingNo	String	否		跟踪号（编辑时有值，不可修改）
refNo	String	是	必填	参考号
refNo1	String	否		参考号1
dangerousGoods	Boolean	否		包含其他危险品
incoterm	String	否		付税方式，可选值见下文"付税方式选项"
invoiceCurrency	String	是	必填	发票币种
invoiceValue	Number	是	≥0	发票金额
instruction	String	否		装运提示
weight	Number	否	≥0	重量
weightUnit	String	是	必填	重量单位，可选值：kg、lb
volume	Number	否	≥0	体积
description	String	是	必填	货物描述（英文）
nativeDescription	String	否		货物描述（中文）
length	Number	否	≥0	长度
width	Number	否	≥0	宽度
height	Number	否	≥0	高度
dimensionUnit	String	否		体积单位，可选值：cm、in、m
batteryPacking	String	否		电池包装（系统码：BOT001）
batteryType	String	否		电池类型（系统码：BPT001）
recipientTaxId	String	否		收件人税号
sku	String	否		拣货清单

四、扩展字段 extendData (共31个字段)

扩展字段包含以下内容：

序号	字段	类型	必填	显示条件	说明
1	vendorid	String	否	始终显示	Vendor ID
2	agentID	String	否	始终显示	代理ID
3	sortCode	String	否	始终显示	分拣码
4	purpose	String	否	始终显示	用途
5	material	String	否	始终显示	材质
6	codAmount	Number	否	始终显示	COD金额，≥0
7	codCurrency	String	否	始终显示	COD币种
8	receiverKycType	String	否	始终显示	收件人KYC类型
9	receiverKycNo	String	否	始终显示	收件人KYC号码
10	injectPort	String	否	始终显示	注入口岸
11	abnnumber	String	否	addressCountry='AU'	澳洲生意注册号码（ABN）
12	gstexemptioncode	String	否	addressCountry='AU'	免税码
13	platformorderno	String	否	特定服务	平台订单号，channel∈139,205,237,238,249,273,275,293,345,362,364
14	coveramount	Number	否	addressCountry='AU'	投保金额
15	senderTaxId	String	否	始终显示	发件人税号
16	postage	String	否	特定服务	邮费，channel∈946,1161
17	icms	String	否	特定服务	ICMS税，channel∈946,1161
18	vat	String	否	特定服务	VAT税，channel∈698,946,1161
19	originPort	String	否	特定服务	起运港，channel∈698,721,724,722,725,723,726,786
20	osnr	String	否	特定服务	OSNR，channel∈1062,1063，值为"0"或"1"
21	specialHandlingType	String	否	特定服务	特殊处理类型，channel∈1062,1063，可选值：SH05、SH06、SH07、SH09、SH10
22	holdForPickup	String	否	特定服务	等待提货，channel∈1062,1063，值为"N"或"Y"
23	residentialSignatureRequired	String	否	特定服务	需要居民签名，channel∈1062,1063，值为"N"或"Y"
24	saturdayDelivery	String	否	特定服务	周六配送，channel∈1062,1063，值为"N"或"Y"
25	exportInvoiceValue	Number	否	始终显示	出口申报金额，数字格式
26	exportInvoiceCurrency	String	否	始终显示	出口申报币种
27	imei1	String	否	特定服务	IMEI1，channel=1153
28	imei2	String	否	特定服务	IMEI2，channel=1153
29	warehouseID	String	否	始终显示	仓库ID
30	shipperOrganizationCode	String	否	始终显示	发件人企业统一社会信用代码，展示在发货人地址模块，提交时放入extendData
31	shipperCompanyName	String	否	始终显示	发件人公司名，展示在发货人地址模块，提交时放入extendData

注意：

以上31个字段会被收集到extendData对象中提交
如果接口未返回某字段，传空字符串""
最后2个字段（shipperOrganizationCode、shipperCompanyName）虽然展示在发货人地址模块，但提交时放入extendData对象中

注意：extendData字段如果接口未返回，传空字符串""

五、物品信息 parcelItems (数组)

字段	类型	必填	说明
uuid	String	否	物品UUID，编辑时必传，新增时为空
sku	String	否	物品标示SKU
description	String	是	物品描述（英文）
nativeDescription	String	否	物品描述（中文）
hsCode	String	否	HS编码
originCountry	String	否	原产地国家代码
unitValue	Number	是	单价
itemCount	Number	是	数量
weight	Number	是	重量
productURL	String	否	产品链接URL
warehouseNo	String	否	仓库号
itemExportInvoiceValue	Number	否	出口申报金额，提交时放入extendData
itemExportInvoiceCurrency	String	否	出口申报币种，提交时放入extendData
pictures	Array	否	物品图片URL数组，最多5张

六、收件人地址对象 address

字段	类型	必填	说明
addressId	String	是	地址ID，编辑时必传
country	String	是	国家代码，从addressCountry获取
addressLine1	String	是	地址第一行
addressLine2	String	否	地址第二行
addressLine3	String	否	地址第三行
city	String	是	城市，从addressCity获取
state	String	否	省/州，从addressState获取
postcode	String	是	邮编，从addressPostcode获取

七、发货人地址对象 shipperAddress

字段	类型	必填	说明
addressId	String	是	地址ID，编辑时必传
country	String	是	国家代码，从shipperAddressCountry获取
addressLine1	String	是	地址第一行，从shipperAddressLine1获取
addressLine2	String	否	地址第二行，从shipperAddressLine2获取
addressLine3	String	否	地址第三行，从shipperAddressLine3获取
city	String	是	城市，从shipperAddressCity获取
state	String	否	省/州，从shipperAddressState获取
postcode	String	是	邮编，从shipperAddressPostCode获取

注意：shipperOrganizationCode和shipperCompanyName虽然展示在发货人地址模块，但提交时放入extendData对象中，不在shipperAddress对象内

八、退货地址对象 returnAddress

字段	类型	必填	说明
addressId	String	是	地址ID，编辑时必传
addressLine1	String	是	退货地址第一行，从returnAddressLine1获取
addressLine2	String	否	退货地址第二行，从returnAddressLine2获取
addressLine3	String	否	退货地址第三行，从returnAddressLine3获取
city	String	是	退货城市，从returnAddressCity获取
state	String	否	退货省/州，从returnAddressState获取
postcode	String	是	退货邮编，从returnAddressPostCode获取
country	String	是	退货国家，从returnAddressCountry获取
returnName	String	否	退货人姓名
returnPhone	String	否	退货联系电话
returnOption	String	否	退货选项，可选值：Destroy、Return、Forward、Change

九、在线投保信息 insur

字段	类型	必填	校验规则	说明
uuid	String	否		投保UUID，编辑时必传
cancel	Boolean	是		是否取消投保，true=不投保（删除insur对象），false=投保
insureType	String	条件必填	投保时必填	被保险人类型：02=公司，01=个人
insuredContackName	String	条件必填	投保时必填	被保人真实姓名
insuredName	String	条件必填	投保时必填	被投保人联系人姓名
insureAmount	Number	否		投保额
insureCurrency	String	否		投保额币种，可选值见下文"投保额币种"
insureCardNo	String	条件必填	投保时必填	组织机构代码证（insureType=02时）或身份证号码（insureType=01时）
projectNo	String	否		保单号

投保字段校验规则：

cancel=true：不投保，提交时删除整个insur对象
cancel=false：投保时必须填写insuredContackName、insuredName、insureCardNo
insureType=02（公司）：insureCardNo为组织机构代码证
insureType=01（个人）：insureCardNo为身份证号码

十、其他参数

字段	类型	必填	说明
uuid	String	是	订单UUID，编辑时必传，从服务端返回的orderDetial.uuid获取
actualWeight	Number	否	实际重量，从服务端返回，原样提交
actualVolume	Number	否	实际体积，从服务端返回，原样提交
actualLength	Number	否	实际长度，从服务端返回，原样提交
actualWidth	Number	否	实际宽度，从服务端返回，原样提交
actualHeight	Number	否	实际高度，从服务端返回，原样提交
girth	Number	否	周长，从服务端返回（值≠-1时），原样提交
actualGirth	Number	否	实际周长，从服务端返回（值≠-1时），原样提交

下拉框选项数据

1. 体积单位选项 (DIMENSIONUNIT_OPTIONS)

值	说明
cm	厘米
m	米
in	英寸

2. 退货选项 (RETURN_OPTIONS)

值	说明
Destroy	销毁
Return	退回
Forward	转寄
Change	地址更改

3. 投保额币种 (INSURANCE_CURRENCY_OPTIONS)

值	说明
RMB	人民币
HKD	港币
USD	美元
GBP	英镑
JPY	日元
SGD	新加坡元
CAD	加拿大元
EUR	欧元
AUD	澳元

4. 付税方式选项 (INCOTERM_OPTIONS_DEFAULT)

值	说明
DDU	未完税交货
DDP	完税后交货

5. 扣留类型 (HELDS_OPTIONS，共32种)

值	说明
0	正常（noNeed）
1	客户扣货（customerHold）
2	操作站扣货（carrierHold）
3	财务扣货（financialHold）
4	抛货扣货（bulkyCargo）
5	带电扣货（batteryHold）
6	违禁品扣货（contrabandHold）
7	其他扣货（otherHold）
8	退货扣货（returnHold）
9	KYC扣货（kycHold）
10	超载扣货（overloadHold）
11	超长扣货（overlengthHold）
12	包装不符扣货（packingProblemsHold）
23	重量有差异（differenceInWeight）
25	重复收件人（repeatRecipient）
26	超载警告（overloadWarn）
27	超重超尺寸（overSize）
29	申报不符（nonConformanceDeclaration）
30	HsCode扣货（hsCodeHold）
31	无可用服务（noAvailableService）
32	订单超时扣货（overTime）

参数联动关系

1. 国家 → 服务列表联动

2. 服务 → 服务选项联动

3. 服务ID → 付税方式可选值规则

// 服务ID与付税方式可选值对应关系：
服务ID=28,35,36,37,58,67,274：仅DDU
服务ID=29：美国(US)只能DDP，英国(GB)和其他可DDU/DDP
服务ID=57,174,273：仅DDP
服务ID=139：仅DDP（代码中配置为DDP、DDU，但实际仅DDP可用）
服务ID=140,141,142,198,238,249,377：DDP、DDU
服务ID=0：DDU、DDP（默认）
其他：DDU、DDP

4. 国家 → 储物柜服务显示

// 显示条件：addressCountry === 'RU'
// 字段：lockerService（Boolean）
// 仅俄罗斯显示储物柜选项

5. 服务 → ATL授权放置显示

// 显示条件：channel ∈ [2, 3, 42, 585, 586, 587]
// 字段：authorityToLeave（Boolean）
// 仅特定服务渠道显示ATL选项

6. 国家 → 澳洲特定字段显示

// 显示条件：addressCountry === 'AU'
// 显示字段：
//   - abnnumber（澳洲生意注册号码）
//   - gstexemptioncode（免税码）
//   - coveramount（投保金额）

7. 服务 → 巴西特定字段显示

// 显示条件：channel ∈ [946, 1161]
// 显示字段：
//   - postage（邮费）
//   - icms（ICMS税）
//   - vat（VAT税）

8. 服务 → 印度特定字段显示

// 显示条件：channel ∈ [698, 721, 724, 722, 725, 723, 726, 786]
// 显示字段：originPort（起运港）
// 显示条件：channel ∈ [1062, 1063]
// 显示字段：
//   - osnr
//   - specialHandlingType
//   - holdForPickup
//   - residentialSignatureRequired
//   - saturdayDelivery

9. 服务 → 平台订单号显示

// 显示条件：channel ∈ [139, 205, 237, 238, 249, 273, 275, 293, 345, 362, 364]
// 显示字段：platformorderno

10. 服务 → IMEI字段显示

// 显示条件：channel = 1153
// 显示字段：
//   - imei1
//   - imei2

请求示例

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "facility": "*",
  "channel": 29,
  "serviceOption": "STANDARD",
  "billingPartyName": "Test Company",
  "platform": "eBay",
  "lockerService": false,
  "authorityToLeave": true,
  "recipientName": "John Smith",
  "recipientCompany": "Smith Ltd",
  "phone": "+44 20 1234 5678",
  "email": "john.smith@example.com",
  "trackingNo": "TRACK123456",
  "refNo": "REF123456",
  "refNo1": "REF789012",
  "dangerousGoods": false,
  "incoterm": "DDP",
  "invoiceCurrency": "GBP",
  "invoiceValue": 25.99,
  "instruction": "Please call before delivery",
  "weight": 1.5,
  "weightUnit": "kg",
  "volume": 0.003,
  "description": "Cotton T-Shirt",
  "nativeDescription": "纯棉T恤",
  "length": 30,
  "width": 20,
  "height": 5,
  "dimensionUnit": "cm",
  "batteryPacking": "NOBATTERY",
  "batteryType": "NOBATTERY",
  "recipientTaxId": "GB123456789",
  "sku": "SKU001",
  "actualWeight": 1.6,
  "actualVolume": 0.0032,
  "actualLength": 30.5,
  "actualWidth": 20.5,
  "actualHeight": 5.5,
  "girth": 90,
  "actualGirth": 92,
  "address": {
    "addressId": "addr-123-456-789",
    "country": "GB",
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "addressLine3": "London",
    "city": "London",
    "state": "England",
    "postcode": "SW1A 1AA"
  },
  "parcelItems": [
    {
      "uuid": "item-uuid-001",
      "sku": "ITEM001",
      "description": "Cotton T-Shirt - Blue",
      "nativeDescription": "纯棉T恤-蓝色",
      "hsCode": "61091000",
      "originCountry": "CN",
      "unitValue": 12.99,
      "itemCount": 2,
      "weight": 0.3,
      "productURL": "https://example.com/product/123",
      "warehouseNo": "WH-SZ-001",
      "pictures": [
        "https://example.com/images/item1-front.jpg",
        "https://example.com/images/item1-back.jpg"
      ],
      "extendData": {
        "itemExportInvoiceValue": 15,
        "itemExportInvoiceCurrency": "GBP"
      }
    }
  ],
  "shipperAddress": {
    "addressId": "ship-addr-123-456",
    "country": "CN",
    "addressLine1": "456 Shipping Street, Suite 100",
    "addressLine2": "Futian District",
    "addressLine3": "Shenzhen",
    "city": "Shenzhen",
    "state": "Guangdong",
    "postcode": "518000"
  },
  "returnAddress": {
    "addressId": "ret-addr-123-456",
    "addressLine1": "789 Return Street",
    "addressLine2": "Warehouse B",
    "addressLine3": "Industrial Zone",
    "city": "Shenzhen",
    "state": "Guangdong",
    "postcode": "518001",
    "country": "CN",
    "returnName": "Return Department",
    "returnPhone": "+86 13900139000",
    "returnOption": "Return"
  },
  "insur": {
    "uuid": "ins-uuid-001",
    "cancel": false,
    "insureType": "01",
    "insuredContackName": "Zhang San",
    "insuredName": "Li Si",
    "insureAmount": 100,
    "insureCurrency": "GBP",
    "insureCardNo": "110101199001001234",
    "projectNo": "POL2023001"
  },
  "extendData": {
    "vendorid": "VENDOR001",
    "agentID": "AGENT001",
    "sortCode": "SORT001",
    "purpose": "GIFT",
    "material": "COTTON",
    "codAmount": 0,
    "codCurrency": "",
    "receiverKycType": "INDIVIDUAL",
    "receiverKycNo": "KYC123456",
    "injectPort": "LHR",
    "abnnumber": "",
    "gstexemptioncode": "",
    "platformorderno": "EBAY-ORDER-123",
    "coveramount": 100,
    "senderTaxId": "CN123456789",
    "postage": "",
    "icms": "",
    "vat": "GB20",
    "originPort": "CN",
    "osnr": "",
    "specialHandlingType": "",
    "holdForPickup": "",
    "residentialSignatureRequired": "",
    "saturdayDelivery": "",
    "exportInvoiceValue": 30,
    "exportInvoiceCurrency": "GBP",
    "imei1": "",
    "imei2": "",
    "warehouseID": "",
    "shipperOrganizationCode": "91310000MA1X4QC",
    "shipperCompanyName": "Shenzhen Tech Co., Ltd"
  }
}

返回示例

{
  "success": true,
  "code": "0",
  "data": {
    "warnings": [
      "包裹重量可能超过服务限制"
    ],
    "errors": [],
    "errorMessage": null
  }
}

返回字段说明

字段	类型	说明
success	Boolean	请求是否成功
code	String	响应状态码，"0"表示成功
data	Object	返回数据对象
data.warnings	Array	警告信息列表，不影响订单编辑
data.errors	Array	错误信息列表，阻止订单编辑
data.errorMessage	String	错误消息概要

错误码说明

code	说明
0	成功
1001	参数校验失败
1002	服务不可用
1003	国家不支持该服务
1004	物品信息必填
1005	发货人邮箱格式错误
1006	收件人地址信息不完整
1007	包裹重量必须大于等于0
1008	发票金额必须大于等于0
1009	投保信息不完整

业务规则说明

1. 编辑权限控制

订单状态判断：

status >= 0 且 status < 2：可编辑
其他状态：不可编辑
虚拟服务判断：extendData.virtualId存在时为虚拟服务，不可编辑

可编辑字段（非虚拟服务且状态在可编辑范围内）：

serviceOption
platform
lockerService
authorityToLeave
收件人地址信息
包裹信息
物品信息
发货人地址信息
退货地址信息
投保信息

2. 表单校验规则

订单信息模块（OrderInfo）：

facility：必填
channel：必填

收件人地址模块（RecipientAddressInfo）：

recipientName：必填
addressLine1：必填
city：必填
postcode：必填

包裹信息模块（ParcelInfo）：

refNo：必填
invoiceValue：必填，≥0
description：必填
weight：≥0
volume：≥0
length：≥0
width：≥0
height：≥0
codAmount：≥0
exportInvoiceValue：数字格式

发货人地址模块（ShipperAddressInfo）：

addressLine1（shipperAddressLine1）：必填
city（shipperAddressCity）：必填
shipperEmail：邮箱格式校验

退货地址模块（ReturnAddressInfo）：

city（returnAddressCity）：必填
addressLine1（returnAddressLine1）：必填

3. 数据组装规则

收件人地址字段会被组装成address对象：

addressId：从服务端返回的orderDetial.addressId获取
country：从addressCountry获取
addressLine1-3：从对应字段获取
city：从addressCity获取
state：从addressState获取
postcode：从addressPostcode获取

不直接提交addressCountry、addressLine1等原始字段
同理，shipperAddress和returnAddress也需要从对应字段组装

4. 扩展字段处理规则

包含35个字段，详见上文"扩展字段 extendData"
如果接口未返回某字段，传空字符串""
shipperOrganizationCode和shipperCompanyName：

展示在发货人地址模块
从服务端的extendData中提取到根级别
提交时收集回extendData对象中

5. 物品信息处理规则

新增物品：uuid为空或以"add-"开头，提交时删除uuid字段
编辑物品：保留原uuid
删除物品：标记isDelete=true，只保留uuid字段
物品的extendData包含：

itemExportInvoiceValue：出口申报金额
itemExportInvoiceCurrency：出口申报币种

6. 投保信息校验逻辑

cancel=true：不投保

提交时删除整个insur对象

cancel=false：投保

必须填写：insuredContackName、insuredName、insureCardNo
insureType=02（公司）：insureCardNo为组织机构代码证
insureType=01（个人）：insureCardNo为身份证号码

7. 响应处理规则

warnings有值，errors为空：

显示警告提示框
订单编辑成功，关闭页面

warnings有值，errors有值：

先显示警告提示框（用户点继续）
再显示错误提示框
订单编辑失败

errors有值，warnings为空：

显示错误提示框
订单编辑失败

两者都为空：

显示保存成功
关闭页面

8. 实际测量字段处理

actualWeight、actualVolume、actualLength、actualWidth、actualHeight：

从服务端返回
不可编辑
原样提交

girth、actualGirth：

仅在值≠-1时从服务端返回
原样提交

注意事项

编辑与创建的区别

编辑时必须提供uuid参数
编辑时需要提供addressId（收件人、发货人、退货地址）
编辑时需要提供actualWeight等实际测量字段并原样提交
编辑时某些字段可能被禁用，取决于订单状态
编辑时trackingNo不可修改

重量和尺寸单位

重量单位：kg（千克）、lb（磅）
体积单位：cm（厘米）、in（英寸）、m（米）
weightUnit和dimensionUnit必须与实际填写值保持一致

物品信息

至少需要一个物品信息
description（英文描述）和nativeDescription（中文描述）至少填写一个
pictures数组最多5张图片URL

发货人邮箱

必须符合邮箱格式校验

退货选项

必须选择一项：Destroy、Return、Forward、Change
returnPhone为必填字段（编辑时可能根据实际情况调整）

虚拟服务

如果extendData.virtualId存在，表示是虚拟服务
虚拟服务时更多字段会被禁用

页面树结构