注意:以下文档只适用于TOP接口,请谨慎使用!

 第一章 PC端API

1.QN.top.invoke top服务... 19

1.1 top接口字符串... 19

1.2 tql

2.预定义的事件... 24

2.1 wangwang.active_contact_changed.. 24

2.2 wangwang.trade_focus交易焦点... 25

2.3 wangwang.contact_closed正在联系人列表中关闭该联系人... 25

2.4 wangwang.contact_joined联系人列表中加入新的接入人... 25

2.5 wangwang.chatdlg_open旺旺聊天窗口打开... 26

2.6 wangwang.chatdlg_closed旺旺聊天窗口关闭... 26

2.7 bench.attach_wnd.close插件附属窗口的关闭通知... 26

2.8 bench.trade_info交易通知... 26

2.9 bench.refund_info退款通知... 27

2.10 bench.item_info宝贝通知... 28

2.11 bench.colorize换肤主题色通知

2.12 wangwang.recvmsgurl.itemid对方发送了宝贝链接的通知

... 29

3. 常见错误码... 29

第二章 移动端API 29

1. System对象... 29

1.1 pasteboard获取系统剪切板里的信息... 29

1.2. pasteboard复制信息到剪切板... 30

1.3 information. 30

1.4 API调用top api 31

2. Contacts对象... 32

2.1 list获取联系人列表... 32

2.2 myPhoneNum获取当前手机号... 32

3. Camera对象... 33

3.1 getPicture获取照片... 33

3.2 resize按指定大小压缩图片... 34

3.3 scan利用摄像头对二维码条形码进行扫描... 34

4 notification对象... 35

4.1 vibrate手机震动... 35

4.2 lockscreen控制锁屏... 35

5. ww对象... 35

5.1chat呼出和某个聊天的聊天对话框... 36

6. fm对象... 36

6.1 info查询和当前应用绑定的电台的订阅信息... 36

6.2 spread手机震动... 37

6.3 openSetting打开任意电台的消息订阅页面... 38

6.4 getIconBadgeNumber获取任意电台的未读消息数... 38

7. Widget对象... 38

7.1 changePrice获得改价组件呼出句柄... 38

7.2 refund获得退款组件呼出句柄... 39

7.3 pay支付组件... 39

7.4 payBySimpleSDK.. 40

 

 

 

 

 

 

 

 

 

 

 

第一章 PC端API

1.QN.top.invoke top服务

1.1 top接口字符串

参数名

值/返回值

备注

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

 

 

 

1.2 tql

参数名

值/返回值

备注

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

 

 

 

 

2.预定义的事件

2.1 wangwang.active_contact_changed

参数名

值/返回值

备注

eventId

wangwang.active_contact_changed

旺旺聊天焦点用户切换

对于旺旺插件,如果不监听,每次切换旺旺联系人将刷新callback_url,用户感受延迟体验不好,并造成ISV后台压力。

强烈建议使用监听该事件的方式来做,但需要保证内存不泄漏。

data

{

'old_contact':xxx,

'new_contact':xxx

}

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.2 wangwang.trade_focus交易焦点

参数名

值/返回值

备注

eventId

wangwang.trade_focus

交易焦点

data

{

'type':gid的类型,

'gids':xxx,

'user':焦点信息对应的用户

}

type:0交易;1商品

gids:是该交易焦点中包含的所有ID(宝贝ID可能有多个,订单ID只有一个)

msg(reg)

 

 

msg(unreg)

 

 

 

2.3 wangwang.contact_closed正在联系人列表中关闭该联系人

参数名

值/返回值

备注

eventId

wangwang.contact_closed

正在联系人列表中关闭该联系人

data

{

'contact':"关闭的联系人"

}

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.4 wangwang.contact_joined联系人列表中加入新的接入人

参数名

值/返回值

备注

eventId

wangwang.contact_joined

联系人列表中加入新的接入人

data

{

'contact':"新接入的联系人"

}

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.5 wangwang.chatdlg_open旺旺聊天窗口打开

参数名

值/返回值

备注

eventId

wangwang.chatdlg_open

旺旺聊天窗口打开

data

 

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.6 wangwang.chatdlg_closed旺旺聊天窗口关闭

参数名

值/返回值

备注

eventId

wangwang.chatdlg_close

旺旺聊天窗口关闭

data

 

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.7 bench.attach_wnd.close插件附属窗口的关闭通知

参数名

值/返回值

备注

eventId

bench.attach_wnd.close

插件附属窗口的关闭通知

data

{

event:'xxx'

}

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.8 bench.trade_info交易通知

参数名

值/返回值

备注

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

订单信息已修改

 

2.9 bench.refund_info退款通知

参数名

值/返回值

备注

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

退款已超时

 

 

2.10 bench.item_info宝贝通知

参数名

值/返回值

备注

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

商品体检日报

 

2.11 bench.colorize换肤主题色通知

参数名

值/返回值

备注

eventId

bench.colorize

换肤主题色通知

data

{

"rgb" : 'ffffff',

"textColor": 'ffffff',

"backgroundImageUrl": 'http://.',//cdn上图片地址

"backgroundPositionX":"left",//right左对齐或右对齐

}

 

msg(reg)

 

 

msg(unreg)

 

 

 

2.12 wangwang.recvmsgurl.itemid对方发送了宝贝链接的通知

参数名

值/返回值

备注

eventId

wangwang.recvmsgurl.itemid

对方发送了宝贝链接的通知

data

{

"fromuid":"顾客的nick",

"itemid":"192262821019180"

}

 

msg(reg)

 

 

msg(unreg)

 

 

3. 常见错误码

code:-501088242, msg:top net error

TOP请求网络层失败,具体信息可以参考sub_code,sub_msg

code:-501088255,msg:plugin in calling, wait

上一次对插件的调用还未结束。通常原因是插件页面加载后未设置回包,如何设置回包,参考开发文档 设置回包 章节

 

第二章 移动端API

1. System对象

system 对象提供用户对剪切板的操作。

var system = TOP.mobile.sys;

1.1 pasteboard获取系统剪切板里的信息

 

值/返回值

备注

方法名

pasteboard

获取系统剪切板里的信息

Parameters

callback {function}

接收系统剪切板信息的回调

Returns

{

        type:'text',

        content:info

}

 

Example

system.pasteboard(function(info){

       alert(info);

});

 

 

1.2. pasteboard复制信息到剪切板

 

 

值/返回值

备注

方法名

pasteboard

复制信息到剪切板

Parameters

 info {string} 需要往剪切板设置的信息

 

Returns

{

        type:'text',

        content:info

}

 

Example

system.pasteboard('你好,我是测试。测试URL:http://taobao.com。测试引号:\' ,",\'');});

 

1.3 information

 

值/返回值

备注

方法名

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);

}

 

 

1.4 API调用top api

 

值/返回值

备注

方法名

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));

});

 

 

2. Contacts对象

contacts 对象提供对用户联系人的操作权限。

var contacts = TOP.mobile.contacts;

2.1 list获取联系人列表

 

值/返回值

备注

方法名

list

获取联系人列表

Parameters

 callback {function}

接收联系人列表

Returns

{code:10006}

 

或者列表为空 表示用户拒绝

  正常情况待补充

Example

contacts.list(function(info){

                     alert(info);

  });

 

 

2.2 myPhoneNum获取当前手机号

 

值/返回值

备注

方法名

myPhoneNum

获取当前手机号,目前只支持android手机

Parameters

 callback {function}

接收当前手机号

Returns

{

       name:'mySelf'

       phone:'13811111111'

}

 

Example

contacts.myPhoneNum(function(info){

                     alert(info);

  });

 

 

3. Camera对象

camera 对象提供用户对摄像头的操作,可以进行拍照,扫描,和图片获取。

var camera = TOP.mobile.device.camera;

 

3.1 getPicture获取照片

 

值/返回值

备注

方法名

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);

  });

 

3.2 resize按指定大小压缩图片

 

值/返回值

备注

方法名

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');

 

3.3 scan利用摄像头对二维码条形码进行扫描

 

值/返回值

备注

方法名

scan

利用摄像头对二维码条形码进行扫描

Parameters

 callback {function}

接收扫描结果

Returns

{string}

 

Example

camera.scan(function(result){

alert(result);

});

 

4 notification对象

notification模块负责完成通知用户感官的一些操作,如震动,锁屏等。

var notification = TOP.mobile.notification;

4.1 vibrate手机震动

 

值/返回值

备注

方法名

vibrate

手机震动

Parameters

 no paramter

 

Returns

no return

 

Example

notification.vibrate();

 

4.2 lockscreen控制锁屏

 

值/返回值

备注

方法名

lockscreen

控制锁屏

Parameters

 lockorNot{boolean}

true表示长时间未操作自动锁屏,false表示关闭锁屏功能,长时间未使用也不锁屏

Returns

no return

 

Example

notification.lockscreen(true);

 

5. ww对象

ww对象负责和千牛的旺旺模块交互。

var ww = TOP.mobile.ww;

5.1chat呼出和某个聊天的聊天对话框

 

值/返回值

备注

方法名

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',

});

 

6. fm对象

fm提供操作用户电台订阅数据的接口

var fm = TOP.mobile.fm;

注意,fm提供的方法根据安全等级不一样,有的只能操作自己插件对应的电台的数据,有的可以操作所有电台的数据。具体请看方法详情。

一个应用只能绑定一个电台,形成一一对应的关系

6.1 info查询和当前应用绑定的电台的订阅信息

 

值/返回值

备注

方法名

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){

 

});

 

 

6.2 spread手机震动

 

值/返回值

备注

方法名

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){

 

});

 

6.3 openSetting打开任意电台的消息订阅页面

 

值/返回值

备注

方法名

openSetting

打开任意电台的消息订阅页面

Parameters

fm_id{string} 电台一级类目

callback {function} 接收当前用户与插件绑定电台的订阅状况

 

Returns

no return

 

Example

fm.openSetting('fm_15');

 

6.4 getIconBadgeNumber获取任意电台的未读消息数

 

值/返回值

备注

方法名

getIconBadgeNumber

获取任意电台的未读消息数

Parameters

fm_id{string}

电台一级类目

Returns

未读数

 

Example

fm.getIconBadgeNumber('fm_id',

function(unReadNum){

alert(unReadNum);

});

 

7. Widget对象

 widget 对象呼出千牛各个开放组件的统一方式。

 var widget = TOP.mobile.widget;

7.1 changePrice获得改价组件呼出句柄

 

值/返回值

备注

方法名

changePrice

获得改价组件呼出句柄

Parameters

 tid {long}  

订单ID

Returns

{function}

组件句柄,执行function即可呼出组件,在呼出组件时可以透传结果回调

Example

//获得组件句柄

var ui = widget.changePrice(rid);

//呼出组件

ui(function(result){

                      alert(result);

});

 

7.2 refund获得退款组件呼出句柄

 

值/返回值

备注

方法名

refund

获得退款组件呼出句柄

Parameters

 rid {long}

退款ID

Returns

{function}

组件句柄,执行function即可呼出组件,在呼出组件时可以透传结果回调

Example

//获得组件句柄

var ui = widget.refund(tid);

//呼出组件

ui(function(result){

       alert(result);

});

 

7.3 pay支付组件

 

值/返回值

备注

方法名

pay

获得支付组件呼出句柄,如果为接入过支付宝支付台的调用方,建议走payBySimpleSDK接口

Parameters

 trade_no {string}

支付宝流水号,多个流水号可以使用逗号分隔

Returns

{function}

组件句柄,执行function即可呼出组件,在呼出组件时可以透传结果回调

Example

//获得组件句柄

var ui = widget.pay(trade_no);

//呼出组件

ui(function(result){

       alert(result);//返回结果由支付宝控制,所以无法列出所有错误码,请见谅

});

 

7.4 payBySimpleSDK

 

值/返回值

备注

方法名

payBySimpleSDK

获得支付极简SDK组件呼出句柄,请先确认和支付宝支付台对接过,已经获得支付宝办法的私钥

Parameters

 orderString {string}

订单信息,需要用支付宝颁发的私钥在服务端签名生成

Returns

{function}

组件句柄,执行function即可呼出组件,在呼出组件时可以透传结果回调

Example

//获得组件句柄

var ui = widget.payBySimpleSDK(orderString);

//呼出组件

ui(function(result){

       alert(result);//返回结果由支付宝控制,所以无法列出所有错误码,请见谅

});

 

 

FAQ

关于此文档暂时还没有FAQ
返回
顶部