创建订单详情
/parcel/order/create |
POST |
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
sessionId | String | 是 | 登录会话ID |
language | String | 是 | 语言 |
Content-Type | String | 是 | application/json |
语言取值:
值 | 说明 |
|---|---|
zh_CN | 中文 |
en_US | 英文 |
一、订单基础信息 (OrderInfo)
字段 | 类型 | 必填 | 校验规则 | 说明 |
|---|---|---|---|---|
facility | String | 是 | 必填 | 发件人网点代码,"*"表示默认网点 |
addressCountry | 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 | 否 | 收件人电话 | |
String | 否 | 收件人邮箱 | ||
addressLine1 | String | 是 | 必填 | 地址第一行 |
addressLine2 | String | 否 | 地址第二行 | |
addressLine3 | String | 否 | 地址第三行 | |
addressCity | String | 是 | 必填 | 城市 |
addressState | String | 否 | 省/州 | |
addressPostcode | String | 是 | 必填 | 邮编 |
注意:收件人地址信息会被组装成address对象提交
三、包裹信息 (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 | 否 | 收件人税号 |
四、扩展字段 extendData (33个字段)
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
vendorid | String | 否 | Vendor ID |
agentID | String | 否 | 代理ID |
sortCode | String | 否 | 分拣码 |
purpose | String | 否 | 用途 |
material | String | 否 | 材质 |
codAmount | Number | 否 | COD金额 |
codCurrency | String | 否 | COD币种 |
receiverKycType | String | 否 | 收件人KYC类型 |
receiverKycNo | String | 否 | 收件人KYC号码 |
injectPort | String | 否 | 注入口岸 |
abnnumber | String | 否 | 澳洲生意注册号码(ABN) |
gstexemptioncode | String | 否 | 免税码 |
platformorderno | String | 否 | 平台订单号 |
coveramount | Number | 否 | 投保金额 |
senderTaxId | String | 否 | 发件人税号 |
postage | String | 否 | 邮费 |
icms | String | 否 | ICMS |
vat | String | 否 | VAT |
originPort | String | 否 | 起运港 |
osnr | String | 否 | OSNR |
specialHandlingType | String | 否 | 特殊处理类型 |
holdForPickup | String | 否 | 等待提货 |
residentialSignatureRequired | String | 否 | 需要居民签名 |
saturdayDelivery | String | 否 | 周六配送 |
exportInvoiceValue | Number | 否 | 出口申报金额 |
exportInvoiceCurrency | String | 否 | 出口申报币种 |
imei1 | String | 否 | IMEI1 |
imei2 | String | 否 | IMEI2 |
warehouseID | String | 否 | IMEI2 |
shipperOrganizationCode | String | 否 | 发件人企业统一社会信用代码(展示在发货人地址模块) |
shipperCompanyName | String | 否 | 发件人公司名(展示在发货人地址模块) |
注意:extendData字段如果接口未返回,传空字符串""
五、物品信息 parcelItems (数组)
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
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 | 否 | 出口申报金额 |
itemExportInvoiceCurrency | String | 否 | 出口申报币种 |
pictures | Array | 否 | 物品图片URL数组,最多5张 |
六、发货人地址信息 shipperAddress
字段 | 类型 | 必填 | 校验规则 | 说明 |
|---|---|---|---|---|
addressId | String | 否 | 地址ID(仅编辑时需要) | |
country | String | 是 | 国家代码 | |
addressLine1 | String | 是 | 必填 | 地址第一行 |
addressLine2 | String | 否 | 地址第二行 | |
addressLine3 | String | 否 | 地址第三行 | |
city | String | 是 | 必填 | 城市 |
state | String | 否 | 省/州 | |
postcode | String | 是 | 邮编 | |
shipperOrganizationCode | String | 否 | 企业统一社会信用代码 | |
shipperCompanyName | String | 否 | 发货人公司名 |
七、退货地址信息 returnAddress
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
addressId | String | 否 | 地址ID(仅编辑时需要) |
addressLine1 | String | 是 | 退货地址第一行 |
addressLine2 | String | 否 | 退货地址第二行 |
addressLine3 | String | 否 | 退货地址第三行 |
city | String | 是 | 退货城市 |
state | String | 否 | 退货省/州 |
postcode | String | 是 | 退货邮编 |
country | String | 是 | 退货国家 |
returnOption | String | 是 | 退货选项,可选值见下文"退货选项" |
returnPhone | String | 是 | 退货联系电话 |
八、在线投保信息 insur
字段 | 类型 | 必填 | 校验规则 | 说明 |
|---|---|---|---|---|
cancel | Boolean | 是 | 是否取消投保,true=不投保,false=投保 | |
insureType | String | 条件必填 | 投保时必填 | 被保险人类型:02=公司,01=个人 |
insuredContackName | String | 条件必填 | 投保时必填 | 被保人真实姓名 |
insuredName | String | 条件必填 | 投保时必填 | 被投保人联系人姓名 |
insureAmount | Number | 否 | 投保额 | |
insureCurrency | String | 否 | 投保额币种,可选值见下文"投保额币种" | |
insureCardNo | String | 条件必填 | 投保时必填 | 组织机构代码证(insureType=02时)或身份证号码(insureType=01时) |
projectNo | String | 否 | 保单号 |
投保字段校验规则:
九、其他参数
字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
uuid | String | 否 | 订单UUID,仅编辑订单时需要 |
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:仅DDU 服务ID=29:美国(US)只能DDP,其他可DDU/DDP 服务ID=57:仅DDP 服务ID=58:仅DDU 服务ID=67,139:仅DDP 服务ID=140,141,142:DDP、DDU 服务ID=174:仅DDP 服务ID=198:DDP、DDU 服务ID=238:DDP、DDU 服务ID=249:DDP、DDU 服务ID=273:仅DDP 服务ID=274:仅DDU 服务ID=377:DDP、DDU 其他服务:DDU、DDP(默认) |
4. 国家 → 储物柜服务显示
// 显示条件:addressCountry === 'RU' // 字段:lockerService(Boolean) // 仅俄罗斯显示储物柜选项 |
5. 服务 → ATL授权放置显示
// 显示条件:channel ∈ [2, 3, 42, 585, 586, 587] // 字段:authorityToLeave(Boolean) // 仅特定服务渠道显示ATL选项 |
6. 国家 → 澳洲特定字段显示
// 显示条件:addressCountry === 'AU' // 显示字段: // - abnnumber(澳洲生意注册号码) // - gstexemptioncode(免税码) |
7. 报价弹框 → 表单回填
// 触发条件:从报价弹框返回数据(getQuotationData) // 回填字段: // - channel(服务ID) // - facility(发件人网点) // - addressCountry(国家) // - weight(重量) // - length, width, height(尺寸) // - invoiceCurrency(发票币种) // - invoiceValue(发票金额) // - addressCity(城市) // - addressState(省/州) // - addressPostcode(邮编) // - weightUnit(重量单位) // - dimensionUnit(体积单位) // 注意:报价数据会覆盖用户已填写的数据 |
curl 'https://tracking-qa.etowertech.com/parcel/order/create' \
-H 'Accept: application/json, text/plain, */*' \
-H 'language: zh_CN' \
-H 'sessionId: MuETuXqSzpU_QQFiSD-dbQ' \
-H 'Content-Type: application/json' \
-d '{
"facility": "*",
"addressCountry": "GB",
"channel": 3,
"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",
"addressLine1": "123 Main Street",
"addressLine2": "Apt 4B",
"addressLine3": "London",
"city": "London",
"state": "England",
"postcode": "SW1A 1AA",
"refNo": "REF123456",
"refNo1": "REF789012",
"dangerousGoods": false,
"incoterm": "DDU",
"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",
"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"
},
"parcelItems": [
{
"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",
"itemExportInvoiceValue": 15,
"itemExportInvoiceCurrency": "GBP",
"pictures": [
"https://example.com/images/item1-front.jpg",
"https://example.com/images/item1-back.jpg"
]
}
],
"shipperAddress": {
"country": "CN",
"addressLine1": "456 Shipping Street, Suite 100",
"addressLine2": "Futian District",
"addressLine3": "Shenzhen",
"city": "Shenzhen",
"state": "Guangdong",
"postcode": "518000"
},
"returnAddress": {
"addressLine1": "789 Return Street",
"addressLine2": "Warehouse B",
"addressLine3": "Industrial Zone",
"city": "Shenzhen",
"state": "Guangdong",
"postcode": "518001",
"country": "CN",
"returnOption": "Return",
"returnPhone": "+86 13900139000"
},
"insur": {
"cancel": false,
"insureType": "01",
"insuredContackName": "Zhang San",
"insuredName": "Li Si",
"insureAmount": 100,
"insureCurrency": "GBP",
"insureCardNo": "110101199001001234"
}
}'
|
{
"success": true,
"code": "0",
"data": {
"warnings": [
"包裹重量可能超过服务限制"
],
"errors": [],
"errorMessage": "",
"result": true,
"uuid": "550e8400-e29b-41d4-a716-446655440000"
},
"errors": []
}
|
字段 | 类型 | 说明 |
|---|---|---|
success | Boolean | 请求是否成功 |
code | String | 响应状态码,"0"表示成功 |
data | Object | 返回数据对象 |
errors | Array | 错误信息列表 |
字段 | 类型 | 说明 |
|---|---|---|
warnings | Array | 警告信息列表,不影响订单创建 |
errors | Array | 错误信息列表,阻止订单创建 |
errorMessage | String | 错误消息概要 |
result | Boolean | 创建结果标识,true表示成功 |
uuid | String | 订单UUID,创建成功后返回,用于后续查询和编辑 |
code | 说明 |
|---|---|
0 | 成功 |
1001 | 参数校验失败 |
1002 | 服务不可用 |
1003 | 国家不支持该服务 |
1004 | 物品信息必填 |
1005 | 发货人邮箱格式错误 |
1006 | 收件人地址信息不完整 |
1007 | 包裹重量必须大于等于0 |
1008 | 发票金额必须大于等于0 |
1009 | 投保信息不完整 |