接口文档 - 获取订单详情接口

接口名称

获取订单详情 - Get Shipping Order Detail

接口地址

/parcel/order/edit/{uuid}

请求方式

GET

请求头

参数	类型	必填	说明
sessionId	String	是	登录会话ID
language	String	是	语言，zh_CN=中文，en_US=英文
Content-Type	String	是	application/json

语言取值：

值	说明
zh_CN	中文
en_US	英文

路径参数

参数	类型	必填	说明
uuid	String	是	订单UUID，唯一标识订单

响应参数

一、订单基础信息

字段	类型	说明
uuid	String	订单UUID，唯一标识
trackingNo	String	跟踪号
status	Number	订单状态，0=创建，1=已确认，2=已发货等
facility	String	发件人网点代码，"*"表示默认网点
channel	Number	服务渠道ID
channelName	String	服务名称
serviceOption	String	服务选项代码，如STANDARD
billingPartyName	String	付款方名称
platform	String	电子商务平台
lockerService	Boolean	储物柜服务，true=启用，false=禁用
authorityToLeave	Boolean	授权放置（ATL），true=启用，false=禁用
helds	Number	扣留类型，0=正常，1=客户扣货等

二、收件人地址对象 (address)

字段	类型	说明
addressId	String	地址ID
country	String	目的地国家代码，如GB、US
addressLine1	String	地址第一行
addressLine2	String	地址第二行
addressLine3	String	地址第三行
city	String	城市
state	String	省/州
postcode	String	邮编

三、收件人联系信息

字段	类型	说明
recipientName	String	收件人姓名
recipientCompany	String	收件人公司
phone	String	收件人电话
email	String	收件人邮箱

四、包裹基本信息

字段	类型	说明
refNo	String	参考号
refNo1	String	参考号1
dangerousGoods	Boolean	包含其他危险品
incoterm	String	付税方式，DDU=未完税交货，DDP=完税后交货
invoiceCurrency	String	发票币种，如GBP、USD
invoiceValue	Number	发票金额
instruction	String	装运提示
weight	Number	重量
actualWeight	Number	实际重量（服务端称重）
weightUnit	String	重量单位，kg=千克，lb=磅
volume	Number	体积（立方米）
actualVolume	Number	实际体积（服务端测量）
length	Number	长度
actualLength	Number	实际长度（服务端测量）
width	Number	宽度
actualWidth	Number	实际宽度（服务端测量）
height	Number	高度
actualHeight	Number	实际高度（服务端测量）
dimensionUnit	String	体积单位，cm=厘米，in=英寸，m=米
batteryPacking	String	电池包装代码，如NOBATTERY
batteryType	String	电池类型代码，如NOBATTERY
description	String	货物描述（英文）
nativeDescription	String	货物描述（中文）
recipientTaxId	String	收件人税号
girth	Number	周长，-1表示无值
actualGirth	Number	实际周长，-1表示无值

五、航班信息 (lineHaul)

字段	类型	说明
mawb	String	主运单号
flightDate	String	航班日期，格式YYYY-MM-DD
flightNo	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	仓库ID
shipperOrganizationCode	String	发件人企业统一社会信用代码
shipperCompanyName	String	发件人公司名
virtualId	String	虚拟服务ID，存在时表示虚拟服务

七、物品信息 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	出口申报金额
itemExportInvoiceCurrency	String	出口申报币种
pictures	Array	物品图片URL数组，最多5张

八、发货人地址信息 (shipperAddress)

字段	类型	说明
addressId	String	发货人地址ID
country	String	国家代码
addressLine1	String	地址第一行
addressLine2	String	地址第二行
addressLine3	String	地址第三行
city	String	城市
state	String	省/州
postcode	String	邮编

九、发货人联系信息

字段	类型	说明
shipperName	String	发货人姓名
shipperPhone	String	发货人电话
shipperEmail	String	发货人邮箱

十、退货地址信息 (returnAddress)

字段	类型	说明
addressId	String	退货地址ID
addressLine1	String	退货地址第一行
addressLine2	String	退货地址第二行
addressLine3	String	退货地址第三行
city	String	退货城市
state	String	退货省/州
postcode	String	退货邮编
country	String	退货国家

十一、退货信息

字段	类型	说明
returnName	String	退货人姓名
returnPhone	String	退货联系电话
returnOption	String	退货选项，Destroy=销毁，Return=退回，Forward=转寄，Change=地址更改

十二、在线投保信息 (insur)

字段	类型	说明
uuid	String	投保UUID
cancel	Boolean	是否取消投保，true=不投保，false=投保
insureType	String	被保险人类型，02=公司，01=个人
insuredContackName	String	被保人真实姓名
insuredName	String	被投保人联系人姓名
insureAmount	Number	投保额
insureCurrency	String	投保额币种
insureCardNo	String	组织机构代码证或身份证号码
projectNo	String	保单号

完整响应示例

{
  "success": true,
  "code": "0",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "trackingNo": "ET123456789CN",
    "status": 0,
    "facility": "*",
    "channel": 3,
    "channelName": "Standard Service",
    "serviceOption": "STANDARD",
    "billingPartyName": "Test Company",
    "platform": "eBay",
    "lockerService": false,
    "authorityToLeave": true,
    "helds": 0,
    "address": {
      "addressId": "ADDR001",
      "country": "GB",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "addressLine3": "London",
      "city": "London",
      "state": "England",
      "postcode": "SW1A 1AA"
    },
    "recipientName": "John Smith",
    "recipientCompany": "Smith Ltd",
    "phone": "+44 20 1234 5678",
    "email": "john.smith@example.com",
    "refNo": "REF123456",
    "refNo1": "REF789012",
    "dangerousGoods": false,
    "incoterm": "DDU",
    "invoiceCurrency": "GBP",
    "invoiceValue": 25.99,
    "instruction": "Please call before delivery",
    "weight": "1.5",
    "actualWeight": 1.6,
    "weightUnit": "kg",
    "volume": 0.003,
    "actualVolume": 0.0035,
    "length": "30.0",
    "actualLength": 31,
    "width": "20.0",
    "actualWidth": 21,
    "height": "5.0",
    "actualHeight": 5.5,
    "dimensionUnit": "cm",
    "batteryPacking": "NOBATTERY",
    "batteryType": "NOBATTERY",
    "description": "Cotton T-Shirt",
    "nativeDescription": "纯棉T恤",
    "recipientTaxId": "GB123456789",
    "girth": 110,
    "actualGirth": 112,
    "lineHaul": {
      "mawb": "123-45678900",
      "flightDate": "2024-01-15",
      "flightNo": "CA1234"
    },
    "extendData": {
      "vendorid": "VENDOR001",
      "agentID": "AGENT001",
      "sortCode": "SORT001",
      "purpose": "GIFT",
      "material": "COTTON",
      "codAmount": 0,
      "codCurrency": "GBP",
      "receiverKycType": "INDIVIDUAL",
      "receiverKycNo": "KYC123456",
      "injectPort": "LHR",
      "abnnumber": "",
      "gstexemptioncode": "",
      "platformorderno": "EBAY-ORDER-123",
      "coveramount": 100,
      "senderTaxId": "CN123456789",
      "postage": "",
      "icms": "",
      "vat": "GB20",
      "originPort": "CN",
      "osnr": "0",
      "specialHandlingType": "SH05",
      "holdForPickup": "N",
      "residentialSignatureRequired": "N",
      "saturdayDelivery": "N",
      "exportInvoiceValue": 30,
      "exportInvoiceCurrency": "GBP",
      "imei1": "",
      "imei2": "",
      "warehouseID": "WH-SZ-001",
      "shipperOrganizationCode": "91310000MA1X4QC",
      "shipperCompanyName": "Shenzhen Tech Co., Ltd"
    },
    "parcelItems": [
      {
        "uuid": "ITEM001",
        "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": {
      "addressId": "SHIPPER001",
      "country": "CN",
      "addressLine1": "456 Shipping Street, Suite 100",
      "addressLine2": "Futian District",
      "addressLine3": "Shenzhen",
      "city": "Shenzhen",
      "state": "Guangdong",
      "postcode": "518000"
    },
    "shipperName": "Zhang San",
    "shipperPhone": "+86 13900139000",
    "shipperEmail": "zhangsan@example.com",
    "returnAddress": {
      "addressId": "RETURN001",
      "addressLine1": "789 Return Street",
      "addressLine2": "Warehouse B",
      "addressLine3": "Industrial Zone",
      "city": "Shenzhen",
      "state": "Guangdong",
      "postcode": "518001",
      "country": "CN"
    },
    "returnName": "Li Si",
    "returnPhone": "+86 13800138000",
    "returnOption": "Return",
    "insur": {
      "uuid": "INSUR001",
      "cancel": false,
      "insureType": "01",
      "insuredContackName": "Zhang San",
      "insuredName": "Li Si",
      "insureAmount": 100,
      "insureCurrency": "GBP",
      "insureCardNo": "110101199001001234",
      "projectNo": "POLICY123"
    }
  },
  "errors": []
}

响应字段说明

字段	类型	说明
success	Boolean	请求是否成功
code	String	响应状态码，"0"表示成功
data	Object	返回数据对象，包含订单详情
errors	Array	错误信息列表

错误码说明

code	说明
0	成功
1001	参数校验失败
1002	订单不存在
1003	无权限访问该订单
1004	订单UUID格式错误

前端数据处理规则

1. 数据格式转换

// 服务端返回的整数需要转换为浮点数格式显示
// 例如：2 -> "2.0"，1.5 -> "1.5"
handlerIntegerField(data, fractionDigits) {
  return Number.isInteger(data) ? Number(data).toFixed(fractionDigits) : data
}

// 应用于以下字段：
// - actualWeight: 保留3位小数
// - actualWidth, actualLength, actualHeight: 保留1位小数
// - invoiceValue: 保留1位小数
// - weight, length, width, height: 保留1位小数

注意事项

1. UUID格式

订单UUID必须是有效的UUID格式
UUID由32位十六进制数字组成，格式为xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. 权限验证

需要提供有效的sessionId
只能查询属于当前登录发件人的订单

3. 数据完整性

address对象可能为空，需要做容错处理
lineHaul对象可能为空
extendData可能不包含所有字段，未返回的字段需要设置为空字符串
parcelItems可能为空数组

4. 特殊字段处理

lockerService仅在addressCountry='RU'时有意义
authorityToLeave仅在特定服务channel时显示
helds值对应扣留类型，0表示正常

5. 数据使用场景

查询到的数据用于编辑订单页面展示
编辑时需要保留所有实际数据字段（actual开头）
地址ID需要在编辑时提交
物品的UUID在编辑时需要提交