注意：以下文档只适用于TOP接口，请谨慎使用！
注意：以下文档只适用于TOP接口，请谨慎使用！
第一章 PC端API
1.QN.top.invoke top服务
1.1 top接口字符串
1.2 tql
2.预定义的事件
2.1 wangwang.active_contact_changed
2.2 wangwang.trade_focus交易焦点
2.3 wangwang.contact_closed正在联系人列表中关闭该联系人
2.4 wangwang.contact_joined联系人列表中加入新的接入人
2.5 wangwang.chatdlg_open旺旺聊天窗口打开
2.6 wangwang.chatdlg_closed旺旺聊天窗口关闭
2.7 bench.attach_wnd.close插件附属窗口的关闭通知
2.8 bench.trade_info交易通知
2.9 bench.refund_info退款通知
2.10 bench.item_info宝贝通知
2.11 bench.colorize换肤主题色通知
2.12 wangwang.recvmsgurl.itemid对方发送了宝贝链接的通知
3. 常见错误码
第二章 移动端API
1. System对象
1.1 pasteboard获取系统剪切板里的信息
1.2. pasteboard复制信息到剪切板
1.3 information
1.4 API调用top api
2. Contacts对象
2.1 list获取联系人列表
2.2 myPhoneNum获取当前手机号
3. Camera对象
3.1 getPicture获取照片
3.2 resize按指定大小压缩图片
3.3 scan利用摄像头对二维码条形码进行扫描
4 notification对象
4.1 vibrate手机震动
4.2 lockscreen控制锁屏
5. ww对象
5.1chat呼出和某个聊天的聊天对话框
6. fm对象
6.1 info查询和当前应用绑定的电台的订阅信息
6.2 spread手机震动
6.3 openSetting打开任意电台的消息订阅页面
6.4 getIconBadgeNumber获取任意电台的未读消息数
7. Widget对象
7.1 changePrice获得改价组件呼出句柄
7.2 refund获得退款组件呼出句柄
7.3 pay支付组件
7.4 payBySimpleSDK
参数名 |
值/返回值 |
备注 |
cmd |
top接口字符串 |
如： taobao.user.seller.get |
param |
{ fields:'nick,sex,seller_credit,type, alipay_bind,consumer_protection, avatar,online_gaming', format : 'xml', qianniu_https : true //... } |
可以指定返回格式为xml，这时返回结果为： { xml_result : 'xml string format response of api' }
https的调用方式支持， param中新增参数qianniu_https |
method |
get/post |
|
rsp |
|
|
msg |
|
|
参数名 |
值/返回值 |
备注 |
cmd |
top接口字符串 |
针对并发请求TQL的支持，参考： //open.taobao.com/doc/detail.htm?id=806 |
param |
{ ql: '{select nick,sex,vip_info, created,last_visit, location,buyer_credit, promoted_type, consumer_protection from taobao.user.get where nick="测试账号"}{select nick,sex from taobao.user.seller.get}' } |
可以指定返回格式为xml，这时返回结果为： { xml_result : 'xml string format response of api' }
https的调用方式支持， param中新增参数qianniu_https |
method |
get/post |
|
rsp |
[ {}, {} //... ] 多个对象的数组 |
|
msg |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.active_contact_changed |
旺旺聊天焦点用户切换 对于旺旺插件，如果不监听，每次切换旺旺联系人将刷新callback_url，用户感受延迟体验不好，并造成ISV后台压力。 强烈建议使用监听该事件的方式来做，但需要保证内存不泄漏。 |
data |
{ 'old_contact':xxx, 'new_contact':xxx } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.trade_focus |
交易焦点 |
data |
{ 'type':gid的类型, 'gids':xxx, 'user':焦点信息对应的用户 } |
type:0交易；1商品 gids：是该交易焦点中包含的所有ID（宝贝ID可能有多个，订单ID只有一个） |
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.contact_closed |
正在联系人列表中关闭该联系人 |
data |
{ 'contact':"关闭的联系人" } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.contact_joined |
联系人列表中加入新的接入人 |
data |
{ 'contact':"新接入的联系人" } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.chatdlg_open |
旺旺聊天窗口打开 |
data |
|
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.chatdlg_close |
旺旺聊天窗口关闭 |
data |
|
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
bench.attach_wnd.close |
插件附属窗口的关闭通知 |
data |
{ event:'xxx' } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
bench.trade_info |
|
data |
{ "subTopic":"TradeCreate", "title":"test", "buy_nick":"buywebx_buyer8", "time":1379901173, "id":192262821019180 } |
subTopic是交易通知的子类别，详见后面的注意 |
msg(reg) |
|
|
msg(unreg) |
|
|
注意：
关于bench.trade_info的回参subTopic的说明：
TradeCreate |
新订单 |
TradeModifyFee |
订单价格已修改 |
TradeCloseAndModifyDetailOrder |
子订单已关闭或修改 |
TradeClose |
订单关闭 |
TradeBuyerPay |
买家已付款 |
TradeSellerShip |
卖家已发货 |
TradeDelayConfirmPay |
已延长收货时间 |
TradePartlyRefund |
子订单退款成功 |
TradePartlyConfirmPay |
子订单打款成功 |
TradeSuccess |
交易成功 |
TradeTimeoutRemind |
订单已超时 |
TradeRated |
买家已评价 |
TradeMemoModified |
交易备注已修改 |
TradeLogisticsAddressChanged |
修改交易收货地址 |
TradeChanged |
订单信息已修改 |
参数名 |
值/返回值 |
备注 |
eventId |
bench.refund_info |
退款通知 |
data |
{ "subTopic":"TradeCreate", "title":"xizi-8.16-15.47", "buy_nick":"buywebx_buyer8", "time":1379901173, "id":192262821019180 } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
关于bench.refund_info的回参subTopic的说明：
RefundSuccess |
退款已完成 |
RefundClosed |
退款已关闭 |
RefundCreated |
新退款申请 |
RefundSellerAgreeAgreement |
卖家已同意退款协议 |
RefundSellerRefuseAgreement |
卖家已拒绝退款协议 |
RefundBuyerModifyAgreement |
买家修改退款协议 |
RefundBuyerReturnGoods |
买家退货给卖家 |
RefundTimeoutRemind |
退款已超时 |
参数名 |
值/返回值 |
备注 |
eventId |
bench.item_info |
宝贝通知 |
data |
{ "subTopic":"TradeCreate", "title":"商品1", "time":1379901173, "id":192262821019180 } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
关于bench.item_info的回参subTopic的说明：
ItemAdd |
新商品 |
ItemUpshelf |
商品已上架 |
ItemDownshelf |
商品被下架 |
ItemDelete |
商品被删除 |
ItemUpdate |
商品已更新 |
ItemZeroStock |
商品已卖空 |
ItemStockChanged |
商品库存变动 |
ItemSkuZeroStock |
商品卖空（SKU） |
ItemRecommendDelete |
商品取消橱窗推荐 |
ItemRecommendAdd |
商品被橱窗推荐 |
ItemWillBePunished |
商品即将被处罚 |
ItemAuditFailed |
商品审核失败 |
ItemAuditSuccess |
商品审核成功 |
ItemHealthDailyReport |
商品体检日报 |
参数名 |
值/返回值 |
备注 |
eventId |
bench.colorize |
换肤主题色通知 |
data |
{ "rgb" : 'ffffff', "textColor": 'ffffff', "backgroundImageUrl": 'http://.',//cdn上图片地址 "backgroundPositionX":"left",//right左对齐或右对齐 } |
|
msg(reg) |
|
|
msg(unreg) |
|
|
参数名 |
值/返回值 |
备注 |
eventId |
wangwang.recvmsgurl.itemid |
对方发送了宝贝链接的通知 |
data |
{
"fromuid":"顾客的nick",
"itemid":"192262821019180"
} |
|
msg(reg) |
|
|
msg(unreg) |
|
|
code:-501088242， msg:top net error |
TOP请求网络层失败，具体信息可以参考sub_code,sub_msg |
code:-501088255，msg:plugin in calling, wait |
上一次对插件的调用还未结束。通常原因是插件页面加载后未设置回包，如何设置回包，参考开发文档 设置回包 章节 |
system 对象提供用户对剪切板的操作。
var system = TOP.mobile.sys;
|
值/返回值 |
备注 |
方法名 |
pasteboard |
获取系统剪切板里的信息 |
Parameters |
callback {function} |
接收系统剪切板信息的回调 |
Returns |
{ type:'text', content:info } |
|
Example |
system.pasteboard(function(info){ alert(info); }); |
|
|
值/返回值 |
备注 |
方法名 |
pasteboard |
复制信息到剪切板 |
Parameters |
info {string} 需要往剪切板设置的信息 |
|
Returns |
{ type:'text', content:info } |
|
Example |
system.pasteboard('你好，我是测试。测试URL：http://taobao.com。测试引号：\' ,",\'');}); |
|
|
值/返回值 |
备注 |
方法名 |
information |
查询网络，版本和千牛应用的版本等 |
Parameters |
infoList {enum array} 枚举数组，列出需要查询的可选项， 目前公开的可选值有： system.InformationOption.NETWORK:网络情况 system.InformationOption.SYS_VERSION:系统版本 system.InformationOption.SYS_NAME:系统名称 system.InformationOption.QN_VERSION:千牛版本 callback {function} 接收查询到的信息回调 |
|
Returns |
{ "network":"WIFI" }
|
返回结果按请求的infoList项返回 |
Example |
var InformationOption = system.InformationOption; //获取系统信息 system.information([InformationOption.NETWORK, InformationOption.QN_VERSION],function(info){ alert(info); } |
|
|
值/返回值 |
备注 |
方法名 |
api |
调用top api |
Parameters |
apiRequest {object} |
根据开放平台的文档传给开放平台的调用信息 |
Returns |
请查看调用的API的API文档 |
|
Example |
调用 taobao.user.seller.get var topUserRequest = system.api({ method:'taobao.user.seller.get', fields:'nick,sex,avatar,online_gaming' }); //发出请求，获取结果，可重复使用 topUserRequest(function(result){ alert(JSON.stringify(result)); });
调用 taobao.item.get var topItemRequest = system.api({ method:'taobao.item.get', fields:' num_iid,title,price,desc_modules', num_iid:'432432423423423234' }); //发出请求，获取结果，可重复使用 topItemRequest(function(result){ alert(JSON.stringify(result)); });
调用 taobao.picture.upload图片上传 图片上传类接口请参考以下example var topUploadRequest = system.api({ method:'taobao.picture.upload', picture_category_id:3, img:{ name:"Bule.jpg", data:base64String }, image_input_title:"Bule.jpg", title:"zhudi test" }); topUploadRequest(function(result){ alert(JSON.stringify(result)); }); |
|
contacts 对象提供对用户联系人的操作权限。
var contacts = TOP.mobile.contacts;
|
值/返回值 |
备注 |
方法名 |
list |
获取联系人列表 |
Parameters |
callback {function} |
接收联系人列表 |
Returns |
{code:10006}
|
或者列表为空 表示用户拒绝 正常情况待补充 |
Example |
contacts.list(function(info){ alert(info); }); |
|
|
值/返回值 |
备注 |
方法名 |
myPhoneNum |
获取当前手机号，目前只支持android手机 |
Parameters |
callback {function} |
接收当前手机号 |
Returns |
{ name:'mySelf' phone:'13811111111' } |
|
Example |
contacts.myPhoneNum(function(info){ alert(info); }); |
|
camera 对象提供用户对摄像头的操作，可以进行拍照，扫描，和图片获取。
var camera = TOP.mobile.device.camera;
|
值/返回值 |
备注 |
方法名 |
getPicture |
获取照片,返回用户选择或者拍摄的照片 |
Parameters |
Parameters callback {function} 接收图片信息的回调 [sourceType]{enum} 可选参数,枚举类型,可选值有： camera.PictureSourceType.PHOTO_ALBUM 相册取 camera.PictureSourceType.CAMERA 摄像头拍照 默认是PHOTO_ALBUM [mimeType]{enum} 可选参数,标志返回图片类型,可选值有 camera.PictureMIMEType.PNG PNG格式 camera.PictureMIMEType.JPEG JPEG格式 默认值为JPEG [quality]{int} 可选参数,为0-100之间的数值，表示JPEG类型图片的压缩比，默认为100 [size]{string} 可选参数,其格式为width_height格式，表示图片的大小。如100_* 200_100 200_ |
接收当前手机号 |
Returns |
Returns { MIME:MIME, data:base64String, size:'100_300', code:[0|-1|-2] } |
code为0成功，code为-1用户取消，code为-2请求重复提交 图片数据作为base64 string返回回来，可以通过DATA URI直接显示在页面 |
Example |
contacts.myPhoneNum(function(info){ alert(info); }); |
|
|
值/返回值 |
备注 |
方法名 |
myPhoneNum |
按指定大小压缩图片，保持图片高宽比 |
Parameters |
callback {function} 接收图片信息的回调 base64String{string} 需要压缩的图片数据 [mimeType]{enum} 可选参数,标志返回图片类型,可选值有: camera.PictureMIMEType.PNG PNG格式 camera.PictureMIMEType.JPEG JPEG格式 默认值为JPEG [size]{string} 可选参数,其格式为width_height格式，表示图片的大小。如100_* 200_100 200_* 默认值为100_100 |
|
Returns |
{ MIME:MIME, data:base64String, size:'100_300', code:[0|-1|-2] } |
code为0成功，code为-1用户取消，code为-2请求重复提交 图片数据作为base64 string返回回来，可以通过DATA URI直接显示在页面 |
Example |
camera.resize(function(result){ setPic(result); },imgBase64String,null,'100_300'); |
|
|
值/返回值 |
备注 |
方法名 |
scan |
利用摄像头对二维码条形码进行扫描 |
Parameters |
callback {function} |
接收扫描结果 |
Returns |
{string} |
|
Example |
camera.scan(function(result){ alert(result); }); |
|
notification模块负责完成通知用户感官的一些操作，如震动，锁屏等。
var notification = TOP.mobile.notification;
|
值/返回值 |
备注 |
方法名 |
vibrate |
手机震动 |
Parameters |
no paramter |
|
Returns |
no return |
|
Example |
notification.vibrate(); |
|
|
值/返回值 |
备注 |
方法名 |
lockscreen |
控制锁屏 |
Parameters |
lockorNot{boolean} |
true表示长时间未操作自动锁屏，false表示关闭锁屏功能，长时间未使用也不锁屏 |
Returns |
no return |
|
Example |
notification.lockscreen(true); |
|
ww对象负责和千牛的旺旺模块交互。
var ww = TOP.mobile.ww;
|
值/返回值 |
备注 |
方法名 |
chat |
呼出和某个聊天的聊天对话框 |
Parameters |
chatInfo {object} 聊天启动信息。详细说明如下： { chatNick:聊天对象的nick, text:'你好,欢迎', [domain_code]:可选参数， 所属域：taobao|alichn|aliint [ iid]: 可选参数，焦点商品, [tid]: 可选参数，焦点订单 }} |
|
Returns |
no return |
|
Example |
ww.chat({ chatNick:'朱棣', text:'你好,欢迎', domain_code:'alichn' iid:'124234234234', }); |
|
fm提供操作用户电台订阅数据的接口。
var fm = TOP.mobile.fm;
注意，fm提供的方法根据安全等级不一样，有的只能操作自己插件对应的电台的数据，有的可以操作所有电台的数据。具体请看方法详情。
一个应用只能绑定一个电台，形成一一对应的关系
|
值/返回值 |
备注 |
方法名 |
infor |
手机震动 |
Parameters |
callback {function} |
接收当前用户与插件绑定电台的订阅状况 |
Returns |
{ code:0, result:{ "topic":self.topic, "subscribed":['fm_s_4'], "unsubscribed":[], "refused":[], "chineseNameMapping":{ fm_s_4:'千牛课堂' } } } |
code 定义如下： *0 成功 *10001 系统异常，可重试 *10002 无未绑定FM *10008 FM在后台找不到 |
Example |
fm.info(function(result){
}); |
|
|
值/返回值 |
备注 |
方法名 |
spread |
提示用户订阅应用绑定的电台 |
Parameters |
subTopicArray{array} 需要用户订阅的二级类目数组。 callback {function} 接收操作结果。 |
|
Returns |
{ code:0, result:{ "topic":self.topic, "subscribed":['fm_s_4'], "unsubscribed":[], "refused":[], "chineseNameMapping":{ fm_s_4:'千牛课堂' } } } |
code 定义如下： *0 成功 *10001 系统异常，可重试 *10002 无未绑定FM *10003 请求参数不合法 *10004 用户拒绝 *10005 上次的流程还没结束，不能重复发起 *10006 用户拒绝（对，你没看错，和10004一样，一次是系统自动，一个是用户点击） *10007 请求参数里含有不合法的二级类目 *10008 FM在后台找不到 |
Example |
fm.spread(['sub_topic1','sub_topic2'], function(result){
}); |
|
|
值/返回值 |
备注 |
方法名 |
openSetting |
打开任意电台的消息订阅页面 |
Parameters |
fm_id{string} 电台一级类目 callback {function} 接收当前用户与插件绑定电台的订阅状况 |
|
Returns |
no return |
|
Example |
fm.openSetting('fm_15'); |
|
|
值/返回值 |
备注 |
方法名 |
getIconBadgeNumber |
获取任意电台的未读消息数 |
Parameters |
fm_id{string} |
电台一级类目 |
Returns |
未读数 |
|
Example |
fm.getIconBadgeNumber('fm_id', function(unReadNum){ alert(unReadNum); }); |
|
widget 对象呼出千牛各个开放组件的统一方式。
var widget = TOP.mobile.widget;
|
值/返回值 |
备注 |
方法名 |
changePrice |
获得改价组件呼出句柄 |
Parameters |
tid {long} |
订单ID |
Returns |
{function} |
组件句柄，执行function即可呼出组件，在呼出组件时可以透传结果回调 |
Example |
//获得组件句柄 var ui = widget.changePrice(rid); //呼出组件 ui(function(result){ alert(result); }); |
|
|
值/返回值 |
备注 |
方法名 |
refund |
获得退款组件呼出句柄 |
Parameters |
rid {long} |
退款ID |
Returns |
{function} |
组件句柄，执行function即可呼出组件，在呼出组件时可以透传结果回调 |
Example |
//获得组件句柄 var ui = widget.refund(tid); //呼出组件 ui(function(result){ alert(result); }); |
|
|
值/返回值 |
备注 |
方法名 |
pay |
获得支付组件呼出句柄，如果为接入过支付宝支付台的调用方，建议走payBySimpleSDK接口 |
Parameters |
trade_no {string} |
支付宝流水号，多个流水号可以使用逗号分隔 |
Returns |
{function} |
组件句柄，执行function即可呼出组件，在呼出组件时可以透传结果回调 |
Example |
//获得组件句柄 var ui = widget.pay(trade_no); //呼出组件 ui(function(result){ alert(result);//返回结果由支付宝控制，所以无法列出所有错误码，请见谅 }); |
|
|
值/返回值 |
备注 |
方法名 |
payBySimpleSDK |
获得支付极简SDK组件呼出句柄，请先确认和支付宝支付台对接过，已经获得支付宝办法的私钥 |
Parameters |
orderString {string} |
订单信息，需要用支付宝颁发的私钥在服务端签名生成 |
Returns |
{function} |
组件句柄，执行function即可呼出组件，在呼出组件时可以透传结果回调 |
Example |
//获得组件句柄 var ui = widget.payBySimpleSDK(orderString); //呼出组件 ui(function(result){ alert(result);//返回结果由支付宝控制，所以无法列出所有错误码，请见谅 }); |
|
