文档中心 > API类目 > 菜鸟裹裹API

cainiao.pickup.business.platform.preorderview.get (菜鸟商家寄件下单前获取预览信息(代理模式))

该合作企业伙伴（商家）批量操作下单前可以看到的预览信息，通过展示下单时的预览信息及营销内容提升寄件转化率。本接口会展示下单预估价格及各种明细费用，本次预估总价以total_actual_price为准

公共参数

请求地址：

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
target_app_key	String	否	被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
partner_id	String	否	合作伙伴身份标识。
simplify	Boolean	否	是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。

请求参数

名称	类型	是否必须	示例值	更多限制	描述
order_owner_identity_id	String	必须	12345		实际下单人身份ID
order_owner_mobile	String	可选	13355556666		实际下单人手机号
param_list	GuoGuoPackageInfo []	必须		最大列表长度：30	包裹信息，最多传30个
└ item_id String 可选 3000000083 服务id(无特殊情况就填默认值3000000083) └ item_title String 可选测试寄件寄件品名称 └ package_id String 可选 taobao_order_123 用于区分列表中的包裹，一个列表中每个包裹唯一 receiver BusinessCustomer 必须收件人信息 └ area_id String 必须 330100 收件人地址编码，可不填 └ full_address_detail String 必须浙江省杭州市西湖区文一西路西溪首座小邮局收件人详细地址 └ name String 可选张三收件人名字（非必填，不影响预览） └ mobile String 可选 13377778888 收件人联系电话（非必填，不影响预览） sender BusinessCustomer 必须寄件人信息 └ area_id String 必须 330100 寄件人地址编码，可不填 └ full_address_detail String 必须浙江省杭州市西湖区文一西路西溪首座小邮局寄件人详细地址 └ name String 可选张三寄件人名字（非必填，不影响预览） └ mobile String 可选 13377778888 寄件人联系电话（非必填，不影响预览） └ weight Number 可选 1000 包裹重量。单位：克

响应参数

名称	类型	示例值	描述
result	TdOpenServiceResult	{}	返回对象
data OrderViewDto {} 返回对象 └ batch_discount_fee Number 100 整个批次折扣的金额，单位：分 └ coupon_discount_type String NONE 优惠折扣类型，是否有优惠信息（NONE 表示"无任何优惠",ONLY_COUPON 表示"仅有优惠券,无单次阶梯折扣",ONLY_TIERED_PRICING 表示"仅单次阶梯折扣，无优惠券",BOTH 表示"优惠券和单次阶梯折扣优惠都有",FIX_PRICE 表示"一口价模式，可使用优惠劵",NEW_TEMPLATE 表示"新展示模版方式，有后端控制展现什么内容"） └ coupon_price Number 1000 批量下单能够优惠的总金额，单位：分 └ estimation_weight_desc String 描述信息预估价时，采用的预估重量描述 order_ads_desc HrefLabel {} 订单广告信息 └ display_info String 本订单优惠100元显示内容 └ high_lights String [] 优惠100元高亮内容 └ href_desc String 点击查看XXX 链接描述 └ link_url String http://xxx 链接 └ select_type String Default 勾选类型：AutoSelected（无需选择器，自动包含），Default（有选择器，由客户决定是否勾选） order_benefit_desc_list OrderBenefitItem [] [] 订单权益描述 └ key String CompensationForLate 权益Key └ name String 晚揽必赔权益Name └ desc String 千元内免保价权益介绍 └ ori_price String 10元/票原价（一般是价格，如果显示“无价格”表示这个本来不收费，建议就不要展示价格信息） └ current_price String 1元/票、赠送现价（可能是价格，也可能是优惠描述） └ show_condition String AlwaysShow 展示条件：AlwaysShow（始终展示），AlwaysHidden（始终隐藏） └ use_condition String NoCondition 使用条件：NoCondition（无使用条件） └ select_type String Default 勾选类型：AutoSelected（无需选择器，自动包含），Default（有选择器，由客户决定是否勾选） └ tooltip String 提示提示信息 order_preview_desc HrefLabel {} 订单预览信息 └ display_info String 本订单优惠100元显示内容 └ high_lights String [] 优惠100元高亮内容 └ href_desc String 点击查看XXX 链接描述 └ link_url String http://xxx 链接 pre_order_info_list GuoGuoPreOrderInfo [] {} 单个包裹的预估信息 └ can_service Boolean false 订单能否提供服务 └ coupon_price Number 200 优惠价格，单位：分 └ estimate_actual_price Number 1000 实际价格，单位：分 estimate_delivery_info PackageGotInfo {} 预估揽收信息 courier_info CourierInfo {} 小件员信息 └ courier_type String GUOGUO 小件员类型（GUOGUO：全职，PARTTIME：兼职） └ cp_code String cainiaoguoguo 小件员所在cpCode └ cp_name String 菜鸟裹裹小件员所在cp名称 └ name String 张三小件员名称 └ phone_number String 13388889999 小件员电话 └ cp_code String shunfeng 公司code └ cp_name String 顺丰公司名称 └ estimate_got_end_time Date 2020-04-30 12:00:00 预估揽收起始时间 └ estimate_got_start_time Date 2020-04-30 12:00:00 预估揽收结束时间 └ got_time Date 2020-04-30 12:00:00 实际揽收时间 └ estimate_origin_price Number 1200 原始价格，单位：分 └ item_id String 3000000083 服务商品id └ item_title String 测试寄件寄件品名称 └ no_service_reason String 当前区域无服务无法提供服务的原因 └ package_id String 67893874673892 传入的包裹运单号 package_info PackageInfo {} 返回对象 └ amount Number 1000 包裹金额,单位:分 └ goods_name String 大衣货物名称 └ goods_type String 衣服货物类型，DAILY("日用品"),FOOD("食品"),FILE("文件"),CLOTHES("衣物"),DIGITAL("数码产品"),OTHER("其他"); └ package_id String 123 包裹ID └ package_weight Number 100 包裹重量，单位克 └ remark String 备注备注 receiver BusinessCustomer {} 收件人 └ area_id String 330100 收件人地址编码 └ city_id String 21 收件人城市编码 └ district_id String 12 收件人区域编码 └ full_address_detail String 浙江省杭州市西湖区文一西路西溪首座小邮局收件人详细地址 └ name String 张三收件人名字 sender BusinessCustomer {} 寄件人 └ area_id String 330100 寄件人地址编码 └ city_id String 21 寄件人城市编码 └ district_id String 12 寄件人区域编码 └ full_address_detail String 浙江省杭州市西湖区文一西路西溪首座小邮局寄件人详细地址 └ name String 李四寄件人名字 └ weight Number 1000 重量，单位；克 promotion_infos Promotioninfos [] [] 整批下单的促销信息列表 └ promotion_copy String 下单立减优惠文案 └ promotion_price String 350 优惠价格，单位：分 └ promotion_type Number 0 优惠类型，用于区分优惠类别 └ sender_address_desc String 浙江省杭州市西湖区文一西路西溪首座小邮局寄件人地址描述 └ total_actual_price Number 2000 批量下单优惠后预估价格，也是本次预估的最终价格 └ total_origin_price Number 3000 批量下单原始预估价格 external_order_fees ExternalOrderFee [] [] 本次订单额外需要支付的各个费用的明细（已经计入到总价里了，这里只是展示告知客户） └ fee_desc String 一单加价费用名称 └ fee_price Number 100 费用价格，单位：分 └ fee_status String Removed 当前费用收取状态，Used（已计入总价中），Removed（已免除，免收） └ fee_status_reason String VIP专享：免收权益当前费用收取状态原因描述，例如常见的免收原因：VIP专享：免收权益 suggest_display_info HrefLabel {} 该费用的展示的建议方式(PC端) └ tooltip String 提示提示信息 └ link_type String 资源地址的类型 LINK("LINK"，"页面地址，当前页面打开")，NEW_LINK("NEW_LINK"，"页面地址，新页面打开")，IMG("IMG","图片地址")，如果没有传递，则默认代表LINK └ link_url String http://xxx 展现的资源地址 └ href_desc String 点击查看xxx 链接描述 └ high_lights String [] 优惠100元高亮内容 └ display_info String 本订单优惠100元显示内容 suggest_display_info_for_mobile HrefLabel {} 该费用的展示的建议方式(移动端) └ display_info String 本订单优惠100元显示内容 └ high_lights String [] 优惠100元高亮内容 └ href_desc String 点击查看xxx 链接描述 └ link_url String http://xxx 链接描述 └ link_type String 资源地址的类型 LINK("LINK"，"页面地址，当前页面打开")，NEW_LINK("NEW_LINK"，"页面地址，新页面打开")，IMG("IMG","图片地址")，如果没有传递，则默认代表LINK └ tooltip String 提示提示信息 └ benefit_name String 次卡优惠名称 └ benefit_desc String 您有1张寄件卡，剩余12次，寄件揽收后符合条件可使用！优惠展示文案 └ price_tag String 裹裹价价格模版名称 └ retry Boolean false 是否需要重试 └ status_code String SYS_ERROIR 错误码 └ status_message String 系统错误错误描述，如果不能使用服务，会在这里提示错误信息 └ success Boolean true 是否操作成功

请求示例

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
CainiaoPickupBusinessPlatformPreorderviewGetRequest req = new CainiaoPickupBusinessPlatformPreorderviewGetRequest();
req.setOrderOwnerIdentityId("12345");
req.setOrderOwnerMobile("13355556666");
List<CainiaoPickupBusinessPlatformPreorderviewGetRequest.GuoGuoPackageInfo> list2 = new ArrayList<CainiaoPickupBusinessPlatformPreorderviewGetRequest.GuoGuoPackageInfo>();
CainiaoPickupBusinessPlatformPreorderviewGetRequest.GuoGuoPackageInfo obj3 = new CainiaoPickupBusinessPlatformPreorderviewGetRequest.GuoGuoPackageInfo();
list2.add(obj3);
obj3.setItemId("3000000083");
obj3.setItemTitle("测试寄件");
obj3.setPackageId("taobao_order_123");
CainiaoPickupBusinessPlatformPreorderviewGetRequest.BusinessCustomer obj5 = new CainiaoPickupBusinessPlatformPreorderviewGetRequest.BusinessCustomer();
obj5.setAreaId("330100");
obj5.setFullAddressDetail("浙江省杭州市西湖区文一西路西溪首座小邮局");
obj5.setName("张三");
obj5.setMobile("13377778888");
list4.setReceiver(obj5);
CainiaoPickupBusinessPlatformPreorderviewGetRequest.BusinessCustomer obj7 = new CainiaoPickupBusinessPlatformPreorderviewGetRequest.BusinessCustomer();
obj7.setAreaId("330100");
obj7.setFullAddressDetail("浙江省杭州市西湖区文一西路西溪首座小邮局");
obj7.setName("张三");
obj7.setMobile("13377778888");
list6.setSender(obj7);
obj3.setWeight(1000L);
req.setParamList(list2);
CainiaoPickupBusinessPlatformPreorderviewGetResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

响应示例

XML示例
JSON示例

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

<cainiao_pickup_business_platform_preorderview_get_response>
    <result>
        <data>
            <batch_discount_fee>100</batch_discount_fee>
            <coupon_discount_type>NONE</coupon_discount_type>
            <coupon_price>1000</coupon_price>
            <estimation_weight_desc>描述信息</estimation_weight_desc>
            <order_ads_desc>
                <display_info>本订单优惠100元</display_info>
                <high_lights>
                    <string>优惠100元</string>
                </high_lights>
                <href_desc>点击查看XXX</href_desc>
                <link_url>http://xxx</link_url>
                <select_type>Default</select_type>
            </order_ads_desc>
            <order_benefit_desc_list>
                <order_benefit_item>
                    <key>CompensationForLate</key>
                    <name>晚揽必赔</name>
                    <desc>千元内免保价</desc>
                    <ori_price>10元/票</ori_price>
                    <current_price>1元/票、赠送</current_price>
                    <show_condition>AlwaysShow</show_condition>
                    <use_condition>NoCondition</use_condition>
                    <select_type>Default</select_type>
                    <tooltip>提示</tooltip>
                </order_benefit_item>
            </order_benefit_desc_list>
            <order_preview_desc>
                <display_info>本订单优惠100元</display_info>
                <high_lights>
                    <string>优惠100元</string>
                </high_lights>
                <href_desc>点击查看XXX</href_desc>
                <link_url>http://xxx</link_url>
            </order_preview_desc>
            <pre_order_info_list>
                <guo_guo_pre_order_info>
                    <can_service>false</can_service>
                    <coupon_price>200</coupon_price>
                    <estimate_actual_price>1000</estimate_actual_price>
                    <estimate_delivery_info>
                        <courier_info>
                            <courier_type>GUOGUO</courier_type>
                            <cp_code>cainiaoguoguo</cp_code>
                            <cp_name>菜鸟裹裹</cp_name>
                            <name>张三</name>
                            <phone_number>13388889999</phone_number>
                        </courier_info>
                        <cp_code>shunfeng</cp_code>
                        <cp_name>顺丰</cp_name>
                        <estimate_got_end_time>2020-04-30 12:00:00</estimate_got_end_time>
                        <estimate_got_start_time>2020-04-30 12:00:00</estimate_got_start_time>
                        <got_time>2020-04-30 12:00:00</got_time>
                    </estimate_delivery_info>
                    <estimate_origin_price>1200</estimate_origin_price>
                    <item_id>3000000083</item_id>
                    <item_title>测试寄件</item_title>
                    <no_service_reason>当前区域无服务</no_service_reason>
                    <package_id>67893874673892</package_id>
                    <package_info>
                        <amount>1000</amount>
                        <goods_name>大衣</goods_name>
                        <goods_type>衣服</goods_type>
                        <package_id>123</package_id>
                        <package_weight>100</package_weight>
                        <remark>备注</remark>
                    </package_info>
                    <receiver>
                        <area_id>330100</area_id>
                        <city_id>21</city_id>
                        <district_id>12</district_id>
                        <full_address_detail>浙江省杭州市西湖区文一西路西溪首座小邮局</full_address_detail>
                        <name>张三</name>
                    </receiver>
                    <sender>
                        <area_id>330100</area_id>
                        <city_id>21</city_id>
                        <district_id>12</district_id>
                        <full_address_detail>浙江省杭州市西湖区文一西路西溪首座小邮局</full_address_detail>
                        <name>李四</name>
                    </sender>
                    <weight>1000</weight>
                </guo_guo_pre_order_info>
            </pre_order_info_list>
            <promotion_infos>
                <promotioninfos>
                    <promotion_copy>下单立减</promotion_copy>
                    <promotion_price>350</promotion_price>
                    <promotion_type>0</promotion_type>
                </promotioninfos>
            </promotion_infos>
            <sender_address_desc>浙江省杭州市西湖区文一西路西溪首座小邮局</sender_address_desc>
            <total_actual_price>2000</total_actual_price>
            <total_origin_price>3000</total_origin_price>
            <external_order_fees>
                <external_order_fee>
                    <fee_desc>一单加价</fee_desc>
                    <fee_price>100</fee_price>
                    <fee_status>Removed</fee_status>
                    <fee_status_reason>VIP专享：免收权益</fee_status_reason>
                    <suggest_display_info>
                        <tooltip>提示</tooltip>
                        <link_type>资源地址的类型</link_type>
                        <link_url>http://xxx</link_url>
                        <href_desc>点击查看xxx</href_desc>
                        <high_lights>
                            <string>优惠100元</string>
                        </high_lights>
                        <display_info>本订单优惠100元</display_info>
                    </suggest_display_info>
                    <suggest_display_info_for_mobile>
                        <display_info>本订单优惠100元</display_info>
                        <high_lights>
                            <string>优惠100元</string>
                        </high_lights>
                        <href_desc>点击查看xxx</href_desc>
                        <link_url>http://xxx</link_url>
                        <link_type>资源地址的类型</link_type>
                        <tooltip>提示</tooltip>
                    </suggest_display_info_for_mobile>
                </external_order_fee>
            </external_order_fees>
            <benefit_name>次卡</benefit_name>
            <benefit_desc>您有1张寄件卡，剩余12次，寄件揽收后符合条件可使用！</benefit_desc>
            <price_tag>裹裹价</price_tag>
        </data>
        <retry>false</retry>
        <status_code>SYS_ERROIR</status_code>
        <status_message>系统错误</status_message>
        <success>true</success>
    </result>
</cainiao_pickup_business_platform_preorderview_get_response>

{
    "cainiao_pickup_business_platform_preorderview_get_response":{
        "result":{
            "data":{
                "batch_discount_fee":100,
                "coupon_discount_type":"NONE",
                "coupon_price":1000,
                "estimation_weight_desc":"描述信息",
                "order_ads_desc":{
                    "display_info":"本订单优惠100元",
                    "high_lights":{
                        "string":[
                            "优惠100元"
                        ]
                    },
                    "href_desc":"点击查看XXX",
                    "link_url":"http:\/\/xxx",
                    "select_type":"Default"
                },
                "order_benefit_desc_list":{
                    "order_benefit_item":[
                        {
                            "key":"CompensationForLate",
                            "name":"晚揽必赔",
                            "desc":"千元内免保价",
                            "ori_price":"10元\/票",
                            "current_price":"1元\/票、赠送",
                            "show_condition":"AlwaysShow",
                            "use_condition":"NoCondition",
                            "select_type":"Default",
                            "tooltip":"提示"
                        }
                    ]
                },
                "order_preview_desc":{
                    "display_info":"本订单优惠100元",
                    "high_lights":{
                        "string":[
                            "优惠100元"
                        ]
                    },
                    "href_desc":"点击查看XXX",
                    "link_url":"http:\/\/xxx"
                },
                "pre_order_info_list":{
                    "guo_guo_pre_order_info":[
                        {
                            "can_service":false,
                            "coupon_price":200,
                            "estimate_actual_price":1000,
                            "estimate_delivery_info":{
                                "courier_info":{
                                    "courier_type":"GUOGUO",
                                    "cp_code":"cainiaoguoguo",
                                    "cp_name":"菜鸟裹裹",
                                    "name":"张三",
                                    "phone_number":"13388889999"
                                },
                                "cp_code":"shunfeng",
                                "cp_name":"顺丰",
                                "estimate_got_end_time":"2020-04-30 12:00:00",
                                "estimate_got_start_time":"2020-04-30 12:00:00",
                                "got_time":"2020-04-30 12:00:00"
                            },
                            "estimate_origin_price":1200,
                            "item_id":"3000000083",
                            "item_title":"测试寄件",
                            "no_service_reason":"当前区域无服务",
                            "package_id":"67893874673892",
                            "package_info":{
                                "amount":1000,
                                "goods_name":"大衣",
                                "goods_type":"衣服",
                                "package_id":"123",
                                "package_weight":100,
                                "remark":"备注"
                            },
                            "receiver":{
                                "area_id":"330100",
                                "city_id":"21",
                                "district_id":"12",
                                "full_address_detail":"浙江省杭州市西湖区文一西路西溪首座小邮局",
                                "name":"张三"
                            },
                            "sender":{
                                "area_id":"330100",
                                "city_id":"21",
                                "district_id":"12",
                                "full_address_detail":"浙江省杭州市西湖区文一西路西溪首座小邮局",
                                "name":"李四"
                            },
                            "weight":1000
                        }
                    ]
                },
                "promotion_infos":{
                    "promotioninfos":[
                        {
                            "promotion_copy":"下单立减",
                            "promotion_price":"350",
                            "promotion_type":0
                        }
                    ]
                },
                "sender_address_desc":"浙江省杭州市西湖区文一西路西溪首座小邮局",
                "total_actual_price":2000,
                "total_origin_price":3000,
                "external_order_fees":{
                    "external_order_fee":[
                        {
                            "fee_desc":"一单加价",
                            "fee_price":100,
                            "fee_status":"Removed",
                            "fee_status_reason":"VIP专享：免收权益",
                            "suggest_display_info":{
                                "tooltip":"提示",
                                "link_type":"资源地址的类型",
                                "link_url":"http:\/\/xxx",
                                "href_desc":"点击查看xxx",
                                "high_lights":{
                                    "string":[
                                        "优惠100元"
                                    ]
                                },
                                "display_info":"本订单优惠100元"
                            },
                            "suggest_display_info_for_mobile":{
                                "display_info":"本订单优惠100元",
                                "high_lights":{
                                    "string":[
                                        "优惠100元"
                                    ]
                                },
                                "href_desc":"点击查看xxx",
                                "link_url":"http:\/\/xxx",
                                "link_type":"资源地址的类型",
                                "tooltip":"提示"
                            }
                        }
                    ]
                },
                "benefit_name":"次卡",
                "benefit_desc":"您有1张寄件卡，剩余12次，寄件揽收后符合条件可使用！",
                "price_tag":"裹裹价"
            },
            "retry":false,
            "status_code":"SYS_ERROIR",
            "status_message":"系统错误",
            "success":true
        }
    }
}

异常示例

XML示例
JSON示例

<error_response>
    <code>50</code>
    <msg>Remote service error</msg>
    <sub_code>isv.invalid-parameter</sub_code>
    <sub_msg>非法参数</sub_msg>
</error_response>

错误码解释

错误码	错误描述	解决方案

API工具

API测试工具错误码查询工具 SDK下载

如何获得此API

FAQ

我要提问

返回
顶部

开放平台

菜鸟裹裹API