4.createOrder - YCS EXPRESS

服务能力：创建预报包裹
请求地址：host:/createOrder
请求方式：POST

Header 请求参数（用于token校验）:

参数名	示例值
token	4e411a926e7a33ca9d04cd1942ac54a2

Body 请求参数：

参数名	描述	是否必填	数据类型	字段长度
referenceNo	客户自定义单号，唯一	是	String	30
productCode	服务编码取Product Code的值	是	String	10
orderNo	客户订单号	否	String	30
packageType	包裹类型(默认B2C) B2B/B2C	否	String	30
incoterms	贸易条款(DDU、DDP二选一)	否	String	30
reasonForExport	报关用途(UPS渠道必填) 枚举值： SALE:我要銷售這些物品 GIFT:我要送禮物 INTERCOMPANYDATA:我要寄送包含數據的物理設備 SAMPLE：我要寄送產品樣品 REPAIR:我要將這些物品送修 RETURN:我要退回物品	否	String	30
storeId	取件店代码（店铺ID） ---店配模式必填店铺ID从getShopInfo接口中获取	是	String	20
codAmount	包裹COD金额服务编码为： TWYCS-COD，TWFMART-COD TW711-COD时为必填	是	Number	10
remark	包裹派送备注	否	String	100
sender	发件人信息	是	Object
company	发件人公司	否	String	100
contact	发件人	是	String	50
phone	发件人电话	是	String	20
email	email	否	String	50
country	发件人国家	是	String	50
province	发件人省/州	是	String	100
city	发件人城市	是	String	100
address	发件人详细地址	是	String	200
postCode	发件人邮编	是	String	10
vat	发件人税号/ID	否	String	20
receiver	收件人信息	是	Object
company	收件人公司	否	String	100
contact	收件人	是	String	50
phone	收件人电话	是	String	20
email	email	否	String	50
country	收件人国家/区域 ---店配模式非必填	是	String	50
province	收件人省/州	否	String	100
city	收件人市/县 ---店配模式非必填	是	String	100
suburb	收件人行政区	否	String	100
address	收件人详细地址 ---店配模式非必填	是	String	200 UPS渠道：35
address2	收件人详细地址2 ---仅对UPS渠道有效	否	String	35
address3	收件人详细地址3 ---仅对UPS渠道有效	否	String	35
postCode	收件人邮编 ---店配模式非必填	是	String	10
vat	收件人税号/ID	否	String	20
packageList	包裹商品信息	是	Array[PackageList]
packType	包装类型（UPS渠道必填）枚举值 01:UPS Letter 02:自行包装 04:UPS Pak	是	String	2
description	包裹描述 UPS渠道必填	是	Number	5
weight	包裹实际重量，单位：kg 精确到3位小数	是	Number	8
length	包裹长，单位：cm 精确到1位小数	否	Number	5
width	包裹宽，单位：cm 精确到1位小数	否	Number	5
height	包裹高，单位：cm 精确到1位小数	否	Number	5
packageItemList	包裹物品明细	是	array[PackageItemList]
sku	SKU编码	是	String	30
goodsNameEn	英文品名/当地品名	是	String	100
goodsNameCn	中文品名	是	String	100
countryOfOrigin	原产地(UPS渠道必填) 国家/地区两位代码如：TW、CN	是	String	100
fullDescEn	销售描述	是	String	1000
hsCode	HS CODE	否	String	10
quantity	数量	是	Number	10
unitType	单元类型(UPS渠道必填) 枚举值：详情见附录appendix	是	Number	10
itemWeight	重量，单位：kg 精确到3位小数	是	Number	7
itemValue	商品价值	是	String	10
currency	货币单位（比如：TWD、USD）	是	String	5
itemSellingUrl	商品销售链接	否	String	1000
imageUrl	商品图片链接	否	String	500

“宅配模式”请求示例：

{
    "referenceNo": "TEST190107003",
    "productCode": "TWYCS-COD",
    "orderNo": "OD190107003",
    "incoterms": "DDU",
    "remark": "备注",
    "sender": {
        "company": "TEST",
        "contact": "测试",
        "phone": "0977777777",
        "email": "test@test.com",
        "country": "",
        "province": "台北市",
        "city": "北投區",
        "address": "中央南路3段16號3樓501",
        "postCode": "112"
    },
    "receiver": {
        "company": "",
        "contact": "林青霞",
        "phone": "0977560001",
        "email": "test@test.com",
        "country": "",
        "province": "台灣",
        "city": "台南市",
        "suburb": "中西區",
        "address": "武聖路１５３號１樓",
        "postCode": "700",
        "vat": "A123456789"
    },
    "packageList": [
        {
            "weight": "13.109",
            "length": "50",
            "width": "80",
            "height": "45",
            "codAmount": 3980,
            "packageItemList": [
                {
                    "sku": "td2902sx880",
                    "goodsNameEn": "洗地機",
                    "goodsNameCn": "洗地机",
                    "fullDescEn": "【TiDdi】乾濕兩用仿生洗地機(SX880)",
                    "hsCode": "36890233",
                    "quantity": "1",
                    "itemWeight": "5.102",
                    "itemValue": "3390",
                    "currency": "TWD",
                    "itemSellingUrl": "https://24h.pchome.com.tw/prod/DMAX5B-A900H2OI7",
                    "imageUrl": "https://cs-a.ecimg.tw/items/DMAX5BA900H2OI7/000001_1706836797.jpg"
                },
                {
                    "sku": "dy102348",
                    "goodsNameEn": "吸塵器",
                    "goodsNameCn": "吸尘器",
                    "fullDescEn": "Dyson V12 Origin SV44 輕量智能吸塵器 銀灰",
                    "hsCode": "36890235",
                    "quantity": "1",
                    "itemWeight": "7.88",
                    "itemValue": "15900",
                    "currency": "TWD",
                    "itemSellingUrl": "https://24h.pchome.com.tw/prod/DMBF05-1900GQDCH?fq=/S/DMAX00",
                    "imageUrl": "https://cs-a.ecimg.tw/items/DMBF051900GQDCH/l000001_1706866075.jpg"
                }
            ]
        }
    ]
}

“店配模式”请求示例：

{
    "referenceNo": "TEST190107005",
    "productCode": "TWFMART-COD",
    "orderNo": "OD190107005",
    "incoterms": "DDU",
    "storeId": "022172",
    "codAmount": "5960",
    "remark": "备注",
    "sender": {
        "company": "TEST",
        "contact": "测试",
        "phone": "0977777777",
        "email": "test@test.com",
        "country": "",
        "province": "台北市",
        "city": "北投區",
        "address": "中央南路3段16號3樓501",
        "postCode": "112"
    },
    "receiver": {
        "contact": "林青霞",
        "phone": "0977560001"
    },
    "packageList": [
        {
            "weight": "13.109",
            "length": "50",
            "width": "80",
            "height": "45",
            "packageItemList": [
                {
                    "sku": "td2902sx880",
                    "goodsNameEn": "洗地機",
                    "goodsNameCn": "洗地机",
                    "fullDescEn": "【TiDdi】乾濕兩用仿生洗地機(SX880)",
                    "hsCode": "36890233",
                    "quantity": "1",
                    "itemWeight": "5.102",
                    "itemValue": "3390",
                    "currency": "TWD",
                    "itemSellingUrl": "https://24h.pchome.com.tw/prod/DMAX5B-A900H2OI7",
                    "imageUrl": "https://cs-a.ecimg.tw/items/DMAX5BA900H2OI7/000001_1706836797.jpg"
                },
                {
                    "sku": "dy102348",
                    "goodsNameEn": "吸塵器",
                    "goodsNameCn": "吸尘器",
                    "fullDescEn": "Dyson V12 Origin SV44 輕量智能吸塵器 銀灰",
                    "hsCode": "36890235",
                    "quantity": "1",
                    "itemWeight": "7.88",
                    "itemValue": "15900",
                    "currency": "TWD",
                    "itemSellingUrl": "https://24h.pchome.com.tw/prod/DMBF05-1900GQDCH?fq=/S/DMAX00",
                    "imageUrl": "https://cs-a.ecimg.tw/items/DMBF051900GQDCH/l000001_1706866075.jpg"
                }
            ]
        }
    ]
}

UPS渠道请求示例

{
    "referenceNo": "TEST20020726018",
    "productCode": "TWUPS-WES",
    "incoterms": "DDP",
    "reasonForExport": "GIFT",
    "sender": {
        "company": "Company",
        "contact": "Test",
        "phone": "091234124",
        "country": "TW",
        "province": "TP",
        "city": "Taibei",
        "address": "Industrial Park",
        "postCode": "100",
        "vat": "00000000"
    },
    "receiver": {
        "contact": "Jenna",
        "phone": "0985532043",
        "country": "KR",
        "province": "Seoul",
        "city": "Gangnam-gu",
        "suburb": "Yeoksam-dong",
        "address": "123 Teheran-ro, Gangnam-gu",
        "postCode": "06123",
        "vat": "0000000"
    },
    "packageList": [
        {
            "packType": "02",
            "description": "TEST GOODS",
            "weight": "0.177",
            "length": 37,
            "width": 28,
            "height": 0,
            "packageItemList": [
                {
                    "sku": "sku001",
                    "goodsNameEn": "One-piece underwear",
                    "goodsNameCn": "连体内衣",
                    "countryOfOrigin": "TW",
                    "fullDescEn": "Topless Crotchless Jumpsuit",
                    "hsCode": "6108920010",
                    "quantity": 1,
                    "unitType": "BOX",
                    "itemWeight": 0.1,
                    "itemValue": "64.56",
                    "currency": "TWD"
                },
                {
                    "sku": "sku002",
                    "goodsNameEn": "Lingerie set",
                    "goodsNameCn": "女式内衣套装",
                    "countryOfOrigin": "TW",
                    "fullDescEn": "Lingerie",
                    "hsCode": "6212101000",
                    "quantity": 1,
                    "unitType": "BG",
                    "itemWeight": 0.1,
                    "itemValue": "139.87",
                    "currency": "TWD"
                }
            ]
        }
    ]
}

响应字段说明：

字段名	描述	数据类型
success	true 或者 false	Boolean
code	200：成功其他：失败	Integer
message	请求返回信息	String
requestId	请求ID	String
data		Object
waybill	运单号	String
referenceNo	客户自定义单号，唯一	String
productCode	服务编码	String
labelUrl	面单url地址，pdf格式	String

成功示例返回：

{
    "success": true,
    "code": 200,
    "message": "success",
    "requestId": "65bcecc674687425",
    "data": [
        {
            "waybill": "T80000045",
            "referenceNo": "TEST240202005",
            "productCode": "TEST",
            "labelUrl": "https://openapitest.ycs.express/pdf-file/T80000045/3a8df10c-c1ce-11ee-8445-00163e0cad28.pdf"
        }
    ]
}

错误代码说明：

错误代码	错误描述
1001	Token验证错误，请检查传入的Token是否正确
1002	请求参数数据结构错误，请检测后重新传入
1003	传入参数长度不符合要求
1004	接口异常
1005	客户自定义单号重复
1006	包裹重量超过限制
1007	申报金额超过限制
1008	地址问题
1009	实名认证失败，请转其他渠道

错误示例返回：

{
    "success":false,
    "code":1001,
    "message":"Token验证错误，请检查传入的Token是否正确",
    "requestId":"655c00af45b3a785"
}