抽奖API接口说明.md 9.2 KB
抽奖API接口说明
概述
本文档描述了抽奖系统的API接口，包括活动管理、抽奖操作、记录查询等功能。
接口列表
1. 获取抽奖活动列表
接口地址: /api/lottery/activityList
请求方式: GET
参数说明:
page(可选): 页码，默认1pageSize(可选): 每页数量，默认10status(可选): 活动状态，默认进行中
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": {
"list": [
{
"id": 1,
"name": "新年抽奖活动",
"description": "活动描述",
"cover_image": "/uploads/cover.jpg",
"type": 1,
"status": 2,
"start_time": 1640995200,
"end_time": 1641081600,
"lottery_type": 1,
"guide_image": "/uploads/guide.jpg",
"guide_text": "活动引导文字",
"intro_content": "活动详细介绍",
"prizes": [
{
"id": 1,
"name": "一等奖",
"type": 2,
"image": "/uploads/prize1.jpg",
"probability": 0.01
}
],
"total_participants": 100
}
],
"total": 1
}
}
2. 获取活动详情
接口地址: /api/lottery/activityDetail
请求方式: GET
参数说明:
activity_id(必填): 活动ID
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": {
"id": 1,
"name": "新年抽奖活动",
"description": "活动描述",
"cover_image": "/uploads/cover.jpg",
"type": 1,
"status": 2,
"start_time": 1640995200,
"end_time": 1641081600,
"lottery_type": 1,
"guide_image": "/uploads/guide.jpg",
"guide_text": "活动引导文字",
"intro_content": "活动详细介绍",
"prizes": [
{
"id": 1,
"name": "一等奖",
"type": 2,
"image": "/uploads/prize1.jpg",
"description": "奖品描述",
"probability": 0.01,
"total_stock": 10,
"remain_stock": 8,
"win_prompt": "恭喜中奖！",
"sort_order": 1,
"unlock_people_num": 100,
"is_unlocked": true
}
],
"total_participants": 100,
"user_chances": {
"total_chances": 10,
"used_chances": 3,
"remain_chances": 7,
"last_get_time": 1640995200,
"last_use_time": 1640995300
},
"user_draw_count": 3,
"user_win_count": 1
}
}
3. 执行抽奖
接口地址: /api/lottery/draw
请求方式: POST
参数说明:
activity_id(必填): 活动ID
返回示例:
{
"code": 1,
"msg": "抽奖成功",
"data": {
"draw_id": 123,
"is_win": true,
"prize": {
"id": 1,
"name": "一等奖",
"type": 2,
"type_text": "实物奖品",
"image": "/uploads/prize1.jpg",
"win_prompt": "恭喜中奖！"
},
"draw_time": 1640995400,
"win_record_id": 456,
"deliver_status": 0,
"exchange_code": null
}
}
4. 获取用户抽奖机会
接口地址: /api/lottery/getUserChances
请求方式: GET
参数说明:
activity_id(必填): 活动ID
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": {
"total_chances": 10,
"used_chances": 3,
"remain_chances": 7,
"last_get_time": 1640995200,
"last_use_time": 1640995300
}
}
5. 获取用户抽奖记录
接口地址: /api/lottery/getDrawRecords
请求方式: GET
参数说明:
activity_id(可选): 活动ID，不传则查询所有活动page(可选): 页码，默认1limit(可选): 每页数量，默认20
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": {
"list": [
{
"id": 123,
"activity_id": 1,
"activity_name": "新年抽奖活动",
"prize_id": 1,
"prize_name": "一等奖",
"prize_type": 2,
"prize_image": "/uploads/prize1.jpg",
"is_win": true,
"draw_time": 1640995400,
"trigger_type_text": "购买商品",
"win_record": {
"id": 456,
"deliver_status": 0,
"deliver_status_text": "待发放",
"deliver_time": null,
"exchange_code": null
}
}
],
"total": 1
}
}
6. 获取用户中奖记录
接口地址: /api/lottery/getWinRecords
请求方式: GET
参数说明:
page(可选): 页码，默认1limit(可选): 每页数量，默认20
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": {
"list": [
{
"id": 456,
"activity_id": 1,
"activity_name": "新年抽奖活动",
"prize_id": 1,
"prize_name": "一等奖",
"prize_type": 2,
"deliver_status": 0,
"deliver_status_text": "待发放",
"deliver_time": null,
"exchange_code": null,
"createtime": 1640995400,
"amount": 100.00
}
],
"total": 1
}
}
7. 设置中奖记录收货地址
接口地址: /api/lottery/setWinRecordAddress
请求方式: POST
参数说明:
win_record_id(必填): 中奖记录IDreceiver_name(必填): 收货人姓名receiver_mobile(必填): 收货人手机号receiver_address(必填): 收货地址
返回示例:
{
"code": 1,
"msg": "设置成功",
"data": null
}
8. 获取活动排行榜
接口地址: /api/lottery/getRanking
请求方式: GET
参数说明:
activity_id(必填): 活动IDpage(可选): 页码，默认1limit(可选): 每页数量，默认50
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": [
{
"rank": 1,
"user_id": 123,
"nickname": "用户昵称",
"avatar": "/uploads/avatar.jpg",
"win_count": 5
}
]
}
9. 获取奖品列表
接口地址: /api/lottery/getPrizes
请求方式: GET
参数说明:
lottery_id(可选): 活动ID，不传则查询进行中活动的奖品page(可选): 页码，默认1pageSize(可选): 每页数量，默认10type(可选): 奖品类型筛选，支持JSON数组格式
返回示例:
{
"code": 1,
"msg": "获取成功",
"data": {
"list": [
{
"id": 1,
"activity_id": 1,
"name": "一等奖",
"type": 2,
"type_text": "实物奖品",
"image": "/uploads/prize1.jpg",
"description": "奖品描述",
"probability": 0.01,
"probability_percent": 1.00,
"total_stock": 10,
"remain_stock": 8,
"stock_percent": 80.00,
"win_prompt": "恭喜中奖！",
"sort_order": 1,
"unlock_people_num": 100,
"is_unlocked": true,
"activity_name": "新年抽奖活动",
"activity_status": 2,
"createtime": 1640995200
}
],
"total": 1,
"current_page": 1,
"last_page": 1,
"per_page": 10
}
}
奖品类型说明
| 类型值 | 类型名称 | 说明 |
|---|---|---|
| 1 | 未中奖 | 未中奖类型 |
| 2 | 实物奖品 | 实物商品 |
| 3 | 积分 | 用户积分 |
| 4 | 余额 | 用户余额 |
| 5 | 优惠券 | 优惠券 |
| 6 | 红包 | 红包 |
| 7 | 兑换码 | 兑换码 |
| 8 | 商城奖品 | 商城商品 |
活动状态说明
| 状态值 | 状态名称 | 说明 |
|---|---|---|
| 1 | 未开始 | 活动未开始 |
| 2 | 进行中 | 活动进行中 |
| 3 | 已结束 | 活动已结束 |
| 4 | 已取消 | 活动已取消 |
| 5 | 已暂停 | 活动已暂停 |
发放状态说明
| 状态值 | 状态名称 | 说明 |
|---|---|---|
| 0 | 待发放 | 奖品待发放 |
| 1 | 已发放 | 奖品已发放 |
| 2 | 发放失败 | 奖品发放失败 |
| 3 | 已取消 | 奖品发放已取消 |
错误码说明
| 错误码 | 说明 |
|---|---|
| 1 | 成功 |
| 0 | 失败 |
注意事项
- 所有需要登录的接口都需要在请求头中携带用户token
- 分页参数page从1开始
- 时间戳使用秒级时间戳
- 图片路径为相对路径，需要拼接域名
- 概率值为0-1之间的小数
- 库存数量为整数
- 金额单位为元，保留两位小数