接口名称

创建订单详情

接口地址

/api/shipper/v1/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


收件人电话

email

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. 服务 → 巴西特定字段显示

// 显示条件: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

11. 报价弹框 → 表单回填

// 触发条件:从报价弹框返回数据(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

错误信息列表

data 字段说明

字段

类型

说明

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

投保信息不完整

业务规则说明

  1. 1. 表单校验规则
  1. 2. 地址对象组装规则
  1. 3. 投保信息校验逻辑
  1. 4. 扩展字段处理规则
  1. 5. 响应处理规则

注意事项

  1. 重量和尺寸单位
  1. 物品信息
  1. 发货人邮箱
  1. 退货选项
  1. 编辑订单
  1. 默认值设置