页面历史

接口名称

编辑运单详情

接口地址

代码块
/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. 服务 → 服务选项联动

...

代码块
{ "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存在时为虚拟服务，不可编辑

...

页面树结构

版本比较

旧版本 3

新版本 4

标识