账号系统

• 1. 小天才账号系统是什么？
• 2. 账号系统对接流程
  • 2.1 小天才开放平台入驻申请
  • 2.2 开发对接
  • 2.3 测试对接
  • 2.4 应用上线
• 3. 账号系统对接指引
  • 3.1 账号授权服务时序图
  • 3.2 根据授权码调用token接口获取身份凭证accessToken
  • 3.3 根据refreshToken接口获取新的accessToken
• 4. 获取用户账号信息
  • 4.1 概述
  • 4.2 根据accessToken获取用户信息
  • 4.3 新openId转换成旧openId兼容逻辑处理（2019年9月之前接入的第三方使用）
• 5. 开放排名服务
  • 5.1 概述
  • 5.2 开放排名服务时序图
  • 5.3 上传应用排名数据
  • 5.4 获取好友排行榜数据
  • 5.5 获取校园排行榜数据

1. 小天才账号系统是什么？

通俗的讲，就是一个手表在一个应用中的账号，一个手表在不同应用的账号标识都是不同且唯一的。此外，基于小天才账号授权可获取用户昵称、头像等基本信息，也可在此之上提供应用服务号、好友排行等服务。

2. 账号系统对接流程

2.1 小天才开放平台入驻申请

您在开放平台填完入驻申请之后，在微信群中通知XTC的同学，XTC这边审核之后会给您的应用分配appId、appSecret和第三方应用权限范围（默认头像、名称和推送），之后会将appId和appSecret信息同步到群中。

2.2 开发对接

• 需集成表端账户系统sdk。
• sdk获取方式： 群中找小天才的技术同学获取。

2.3 测试对接

• 测试环境的appId、appSecret与正式环境可能不同，在微信群同步应用时会说明appId和appSecret对应哪个环境，您在对应环境使用对应的appId等应用信息传参即可。

• 访问小天才的服务器接口，调试时请使用测试环境域名，调试成功提测正式版本，请换成正式环境域名。

  • 测试环境域名： https://api-module.okii.com
  • 正式环境域名： https://api.watch.okii.com

• 请注意，手表有测试环境和正式环境之分。判断手表当前环境：点击手表绑定号—>观察右上角，如果有模块二字，则为测试环境，否则为正式环境，下图为测试环境手表示例图。

• 手表环境的切换方式： 请在微信群联系小天才的同学。

2.4 应用上线

3. 账号系统对接指引

3.1 账号授权服务时序图

注：当前appId、appSecret和第三方应用权限范围由小天才服务器分配后在群里进行信息同步。

3.2 根据授权码调用token接口获取身份凭证accessToken

3.2.1 调用时机

• 您从客户端通过sdk拿到授权认证码code后，授权码code的有效期为10分钟。

3.2.2 接口说明

• 功能：拿到手表的临时身份信息凭证，通过这个凭证可以获取手表头像、名称等信息。

• 请求方式：POST

• 协议类型：HTTPS

• 数据格式：json

• 服务URL：

  测试环境：https://api-module.okii.com/oauth/token

  正式环境：https://api.watch.okii.com/oauth/token

• 注意：用户可以主动取消授权，此时之前获取的token便不再有效，目前取消授权不会通知第三方。

• 消息方向：第三方应用->开放服务

• 请求参数

参数	参数名称	类型	必填	参数说明
appId	第三方应用唯一标识	int	是	由小天才分配给接入方的应用标识ID
appSecret	第三方应用秘钥	String	是	由小天才分配给接入方的应用秘钥
code	授权认证码	String	是	通过小天才手表SDK获取的授权码code（有效期10分钟）
grantType	授权类型	String	是	固定值:authorization_code

• 示例

{
    "appId": 100001,
    "appSecret": "123456",
    "grantType": "authorization_code",//固定值
    "code": "0b6bbfedc7044676a65c63e6959d81c2"//授权码
}

• 响应消息

{
  "code": "000001",
  "desc": "SUCCESS",
  "data": {
    "accessToken": "3d9eb36db7594c569702a940e9e86b0d",// 用户授权凭证，有效期3天
    "expiresTime": 259200, // token过期时间，单位秒（S）
    "refreshToken": "8e49c6c296024518bf352c97a29cadf7",// token过期时可以通过该参数获取新的token，有效期90天
    "openId": "a614044b00a8406387aeba629b0e4f75",// 表示该手表在该应用的唯一ID
    "scope": "1"
  }
}

注：scope传值范围目前有下列几种，权限需要小天才开放平台进行分配

值	权限名称
1	用户的基础信息
4	用户好友排行
5	服务号更新时推送到家庭圈、手表

• 返回状态

状态码	提示消息
"12001"	参数无效
"12002"	授权类型有误
"12007"	APPID或APPSecret信息无效
"12004"	授权码已过期、已经被使用过或者不存在（如果不是前两种情况，请检查手表环境和服务器的调用环境URL是否一致，手表环境查看见2.3节）

3.3 根据refreshToken接口获取新的accessToken

3.3.1 功能描述

您通过授权认证码code调用token接口获取accessToken（有效期三天）的同时会返回一个refreshToken（有效期三个月），当accessToken过期后可通过refreshToken接口获取新的accessToken，相当于续期操作。

3.3.2 接口说明

• 请求方式：POST

• 协议类型：HTTPS

• 数据格式：json

• 服务URL：

  测试环境：https://api-module.okii.com/oauth/refreshToken

  正式环境：https://api.watch.okii.com/oauth/refreshToken

• 消息方向：第三方应用->授权服务

• 请求参数

参数	参数名称	类型	必填	参数说明
appId	第三方应用唯一标识	int	是	由小天才分配给接入方的应用标识ID
appSecret	第三方应用秘钥	String	是	由小天才分配给接入方的应用秘钥
grantType	授权类型	String	是	固定值: refresh_token
refreshToken	刷新token	String	是	3.2节token接口返回的refreshToken

• 示例

{
    "appId": 100001,
    "appSecret": "123456",
    "grantType": "refresh_token",//固定值
    "refreshToken": "e6c189f9cc2449b59d5eff12c1616eed"//刷新token(在获取token的接口会返回
}

• 响应消息

{
  "code":"000001",
  "desc":"SUCCESS",
  "data":{
      "accessToken":"3d9eb36db7594c569702a940e9e86b0d",
      "expiresTime":259200,
      "refreshToken":"8e49c6c296024518bf352c97a29cadf7",
      "openId":"a614044b00a8406387aeba629b0e4f75",
      "scope":"1"
  }
}

注意： 在使用过refreshToken之后，会返回一个新的refreshToken，原先的refreshToken一分钟后失效。

• 返回状态

状态码	提示消息
"12001"	参数无效
"12002"	授权类型有误
"12007"	APPID或APPSecret信息无效
"12005"	refreshToken无效
"12006"	授权无效，重新走用户授权流程

4. 获取用户账号信息

4.1 概述

• 调用方： 第三方服务器
• 作用： 通过accessToken获取用户相关信息
• 测试环境域名： https://api-module.okii.com
• 正式环境域名： https://api.watch.okii.com

4.2 根据accessToken获取用户信息

根据accessToken获取用户授权的信息，信息包括头像、昵称、用户的唯一标识openId（若第三方应用成功在平台上申请了其它权限，可获取更多授权信息）。

4.2.1 接口说明

• 请求方式：POST
• 协议类型：HTTPS（POST请求）
• 数据格式：json
• 服务URL（测试环境域名）：https://api-module.okii.com/resource-service/resource/getUserInfo
• 消息方向：第三方应用->资源服务
• 请求参数

参数	参数名称	类型	必填	参数说明
accessToken	授权令牌	String	是	授权令牌
openId	用户openId	String	是	用户openId，token或者refreshToken返回的手表标识ID

• 示例

{
    "openId": "f94d6ff02e134624bfd2fa1ddcb0fdd9",
    "accessToken": "c204f68d78aa41f88002f0f2374732d"
}

• 响应消息

{
     "avatarUrl":"https://watchcdn.okii.com/xxx.jpg", // 手表头像地址
     "nickName": "zhangwtest",// 手表名称
     "openId": "f94d6ff02e134624bfd2fa1ddcb0fdd9",
     "unionId": "cfghc6ff02e134624bfd2fa1ddcb0fdd9" //开发者和用户的唯一id
}

• 返回状态

状态码	提示消息
"12001"	参数无效
"12008"	accessToken无效或过期
"12010"	无效openId
"12009"	该应用没有此权限

4.3 新openId转换成旧openId兼容逻辑处理（2019年9月之前接入的第三方使用）

4.3.1 接口说明

• 请求方式：POST
• 协议类型：HTTPS
• 数据格式：json
• 服务URL（测试环境域名）：https://api-module.okii.com/resource-service/resource/getOldOpenId
• 消息方向：第三方应用->获取用户账号信息服务
• 请求参数

参数	参数名称	类型	必填	参数说明
accessToken	授权令牌	String	是	授权令牌
openId	用户openId	String	是	用户openId
appId	第三方应用id	int	是	第三方应用id

• 示例

{
	"appId": 100005,
	"authList": [{
		"accessToken": "58223983efd14a59ba37620379be85c2",
		"openId": "2d8b34acddb248898b5b178740f2fe26"
	}, {
		"accessToken": "704737e9feac4963bab34ea8b2451008",
		"openId": "76ef8684e5014a3cb237878778f5085b"
	}]
}

• 响应消息

{
	"code": "000001",
	"desc": "SUCCESS",
	"data": {// 新openId->旧openId的映射map
		"76ef8684e5014a3cb237878"(新openId): "8461B6A1564DF055A54F3EFF053D93A3"(旧openId),
		"2d8b34acddb248898b5b178740f2fe26": "C8A58D1C2539A96AC85AEC2481D7BBD9FF42BC5E3"
	}
}

• 返回状态

状态码	提示消息
"12001"	参数无效
"12010"	无效openId
"12099"	其他错误

5. 开放排名服务

5.1 概述

• 调用方： 第三方服务器
• 作用： 实现排行榜功能，提高第三方应用活跃度
• 测试环境域名： https://api-module.okii.com
• 正式环境域名： https://api.watch.okii.com

5.2 开放排名服务时序图

5.3 上传应用排名数据

5.3.1 接口说明

• 请求方式：POST
• 协议类型：HTTPS（POST请求）
• 数据格式：json
• 服务URL（测试环境域名）：https://api-module.okii.com/resource-service/ranking/thirdParty/uploadData
• 消息方向：第三方应用->开放排名服务
• 请求参数

参数	参数名称	类型	必填	参数说明
accessToken	授权令牌	String	是	授权令牌
openId	用户openId	String	是	用户openId
appId	第三方应用id	int	是	第三方应用id
type	应用排名类型	int	否	第三方应用类型（旧数据和默认为1）
dataType	数据排行类型	int	否	默认最大值参与排行（0 最大值，1最小值）（默认0）
data	应用排名数据	Object	是	应用排名数据（数字类型采用Long接收）

• 示例

{
    "openId": "c5284b3270134be28e957fe570c3e54a",
    "appId": 100001,
    "accessToken": "1d27d3391e094828b57db767b4161e93",
    "type": 1,
    "dataType":0,
    "data": "3"
}

• 响应消息

{
  "code":"000001",
  "desc":"SUCCESS",
  "data":1,
} 
//data等于1时上报成功，为-1时上报失败，null时未更新数据(非最高分)

• 返回状态

状态码	提示消息
"12001"	参数无效
"12010"	无效openId
"12011"	授权超过申请范围
"12099"	其他错误
"12009"	该appId没有权限

5.4 获取好友排行榜数据

5.4.1 接口说明

• 请求方式：POST
• 协议类型：HTTPS
• 数据格式：json
• 服务URL（测试环境域名）：https://api-module.okii.com/resource-service/ranking/thirdParty/getRankingList
• 消息方向：第三方应用->开放排名服务
• 请求参数

参数	参数名称	类型	必填	参数说明
accessToken	授权令牌	String	是	授权令牌
openId	用户openId	String	是	用户openId
appId	第三方应用id	int	是	第三方应用id
type	应用排名类型	int	否	第三方应用类型（旧数据和默认为1）
sortType	应用排序类型	String	否	排序类型:DESC,ASC（默认倒序）
iconType	头像类型	int	否	是否需要头像，0否，1是（默认1）
dataType	数据排行类型	int	否	默认最大值参与排行（0 最大值，1最小值）（默认0）
page	分页参数	Object	否	分页实体

• 示例

{
    "openId": "c5284b3270134be28e957fe570c3e54a",
    "appId": 100001,
    "accessToken": "1d27d3391e094828b57db767b4161e93",
    "type": 1,
    "sortType": "DESC",
    "iconType": 1,
    "dataType":0,
    "page":{// 分页参数，非必须，不填返回全部
        "pageSize": 1, // 一页的数量
        "nowPage": 1 // 第几页
    }
}

• 响应消息

{
	"code": "000001",
	"desc": "SUCCESS",
	"data": [// 排行数据列表
      {
		"openId": "2d8b34acddb248898b5b178740f2fe26",
		"name": "白Z5",// 手表昵称
		"icon": "https://qn.authtest.okii.com/user_avat",// 头像地址
		"appId": 100005,
		"data": "50", 
		"rank": 1, // 排名
		"type": 1 // 类型
	  }
    ],
    "extra": {// 个人的排名，rank值为-1时表示没有排行数据
        "openId": "28a49be2c4334494a4aff0c3ec428438",
        "name": "张三",
        "icon": "https://qn.authtest.okii.com/user_avat",// 头像地址
        "appId": 100037,
        "data": "10",
        "rank": 5,
        "type": 1 // 类型
    },
    "page": {// 分页信息，入参有分页信息时则返回
        "nowPage": 1, // 当前页
        "totalRecord": 5,// 总记录数
        "totalPage": 3,// 总页数
        "pageSize": 2,// 一页的数量
        "startIndex": 4// 起始下标
    }
}

• 返回状态

状态码	提示消息
"12001"	参数无效
"12010"	无效openId
"12011"	授权超过申请范围
"12099"	其他错误，联系XTC开发查明原因
"12009"	该appId没有权限

5.5 获取校园排行榜数据

5.5.1 接口说明：获取同一个学校内该应用的排行榜。

• 请求方式：POST

• 协议类型：HTTPS

• 数据格式：json

• 服务URL（测试环境域名）：https://api-module.okii.com/resource-service/ranking/thirdParty/getSchoolRankingList

• 消息方向：第三方应用->开放排名服务

• 注意：

  • 只会展示学校、年级和班级三项信息全部填写的数据。

  • 数据源数据并非实时数据，周一凌晨1点之前填写的周二同步，周四凌晨1点之前填写周五同步。如：我在周一早上9点填写了学校、年级和班级，那么数据会在周五进行同步，如果周日填写则周二同步。

  • 由于成本原因，测试环境的校园排行榜数据不再维护。

    ​ 小天才这边的建议是测试环境确认好友排行榜没问题之后上正式测试校园排行榜，因为校园排行榜的参数跟好友排行榜是完全一致的，好友排行榜无误的话基本上校园排行榜的入参也不会有问题。

• 请求参数

参数	参数名称	类型	必填	参数说明
accessToken	授权令牌	String	是	授权令牌
openId	用户openId	String	是	用户openId
appId	第三方应用id	int	是	第三方应用id
type	应用排名类型	int	否	第三方应用类型（旧数据和默认为1）
sortType	应用排序类型	String	否	排序类型:DESC,ASC（默认倒序）
iconType	头像类型	int	否	是否需要头像，0否，1是（默认1）
dataType	数据排行类型	int	否	默认最大值参与排行（0 最大值，1最小值）（默认0）
page	分页实体	Object	否	分页参数

• 示例

{
    "openId": "c5284b3270134be28e957fe570c3e54a",
    "appId": 100001,
    "accessToken": "1d27d3391e094828b57db767b4161e93",
    "type": 1,
    "sortType": "DESC",
    "iconType": 1,
    "dataType":0,
    "page":{// 选填，不填默认返回全部
        "pageSize": 2,// 一页的数量
        "nowPage":1 // 第几页
    }
}

• 响应消息

{
	"code": "000001",
	"desc": "SUCCESS",
	"data": [// 排行数据列表
      {
		"openId": "2d8b34acddb248898b5b178740f2fe26",
		"name": "白Z5",// 手表昵称
		"icon": "https://qn.authtest.okii.com/user_avat",// 头像地址
		"appId": 100005,
		"data": "50", 
		"rank": 1, // 排名
        "type": 1 // 类型
	  }
    ],
    "extra": {// 个人的排名，rank值为-1时表示没有排行数据
        "openId": "28a49be2c4334494a4aff0c3ec428438",
        "name": "张三",
        "icon": "https://qn.authtest.okii.com/user_avat",// 头像地址
        "appId": 100037,
        "data": "10",
        "rank": 5,
        "type": 1 // 类型
    },
    "page": {// 分页信息，入参有分页信息时则返回
        "nowPage": 1, // 当前页
        "totalRecord": 5,// 总记录数
        "totalPage": 3,// 总页数
        "pageSize": 2,// 一页的数量
        "startIndex": 4// 起始下标
    }
}

• 返回状态

状态码	提示消息
"12001"	参数无效
"12010"	无效openId
"12011"	授权超过申请范围
"12099"	其他错误，联系XTC开发查明原因
"12009"	此范围未授权
"12012","12206"	用户没有填写学校年级班级信息，或者还未进行同步，原因见5.5.1 接口说明的注意