# 答题游戏接口说明
## 修改记录
### 2021604
1. [增加用户信息](#212), [抽奖转盘信息](#213), [抽奖](#214), [邀请奖励信息](#215), [挑战详情](#216) 接口
2. 所有接口增加post字段 version(当前版本固定取1.0.1)和sessionid(取自jcfw)
3. 获取店铺信息 增加返回店铺的数字编号
4. 上报测验题目答案相关接口的 奖励信息 增加返回rewardType, 0: 表明该奖励为优惠券, 1: 抽奖券
5. 用户信息上报接口 增加上报当前店铺
### 20210609
1. 增加 [邮件列表](#217), [设置邮件已读](#218), [领取邮件附件](#219), [删除邮件](#220)
### 20210610
1. 增加 [显示正确答案](#221)
2. 增加 [公告列表](#222)
### 20210611
1. [获取店铺信息](#208) 增加返回字段 local, 用于表示是否使用本地数据
### 20210616
1 . [获取店铺信息](#208) 增加返回默认的分享图和分享语
### 20210705
1. 增加[开始分享优惠券](#223), [领取分享的优惠券](#224), [优惠券详情](#225) 接口
2. [用户券列表](#211), [抽奖](#214), [邀请奖励信息](#215), [领取邮件附件](#217)等接口返回的优惠券信息, 增加expire字段
3. [获取店铺信息](#208) 的gamecfg增加返回 default_desc_txt, 用于首页介绍文字
4. [获取店铺信息](#208) 的挑战列表增加返回 beginTime和endTime
## 一. 说明
所有接口均需上传sessionid
通用返回JSON结构, 接口Response的数据结构说明只包含data部分
``` JSON
{
"errcode": 0, //0:成功 2: 缺少必要参数(accountid, sessionid) 4: 帐号被封, 5: 帐号未找到 100: 所有未定义的错误
"errmsg": "", //错误描述
"data": {}, // 数据
}
```
## 二. 客户端接口列表
### 1. 获取关卡题目列表
1. Method: POST
2. URI: /api/:accountid/puzzle/list
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| shop | 店铺id, 比如 607ff59d4a4e16687a3b7079 |
| level | 关卡id |
| type | 是否降低难度 0: 普通, 1: 降低难度 |
3. Response: JSON
```js
{
session: "6080f330b9655b5c0467ee5a", // 当前局的id,提交答案时必须上报该字段
records: [{
"id": "6080f330b9655b5c0467ee5e", // 题目id
"title": "“大丈夫为国捐躯，死而无憾！”这话是谁说的？", // 问题
"answers": [ // 可选答案
"刘铭传",
"徐骧",
"刘步蟾",
"刘永福"
],
"category": "体育-体育", // 类型
"type": 1, // 题目类型 1: 普通的文字选择题, 2: 图形, 3: 问卷式题目
"quality": 1 // 题目难度
}]
}
```
### 2. 上报题目答案
1. Method: POST
2. URI: /api/:accountid/puzzle/answer
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| id | 题目id |
| session | 当局的id, 从关卡题目列表中获取 |
| level | 关卡id |
| answer | 回答的选项 |
| type | 回答类型, 0: 正常, 1: 超时 |
| mode | 游戏类型, 0: 单人, 1: 多人 |
| debug | 多人模式时, 如果该字段有值, 则直接进入下一轮 |
3. Response: JSON
```js
{
result: 1, //答题结果 1: 正确, 0 : 错误
gameResult: 0, // 当前局游戏结果 0: 未完成, -1: 失败, 1: 胜利
answer: '正确答案',
over: 0.1222, // 超越玩家值, 显示时x100
"stats": { // 当局的状态
"1111": {
"answer": {// 每一题的结果, key为题目的id, 值为answer在答案中的index值, 0为正确值, -1为超时, 其他都为错误
"608a3d15e678843dd443fa53": 0,
},
"total": 2, // 总答题数量
"rightCount": 1, // 答对的数量
"errorCount": 1, // 答错的数量
"comboCount": 0, // 当前连续答对的数量
"maxCombo": 1, // 当局连续答对的最大数量
"score": 10, // 当局胜利后的得分
"star": 1, // 当局胜利后获得的星星
"timeLeft": 1, // 当局剩余时间
"gameResult": 0 // 当局的游戏结果, 单人的话和上一层gameResult相同
}
},
}
```
### 3. 开始匹配
1. Method: POST
2. URI: /api/:accountid/puzzle/match
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| shop | 店铺id |
| aid | 活动id |
| debug_begin_sec | 游戏于n秒后开始, 最小2秒, 测试用 |
| debug_qcount | 题目数量 |
3. Response: JSON
```js
{
"roomId": "mysWNuFnY", //房间id
"beginTime": 1619689073034, // 游戏的开始时间
"sessionId": "adfadf" // 当前用户在该房间的sessionId, 如果有该字段, 客户端在joinById的时候须带上该字段
"session": "608baeea9d0fe70ccd54cf9c" // 当前局的id,提交答案时必须上报该字段
}
```
### 4. 获取关卡更多题目
1. Method: POST
2. URI: /api/:accountid/puzzle/more
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| count | 需要获取的数量 |
| session | 当局的id, 从关卡题目列表中获取 |
| quality | 难度 |
3. Response: JSON
```js
[{
"id": "6080f330b9655b5c0467ee5e", // 题目id
"title": "“大丈夫为国捐躯，死而无憾！”这话是谁说的？", // 问题
"answers": [ // 可选答案
"刘铭传",
"徐骧",
"刘步蟾",
"刘永福"
],
"category": "体育-体育", // 类型
"type": 1, // 题目类型 1: 普通的文字选择题, 2: 图形, 3: 问卷式题目
"quality": 1 // 题目难度
}]
```
### 5. 获取排行榜
1. Method: POST
2. URI: /api/:accountid/puzzle/rank
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| shop | 店铺id |
| level | 关卡id, 挑战模式下, 传挑战的id, 店铺挑战总榜: 挑战id_total, 店铺挑战分桌榜: 挑战id_桌号 |
| mode | 游戏类型, 0: 单人, 1: 多人, 2: 挑战 |
| skip | 数据开始的偏移值, 从0开始, 默认0 |
| limit | 每次返回的数量条数, 默认10 |
3. Response: JSON
```js
{
userRank: 1, //当前帐号的排名
rankList: [
[
'account id', 帐号id
'score', 分数
'nickname', 昵称(暂无)
'avatar' 头像
]
],
rankTotal: 99 排行榜总人数
}
```
### 6. 获取测验题目列表
1. Method: POST
2. URI: /api/:accountid/exam/list
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| shop | 店铺id, 比如 607ff59d4a4e16687a3b7079 |
| eid | 测验id, 比如 609e13eeccc78154ac683583 |
| delay | 每题需要增加的延迟时间, 单位秒 |
3. Response: JSON
```js
{
session: "6080f330b9655b5c0467ee5a", // 当前局的id,提交答案时必须上报该字段
timeone: 10, // 每题最多回答时间
records: [{
"id": "6080f330b9655b5c0467ee5e", // 题目id
"title": "“大丈夫为国捐躯，死而无憾！”这话是谁说的？", // 问题
"answers": [ // 可选答案
"刘铭传",
"徐骧",
"刘步蟾",
"刘永福"
],
"category": "体育-体育", // 类型
"type": 1, // 题目类型 1: 普通的文字选择题, 2: 图形, 3: 问卷式题目
"quality": 1 // 题目难度
}]
}
```
### 7. 上报测验题目答案
1. Method: POST
2. URI: /api/:accountid/exam/answer
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| id | 题目id |
| session | 当局的id, 从关卡题目列表中获取 |
| answer | 回答的选项 |
| type | 回答类型, 0: 正常, 1: 超时 |
3. Response: JSON
```js
{
result: 1, //答题结果 1: 正确, 0 : 错误
gameResult: 0, // 当前局游戏结果 0: 未完成, -1: 失败, 1: 胜利
overtime: 0, // 当前回答是否超时 0: 未超时, 1: 超时
answer: '正确答案',
over: 0.1222, // 超越玩家值, 显示时x100
"stats": { // 当局的状态
"1111": {
"answer": {// 每一题的结果, key为题目的id, 值为answer在答案中的index值, 0为正确值, -1为超时, 其他都为错误
"608a3d15e678843dd443fa53": 0,
},
"total": 2, // 总答题数量
"rightCount": 1, // 答对的数量
"errorCount": 1, // 答错的数量
"comboCount": 0, // 当前连续答对的数量
"maxCombo": 1, // 当局连续答对的最大数量
"score": 10, // 当前得分
"star": 1, // 当局胜利后获得的星星
"timeLeft": 1, // 当局使用时间
"gameResult": 0, // 当局的游戏结果, 单人的话和上一层gameResult相同
"timeLast": 1620973155307 //上次回答时间
}
},
"rewards": [{
coupon: '优惠券的id',
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
ids: ['获取记录的短id'],
rewardType: 0 //奖励类型 0: 优惠券 1: 抽奖券
}]
}
```
### 8. 获取店铺信息
1. Method: POST
2. URI: /api/:accountid/shop
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
3. Response: JSON
```js
{
"id": "607ff59d4a4e16687a3b7079", // 店铺id
"numid": 1002, // 店铺的数字编号
"name": "一品漫城", // 店铺名
"area": "上海市-上海市-闵行区", // 区域
"local": 0, // 是否使用本地数据, 0: 否, 1: 是
"logo": "https://resource.kingsome.cn/game607fd53cb40504740fdccb13.png", // 店铺logo
"exams": [{ // 店铺测验信息
"id": "609e13eeccc78154ac683583", //id
"name": "第一期测试", // 测验
"desc": "简介",
"icon": "", // 相关icon
"banner": "", // 介绍大图
"beginTime": 121212121, // 开始时间
"endTime": 12312312312 // 结束时间
}],
"activity": { // 活动信息
"id": "608bdf61cecfcc2f45247663", // 活动id
"name": "第一个活动", // 活动名
"desc": "", // 活动简介
"icon": "", // 活动相关icon
"banner": "", // 活动介绍大图
"curren": 1621008800000 // 当前正在进行的活动开始时间, 没有该字段或undefined的话, 说明没有当前进行中的活动
"next": 1621008900000 // 下一个活动开始时间, 没有该字段或undefined的话, 说明没有即将开始的活动
},
"gameCfg": {
"game_main_pic": "主页正中间图片",
"bg_item_icon": "背景图案",
"game_single_btn": "主页上单人赛按钮文字",
"game_multi_btn": "主页上多人赛按钮名字",
"default_share_pic":"默认分享图",
"default_share_txt": "默认分享语",
"default_desc_txt": "配置的介绍文字",
"music_bg": "后台配置的背景音乐cdn地址"
}
}
```
### 9. 用户统计信息
1. Method: POST
2. URI: /api/:accountid/stats
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
3. Response: JSON
```js
{
"map": [ //能力地图数据
{
"id": 0,
"name": "知识面", // 显示的文字
"score": 6, // 分值
"max": 20 // 该项最大分值
},
{
"id": 1,
"name": "知识深度",
"score": 11,
"max": 20
},
{
"id": 2,
"name": "反应能力",
"score": 15,
"max": 20
},
{
"id": 3,
"name": "毅力",
"score": 14,
"max": 20
},
{
"id": 4,
"name": "其他",
"score": 2,
"max": 20
}
],
"rightCount": 100, // 总的答对的题目数量
"errorCount": 100, // 总的答错的题目数量
"singleCount": 20, // 单人模式参与局数
"singleWin": 15, // 单人模式胜利局数
"singleLose": 5, // 单人模式失败局数
"activityCount": 20, // 参与活动数量
"examCount": 21 // 参与挑战数量
}
```
### 10. 用户信息上报
1. Method: POST
2. URI: /api/:accountid/login
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| nickname | 昵称 |
| avatar | 头像 |
| mobile | 手机号 |
| sex | 性别 |
| country | 国家 |
| province | 省份 |
| city | 城市 |
| shop | 店铺id |
3. Response: JSON
```js
{
token: '1231231aasa'
}
```
### 11. 用户券列表
1. Method: POST
2. URI: /api/:accountid/tickets
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id, 不传的话, 获取所有 |
3. Response: JSON
```js
[{
id: '记录id',
shop: '店铺id',
shopName: '店铺名',
coupon: '券id',
couponName: '券名',
couponUrl: '券图片url',
status: '状态', //0: 未使用 , 1: 已使用 2: 赠送中, 3: 已赠送,9: 已过期
expire: 0 // 过期时间, 0 为永不过期
}]
```
### 12. 用户信息
1. Method: POST
2. URI: /api/:accountid/info
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
3. Response: JSON
```js
{
tocket_lottery: 10, //用户在当前店铺拥有的抽奖券数量
}
```
### 13. 抽奖转盘信息
1. Method: POST
2. URI: /api/:accountid/lottery_info
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
3. Response: JSON
```js
[ // 奖励列表
{
coupon: '优惠券的id', // 如果该值为 empty, 说明是留空的,
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
rewardType: 0, // 0: 优惠券, 1: 抽奖券
}
]
```
### 14. 抽奖
1. Method: POST
2. URI: /api/:accountid/lottery
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
3. Response: JSON
```js
[{ // 本次请求新获得的物品
coupon: '优惠券的id',
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
rewardType: 0, // 0: 优惠券, 1: 抽奖券
expire: 0 // 过期时间, 0表示永不过期
}]
```
### 15. 邀请奖励信息
1. Method: POST
2. URI: /api/:accountid/share_rewards
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
3. Response: JSON
```js
{
num: 10, // 已邀请人数
newget: [{ // 本次请求新获得的物品
coupon: '优惠券的id',
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
rewardType: 0, // 0: 优惠券, 1: 抽奖券
expire: 0 // 过期时间, 0表示永不过期
}]
rewards: [ // 奖励列表
{
coupon: '优惠券的id',
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
rewardType: 0, // 0: 优惠券, 1: 抽奖券
score: 100, // 获得条件
geted: 0, // 是否已获得, 0: 未获得, 1: 已获得
}
]
}
```
### 16. 挑战奖励详情
1. Method: POST
2. URI: /api/:accountid/exam_rewards
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
| eid | 挑战活动id |
3. Response: JSON
```js
[ // 奖励列表
{
coupon: '优惠券的id',
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
type: 0, //类型 0: 单局能获得的奖励 1: 累计榜积分奖励, 2: 累计榜排名奖励
rewardType: 0, // 0: 优惠券, 1: 抽奖券
score: 100, // 获得条件,type=2的类型, score是排名, 其他类型为积分
scoreEnd: 150, // 只有type=2的时候才需要考虑该值, 表示从第几名到第几名能获得奖励
geted: 0, // 是否已获得, 0: 未获得, 1: 已获得
}
]
```
### 17. 邮件列表
1. Method: POST
2. URI: /api/:accountid/mails
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
3. Response: JSON
```js
[{
_id: '邮件id',
title: '邮件标题',
content: 1: '邮件正文'
status: 0, // 邮件状态: 0: 未读 1: 已读, 2: 已领取附件
items: [{
itemId: '物品的id'
name: '物品名',
count: 1 // 数量
}]
}]
```
### 18. 设置邮件已读
1. Method: POST
2. URI: /api/:accountid/mail/read
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| ids | 邮件id数组 |
### 19. 领取邮件附件
1. Method: POST
2. URI: /api/:accountid/mail/attachment
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| ids | 邮件id数组 |
3. Response: JSON
```js
[{ // 获得的物品列表
coupon: '优惠券的id',
name: '优惠券名',
count: 1, //数量
couponUrl: '优惠券详情图的url',
rewardType: 0, // 0: 优惠券, 1: 抽奖券
expire: 0 // 过期时间, 0表示永不过期
}]
```
### 20. 删除邮件
1. Method: POST
2. URI: /api/:accountid/mail/delete
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| ids | 邮件id数组 |
### 21. 显示正确答案
1. Method: POST
2. URI: /api/:accountId/puzzle/help
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| id | 题目id |
| session | 当局的id, 从关卡题目列表中获取 |
3. Response: JSON
```js
{
answer: '1123123'
}
```
> 说明, 这里获取的answer是使用 当前比赛session_当前题目的id_答案_jcfw中的sessionid, 计算md5
### 22. 公告列表
1. Method: POST
2. URI: /api/:accountId/announces
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| sid | 店铺id |
| ids | 已读的公告id数组 |
3. Response: JSON
```js
{
"id": "60c1d800646792f5f3764e93", // 公告id
"content": "22", // 公告内容, 最好用ubb富文本来显示
"endTime": 1623921267010, // 公告过期时间
"sendTime": 1623316467010, // 公告发送时间
"title": "111", // 公告标题
"type": 2 // 公告类型 0: 普通 1: 店铺群发 2: 全体
}
```
### 23. 开始分享优惠券
1. Method: POST
2. URI: /api/:accountId/coupon/begin_share
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| id | 优惠券的短id |
3. Response: JSON
```js
{}
```
### 24. 领取分享的优惠券
1. Method: POST
2. URI: /api/:accountId/coupon/receive_coupon
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| id | 优惠券的短id |
| shop | 优惠券的所属店铺 |
| sender | 分享者的accountId |
3. Response: JSON
```js
{
id: '记录id',
shop: '店铺id',
shopName: '店铺名',
coupon: '券id',
couponName: '券名',
couponUrl: '券图片url',
status: '状态', //0: 未使用 , 1: 已使用 9: 已过期
expire: 0 // 过期时间, 0表示永不过期
}
```
### 25. 优惠券详情
1. Method: POST
2. URI: /api/:accountId/coupon/info
| 字段 | 说明 |
| -------- | -------------------------------------- |
| accountid | 优惠券拥有者的帐号id |
> POST参数
| 字段 | 说明 |
| -------- | -------------------------------------- |
| id | 优惠券的短id |
| shop | 优惠券的所属店铺 |
3. Response: JSON
```js
{
id: '记录id',
shop: '店铺id',
shopName: '店铺名',
coupon: '券id',
couponName: '券名',
couponUrl: '券图片url',
status: '状态', //0: 未使用 , 1: 已使用 2: 赠送中, 3: 已赠送(已被领取) ,9: 已过期
expire: 0, // 过期时间, 0表示永不过期
user: '拥有者的昵称',
userAvatar: '拥有者的头像'
}
```