开心网开放API说明文档

开心网开放API

说明文档

V1.0

2011-01-14

开心网开放API说明文档

开放API是开心网为第三方开发者提供的一组功能强大的外部接口，它支持Java、PHP、.NET等多种编程语言。借助开放API，第三方开发者可以在开心网平台上方便的开发组件或实现连接功能。

一、 已开放的API列表

开心网开放平台API是采用REST基础的接口规范。所有的开心网开放平台API都是通过HTTP POST向/api/发送请求来实现的。

用户信息调用接口（users API）

 身份信息调用接口（o）：获取已安装本组件的某一用户的身份信息，包括UID、姓名、性别、头像以及该用户是否在线；

 UID调用接口（gedInUser）：获取当前用户（正在使用该组件的用户）的UID；

 组件用户判断接口（ser）：判断某一用户是否安装了本组件；

 获取调用开心币接口verify（odeSessionKey）：获取调用开心币接口需要的verify参数；

 邀请成功的好友UID接口（itationSucList）：获取某用户邀请成功的好友UID列表。

好友信息调用接口（friends API）

 好友列表调用接口（）：获取当前登录用户的好友UID列表；

 好友身份信息调用接口（ends）：获取当前登录用户的好友身份信息，包括UID、姓名、性别、头像以及该用户是否在线；

 添加了当前组件的好友调用接口（Friends）：获取添加了当前组件好友的UID列表。

功能调用接口（actions API）

 好友动态调用接口（wsFeed）：发送好友动态接口，即把组件内的动态发送给全部开心网好友；

 系统消息调用接口（sNews）：发送系统消息接口，即把组件内的信息通过系统消息发送给部分开心网好友；

 好友邀请调用接口（vitation）：发送组件邀请接口，即以系统消息的形式从组件内发出邀请，邀请好友添加该组件。

开心币交易接口

开心币交易接口是开心网为第三方开发者提供的一套开心币余额查询、消费接口，借助开心币交易接口，第三方组件可以获取用户的开心币余额信息，并可以支持把用户的开心币兑换为组件的虚拟币或物品。与采用REST基础的接口规范不同，开心币交易接口是普通WEB接口，开发者需要通过verify方式来调用此接口。关于如何获取调用开心币接口的verify，请参考：odeSessionKey。

 Balance接口

URL：/api/

功能：获取登录用户的开心币账户余额

 Spend接口

URL：/api/

功能：把用户账户里的开心币兑换为组件道具或者组件货币

如需调试开心币交易功能，请在“设置组件基本信息”步骤中填写支付服务器IP和测试UID，创建完成后系统自动为您开通调试权限；如需正式开通开心币交易权限，需与我们联系，签署支付相关协议后即可开通。联系邮箱：app@。

开心币详细接口说明，请参考开心币交易接口说明文档。

二、开放API接口说明

1、 参数说明

（1） 身份信息调用接口（o）：获取已安装本组件的某一用户的详细信息，包括UID、姓名、性别、头像以及该用户是否在线

参数说明

必需参数

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

o

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

sig string 由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

uids

v

session_key

string

string

string

用户ID，用逗号隔开，最多50个

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

可选参数 format string Response的格式。支持JSON和XML（缺省值JSON）

JSON格式，返回例子如下：

[{"uid":100099,"name":"u5f20u7433u7433","gender":1,"logo50":"/logo/10/0/50_100099_","online":0},{"uid":100100,"name":"u80e1u4e00u7f8e","gender":0,"logo50":"/logo/10/1/50_100100_","online":0}]。其中gender的返回值0代表男，1代表女。

（2） UID调用接口（gedInUser）：获取当前用户（正在使用该组件的用户）的UID

参数说明

必需参数

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

gedInUser

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

sig string 由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

可选参数 format string Response的格式。支持JSON和XML（缺省值JSON）

返回值例子：{“result”:1234234}或{“result”:0}

（3） 组件用户判断接口（ser）：判断某些用户是否安装了本组件

参数说明

必需参数

method

uids

call_id

string

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api_key，在调用接口时它代表该组件的唯一身份

ser

用户ID，用逗号隔开，最多50个

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

sig string 由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

可选参数 format string Response的格式。支持JSON和XML（缺省值JSON）

返回值例子：{“UID”:1}代表该用户安装了该组件；{“UID”:0}代表该用户没有安装该组件。

（4） 获取调用开心币接口verify（odeSessionKey）：获取调用开心币接口需要的verify参数

参数说明

必需参数

method

call_id

sig

string

float

string

参数名

api_key

类型

string

描述

组件申请时获得的api_key，在调用接口时它代表该组件的唯一身份

odeSessionKey

当前调用请求队列号，建议使用当前系统时间的毫秒值

它是由当前请求参数和secret_key连接进行MD5加密得到的字符串，用于判断发送请求的APP是否合法。

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

返回值例子：{ "result":

"hsrJmM6c5e_100000438_hsrJmM6c5e_1294219695_2d332780bab933de7e55c2c1b9093e9d" }

（5） 邀请成功的好友UID接口（itationSucList）：获取某用户邀请成功的好友UID列表

参数说明

必需参数

method

uid

call_id

sig

string

int

float

string

参数名

api_key

类型

string

描述

组件申请时获得的api_key，在调用接口时它代表该组件的唯一身份

itationSucList

用户的ID

当前调用请求队列号，建议使用当前系统时间的毫秒值

由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

返回值例子：{"11849":{"uid":"11849","mtime":"2010-07-13

10:50:40"},"11852":{"uid":"11852","mtime":"2010-07-13 10:50:40"}}

（6） 好友列表调用接口（）：获取当前登录用户的好友UID列表

参数说明

必需参数

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api_key，在调用接口时它代表该组件的唯一身份

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

sig string 由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

可选参数 format string Response的格式。支持JSON和XML（缺省值JSON）

返回值例子：[27740660，200009399]

（7） 好友身份信息调用接口（ends）：获取当前登录用户的好友身份信息，包括UID、姓名、性别、头像以及该用户是否在线

参数说明

必需参数

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

ends

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

sig string 由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

可选参数 format string Response的格式。支持JSON和XML（缺省值JSON）

JSON格式，返回例子如下：：[{"uid":73878050,"name":"u6052u514bu9686123qweuff01@#u516cu53f8","gender":0,"logo50":"/logo/87/80/50_73878050_","online":0},{"uid":73968865,"name":"u6b27u9633","gender":1,"logo50":"/logo/96/88/50_73968865_","online":0}]

（8） 添加了当前组件的好友调用接口（Friends）：获取当前用户添加了当前组件好友的UID

参数说明

必需参数

method

call_id

sig

string

float

string

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

Friends

当前调用请求队列号，建议使用当前系统时间的毫秒值

由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

可选参数 format string Response的格式。支持JSON和XML（缺省值JSON）

返回值例子：{"11286":1,"12614":1,"13620":1,"876":1,"11560":1,"11578":1,"13187":1,"12047":0,"14165":0,"10244":0,"12071":0,"12245":0,"1172":0}

其中，标志为1表示添加了组件的好友，为0的表示未添加组件的好友

（9） 好友动态调用接口（wsFeed）：发送好友动态接口，即把组件内的动态发送给全部开心网好友。好友动态与系统消息可以自由切换，所以在文案设计时，请确保文案在动态和系统消息两种模式下，语义均通顺。

参数说明

必需参数

v

session_key

string

string

sig string

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

wsFeed

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

text string 发送动态所使用的文案，不超过60个汉字，否则会被截断。该文案可以有{_USER_} {_USER_TA_}变量，解析时会被替换为当前用户名字和他/她。例如，动态文案：{_USER_} 在做XX任务时遇到了强大的XX，快去帮帮{_USER_TA_}！

linktext string 动态里面的链接文字，不超过15个汉字。例如，链接文案：去xx帮忙

link

可选参数

pic2

pic3

mode

string

string

string

format

pic

string

string

string

动态里的链接地址，只能是组件在开心网的相对地址

Response的格式。支持JSON和XML（缺省值JSON）

发送动态所使用的图片地址，如果动态分享中需要发布图片，则此函数为必需（单张图片时，大小为80X80,多张图片为50X50）

发送动态所使用的图片地址(大小为50X50)

发送动态所使用的图片地址(大小为50X50)

发送动态时页面显示方式。0为图层方式， 1为新窗口方式

无返回值，本接口会弹出一个新页面

（10） 系统消息调用接口（sNews）：发送系统消息接口，即把组件内的信息通过系统消息发送给部分开心网好友。好友动态与系统消息可以自由切换，所以在文案设计时，请确保文案在动态和系统消息两种模式下，语义均通顺。

参数说明

必需参数

v

session_key

string

string

sig string

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

sNews

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

text string 发送系统消息所使用的文案，不超过60个汉字，否则会被截断。该文案可以有{_USER_} {_USER_TA_}变量，解析时会被替换为当前用户名字和他/她。例如，系统消息：{_USER_}

在做XX任务时遇到了强大的XX，快去帮帮{_USER_TA_}！链接文案：去{_PARAM3_}帮忙

可选参数

Linktext

link

format

pic

string

string

string

string

系统消息里的链接文字，不超过15个汉字

系统消息里的链接地址，只能是组件在开心网的相对地址

Response的格式。支持JSON和XML（缺省值JSON）

发送系统消息所使用的图片地址，如果系统消息中需要发布图片，则此函数为必需（大小为80X80）

mode string 页面显示方式。0为图层方式，1为新窗口方式

回调URL所用的callbackkey参数。使用方法参照接口回调说明

无返回值，本接口会弹出一个新页面

接口回调说明：

所有的actions类接口都可以设置一个回调URL（所有actions接口使用同一个回调URL，只callbackkey string

是callbackkey参数不同）。组件开发者可以通过这个回调URL知道用户进行了什么操作，从而给用户奖励或者进行别的活动。以系统消息接口为例， 用户使用了actions类接口给好友发系统消息推荐了本组件，可能开发者需要获取接收系统消息的好友的身份信息：

接收系统消息的好友的身份信息将通过一个回调url传送。请先将自定义的回调url告知开心网。请发邮件至app@，会有专人及时处理。

例如：某组件设定的回调url为/abc/。

系统消息发送成功后，开心网会发出一个http请求：

/abc/?uid=xxx&num=xxx&fuids=xxx&ctime=xxx&callbackkey=xxx&sig=xxx。其中，

uid：执行当前操作的用户UID；

num：接收系统消息或邀请用户的数量（发动态时此参数值为0）；

fuids：接收系统消息或邀请的用户的uid，以逗号隔开 （发动态时此参数值为0）；

ctime：执行回调函数的时间戳；

callbackkey：此次操作的代码，系统消息默认为"sysnews"。邀请默认为“invite”, 好友动态默认为”newsfeed”。此操作代码组件可自定义，如：送A类礼物，组件在调用系统消息接口时可增加参数callbackkey=agift；送B类礼物增加参数callbackkey=bgift。开心网执行回调时，会带上这个callbackkey，这样组件就能知道用户执行的是哪种操作了。

sig：签名。sig是此次回调的所有参数与secret key用下划线连接，进行md5加密获得的字符串，用于判断此回调是否真的由开心网发出。生成sig签名：

$queryStr = $_SERVER['QUERY_STRING'];

$queryStr = explode('&sig=', $queryStr);

$localsig = md5($queryStr[0].$secret)

（11） 好友邀请调用接口（vitation）：发送组件邀请接口，即系统消息的形式从组件内发出邀请，邀请好友添加该组件。

参数说明

必需参数

method

call_id

string

float

参数名

api_key

类型

string

描述

组件申请时获得的api key，在调用接口时它代表该组件的唯一身份

vitation

当前调用请求队列号，建议使用当前系统时间的毫秒值。每一次调用接口的call_id 参数都不能一样，后一次调用的应该比前一次大。一般取毫秒数就可以了，如果要连续调用，最好自己做控制，比如每调用一次，把call_id增加0.001

sig string 由当前请求参数和组件申请时获得的secret_key连接，进行MD5加密得到的字符串，用于判断发送的请求是否合法。sig签名均应为小写字母

v

session_key

string

string

API的版本号，目前为1.0

登录用户的session key。用于验证该调用请求是否为当前用户发出的

text string 发送邀请时所使用的，不超过60个汉字，否则会被截断。例如，邀请：我正在开心庄园搭建羊圈，特别需要你加入庄园助我一臂之力！你一旦加入，名字将永远留在我庄园建筑物的功德榜上，等你来！

可选参数

format

mode

string

string

Response的格式。支持JSON和XML（缺省值JSON）

发送邀请所使用的页面显示方式，0为图层方式， 1为新窗口方式

callbackkey string 回调URL所用的callbackkey参数。使用方法参照接口回调说明

无返回值，本接口会弹出一个新页面

获取被邀请好友的身份信息：请参考（10）系统消息调用接口中的接口回调说明

2、 接口调用说明

（1） 请求数据方式说明

http 地址：/api/

actions API为/rest/.

除actions 类API外，其它均是POST方式发送http请求参数。

POST参数例子：api_key=31ef1d4fde8bfcc7b87bd&call_id=1275975267.83&format=json&method=&session_key=11547_100000438_11547_1275974093_c9f552d245ec5655d8ba605c5a094090&v=1.0&sig=949c584659bbc44d93b8d01968015b4a

【注意】以上整个字符串是一个无参数名的POST数据，并非是将多个POST参数连接在一起）

如何生成sig：将请求中所有参数进行排序，排序为字母顺序；将排序好的参数进行转换，去掉"&",例如：k1=v1&k2=v2&k3=v3变为k1=v1k2=v2k3=v3；在上述转换后的串末尾追加上组件的secret_key；用MD5算出上述串的MD5值，然后作为sig的值传入请求中。

调用接口时错误代码的含义请参照附录Ⅰ

（2） 获取session_key

在申请组件时填写的组件首页里，用get方法获取参数名为session_key的参数。如(php语言)：$session_key = $_GET['session_key']。session_key有效时间为4小时，可以保存在本地的cookies或session中，以备调用接口时使用。

已获取的session_key可以通过以下方式验证是否为开心网发出的（此验证非必需）：

将获取的session_key 和组件secret key用下划线连接，进行MD5加密，验证生成的字符串与获取的sig参数是否一致。一致则表示此session_key是开心网发出的。

php 实例：

$secret = 'XXXXXXXX';

$localsig = md5($_GET['session_key'].'_'.$secret);

if ($localsig == $_GET['sig']) {

//正确

}

（3） 调用actions类接口说明

生成POST参数后，将全部参数串进行base64编码，然后将“+”替换成“*”, 将“/”替换成“-”,得到新的字符串。在页面代码中加上如下所示代码：

发送系统消息：图层模式

（4） 接口调用PHP实例

 o

$api_key = 'xxx';

$secret = 'xxx';

$url = '/api/';

$session_key = $_GET['session_key'];

if (empty($session_key)) {

$session_key = $_COOKIE["kx_session_key"];

} else {

setcookie("kx_session_key", $session_key, time()+3600*4);

}

$param = array(

'api_key' => $api_key,

'method' => 'o',

'uids' => '100099,100100',

'format' => 'json',

'session_key' => $session_key,

);

$query = buildQuery($param, $secret);

$result = postRequest($url, $query);

$result = json_decode($result);

function buildQuery($param, $secret) {

$param['call_id'] = microtime(true);

$param['v'] = '1.0';

ksort($param);

$request_str = '';

foreach ($param as $key => $value) {

$request_str .= $key . '=' . $value; // 没有分割符

}

$sig = $request_str . $secret;

$sig = md5($sig);

$param['sig'] = $sig;

$query = http_build_query($param);

return $query;

}

function postRequest($url, $post_string) {

$useragent = ' API PHP5 Client 1.1 (curl) ' . phpversion();

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_USERAGENT, $useragent);

curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);

curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$result = curl_exec($ch);

curl_close($ch);

return $result;

}

function url_base64_encode($str)

{

$search = array ('+', '/');

$replace = array ('*', '-');

$basestr = base64_encode($str);

return str_replace( $search, $replace, $basestr );

}

 wsFeed

$param = array(

'api_key' => $api_key,

'method' => 'wsFeed',

'format' => 'json',

'session_key' => $session_key,

'mode' => 0,

'pic' => '/i3/cafe/share/',

'pic2' => '/i3/cafe/share/',

'pic3' => '/i3/cafe/share/',

'link' => '/!other_sayhello/',

'text' => '{_USER_} 在做XX任务时遇到了强大的敌人，快去帮帮{_USER_TA_}！',

'linktext' => '去帮忙>>',

);

$query = buildQuery($param, $secret);

$para = url_base64_encode($query);

?>

发送动态：图层模式

附录Ⅰ：

调用接口的错误代码含义

'code' => 1001,

'text' => 'API KEY 不存在',

'code' => 1002,

'text' => 'APP 已经被禁用',

'code' => 1003,

'text' => 'API 签名错误',

'code' => 1004,

'text' => '请求方法不存在',

'code' => 1005,

'text' => '没有权限调用这个 API',

'code' => 1006,

'text' => '用户未登录或 session_key错误,请重新登录',

'code' => 1007,

'text' => 'session_key错误',

'code' => 1008,

'text' => '当前用户未添加组件',

'code' => 1009,

'text' => 'session key 为空',

'code' => 1010,

'text' => 'app还没提交',

'code' => 1011,

'text' => 'api版本错误'。请检查api版本是否为 1.0以及$post_string 是否有值,

'code' => 1012,

'text' => 'call id 错误',

'code' => 2001,

'text' => '缺少参数',

'code' => 2002,

'text' => '参数类型错误',

'code' => 2003,

'text' => 'uids数量超出限制',

'code' => 4001,

'text' => 'action参数错误',

'code' => 4002,

'text' => 'textcode 参数错误',

'code' => 4003,

'text' => 'stime 超时',

'code' => 4004,

'text' => '非种子用户不能邀请',