outsource/HaniBlindBox

Fork 0

zpc 1dc9a869df 文档

2026-01-01 21:01:50 +08:00

18 KiB

Raw Blame History

抽奖盲盒系统API接口文档

1. 接口概览

基础信息

基础URL: https://api.example.com
API版本: v1
数据格式: JSON
字符编码: UTF-8
认证方式: JWT Token

通用响应格式

{
    "code": 200,
    "msg": "success",
    "data": {},
    "timestamp": 1640995200
}

状态码说明

状态码	说明
200	请求成功
400	请求参数错误
401	未授权访问
403	权限不足
404	资源不存在
500	服务器内部错误

2. 用户认证接口

2.1 发送验证码

POST /api/user/sendCode

请求参数:

{
    "phone": "13800138000",
    "type": 1
}

参数说明:

参数	类型	必填	说明
phone	string	是	手机号
type	int	是	类型：1-登录注册

响应示例:

{
    "code": 200,
    "msg": "验证码发送成功",
    "data": {
        "expire_time": 300
    }
}

2.2 用户登录/注册

POST /api/user/login

请求参数:

{
    "phone": "13800138000",
    "code": "123456",
    "openid": "wx_openid_123"
}

响应示例:

{
    "code": 200,
    "msg": "登录成功",
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "user_info": {
            "id": 1001,
            "phone": "13800138000",
            "nickname": "用户昵称",
            "avatar": "头像URL",
            "money": "100.00",
            "integral": "50.00",
            "level": 1
        }
    }
}

2.3 获取用户信息

GET /api/user/info

请求头:

Authorization: Bearer {token}

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1001,
        "phone": "138****8000",
        "nickname": "用户昵称",
        "avatar": "头像URL",
        "money": "100.00",
        "integral": "50.00",
        "money2": "20.00",
        "level": 1,
        "draw_num": 5
    }
}

3. 商品相关接口

3.1 获取商品分类

GET /api/goods/category

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "title": "手办模型",
            "sort": 1
        },
        {
            "id": 2,
            "title": "数码产品",
            "sort": 2
        }
    ]
}

3.2 获取商品列表

GET /api/goods/list

请求参数:

参数	类型	必填	说明
category_id	int	否	分类ID
type	int	否	商品类型
page	int	否	页码，默认1
limit	int	否	每页数量，默认20
keyword	string	否	搜索关键词

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 1001,
                "title": "精美手办盲盒",
                "imgurl": "商品图片URL",
                "price": "29.90",
                "type": 1,
                "type_name": "一番赏",
                "stock": 100,
                "sale_stock": 50,
                "status": 1,
                "prize_num": 1,
                "show_price": "29.9元/抽"
            }
        ],
        "total": 100,
        "page": 1,
        "limit": 20
    }
}

3.3 获取商品详情

GET /api/goods/detail/{id}

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1001,
        "title": "精美手办盲盒",
        "imgurl": "商品封面图",
        "imgurl_detail": "商品详情图",
        "price": "29.90",
        "type": 1,
        "type_name": "一番赏",
        "stock": 100,
        "sale_stock": 50,
        "prize_num": 1,
        "goods_describe": "商品描述",
        "prize_list": [
            {
                "id": 2001,
                "title": "限定手办A",
                "imgurl": "奖品图片",
                "price": "299.00",
                "money": "150.00",
                "real_pro": "0.05000",
                "goods_type": 1,
                "prize_code": "A001"
            }
        ]
    }
}

3.4 获取商品奖品列表

GET /api/goods/prizeList/{goods_id}

请求参数:

参数	类型	必填	说明
num	int	否	第几套，默认0

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 2001,
            "title": "限定手办A",
            "imgurl": "奖品图片",
            "price": "299.00",
            "money": "150.00",
            "real_pro": "0.05000",
            "goods_type": 1,
            "stock": 10,
            "surplus_stock": 8,
            "prize_code": "A001",
            "rank": 1
        }
    ]
}

4. 订单相关接口

4.1 创建订单

POST /api/order/create

请求参数:

{
    "goods_id": 1001,
    "num": 0,
    "prize_num": 1,
    "coupon_id": 0,
    "use_money": "0.00",
    "use_integral": "0.00",
    "use_draw": 0
}

参数说明:

参数	类型	必填	说明
goods_id	int	是	商品ID
num	int	是	第几套
prize_num	int	是	抽奖数量
coupon_id	int	否	优惠券ID
use_money	decimal	否	使用余额
use_integral	decimal	否	使用积分
use_draw	int	否	使用抽奖券

响应示例:

{
    "code": 200,
    "msg": "订单创建成功",
    "data": {
        "order_id": 10001,
        "order_num": "202401010001",
        "order_total": "29.90",
        "price": "29.90",
        "goods_info": {
            "id": 1001,
            "title": "精美手办盲盒",
            "imgurl": "商品图片"
        }
    }
}

4.2 获取支付参数

POST /api/order/pay

请求参数:

{
    "order_id": 10001,
    "pay_type": 1
}

参数说明:

参数	类型	必填	说明
order_id	int	是	订单ID
pay_type	int	是	支付方式：1-微信，2-支付宝

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "pay_params": {
            "appId": "wx123456789",
            "timeStamp": "1640995200",
            "nonceStr": "abc123",
            "package": "prepay_id=wx123456789",
            "signType": "RSA",
            "paySign": "signature"
        }
    }
}

4.3 获取订单列表

GET /api/order/list

请求参数:

参数	类型	必填	说明
status	int	否	订单状态：0-未支付，1-已支付
page	int	否	页码
limit	int	否	每页数量

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 10001,
                "order_num": "202401010001",
                "goods_title": "精美手办盲盒",
                "goods_imgurl": "商品图片",
                "order_total": "29.90",
                "price": "29.90",
                "prize_num": 1,
                "status": 1,
                "addtime": 1640995200,
                "pay_time": 1640995300
            }
        ],
        "total": 50,
        "page": 1,
        "limit": 20
    }
}

5. 抽奖相关接口

5.1 获取中奖记录

GET /api/prize/list

请求参数:

参数	类型	必填	说明
status	int	否	状态：0-待选择，1-回收，2-发货，3-集市
page	int	否	页码
limit	int	否	每页数量

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 20001,
                "order_id": 10001,
                "goodslist_title": "限定手办A",
                "goodslist_imgurl": "奖品图片",
                "goodslist_price": "299.00",
                "goodslist_money": "150.00",
                "goodslist_type": 1,
                "status": 0,
                "addtime": 1640995300,
                "prize_code": "A001",
                "luck_no": 1
            }
        ],
        "total": 20,
        "page": 1,
        "limit": 20
    }
}

5.2 选择奖品处理方式

POST /api/prize/choose

请求参数:

{
    "order_list_ids": [20001, 20002],
    "type": 1
}

参数说明:

参数	类型	必填	说明
order_list_ids	array	是	中奖记录ID数组
type	int	是	处理方式：1-回收，2-发货，3-集市

响应示例:

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "recovery_num": "R202401010001",
        "total_money": "300.00"
    }
}

6. 集市相关接口

6.1 获取集市商品列表

GET /api/market/list

请求参数:

参数	类型	必填	说明
keyword	string	否	搜索关键词
min_price	decimal	否	最低价格
max_price	decimal	否	最高价格
page	int	否	页码
limit	int	否	每页数量

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 30001,
                "order_num": "M202401010001",
                "price": "280.00",
                "stock": 1,
                "status": 0,
                "addtime": 1640995400,
                "goods_info": [
                    {
                        "title": "限定手办A",
                        "imgurl": "奖品图片",
                        "price": "299.00"
                    }
                ]
            }
        ],
        "total": 100,
        "page": 1,
        "limit": 20
    }
}

6.2 发布集市商品

POST /api/market/publish

请求参数:

{
    "order_list_ids": [20001],
    "price": "280.00"
}

响应示例:

{
    "code": 200,
    "msg": "发布成功",
    "data": {
        "market_id": 30001,
        "order_num": "M202401010001"
    }
}

6.3 购买集市商品

POST /api/market/buy

请求参数:

{
    "market_id": 30001,
    "pay_type": 1
}

响应示例:

{
    "code": 200,
    "msg": "购买成功",
    "data": {
        "order_id": 40001,
        "pay_params": {
            "appId": "wx123456789",
            "timeStamp": "1640995200",
            "nonceStr": "abc123",
            "package": "prepay_id=wx123456789",
            "signType": "RSA",
            "paySign": "signature"
        }
    }
}

7. 财务相关接口

7.1 获取资金明细

GET /api/finance/moneyLog

请求参数:

参数	类型	必填	说明
type	int	否	类型：1-充值，2-消费，3-回收等
page	int	否	页码
limit	int	否	每页数量

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 50001,
                "change_money": "+150.00",
                "money": "250.00",
                "type": 4,
                "type_name": "背包回收",
                "content": "回收奖品获得",
                "addtime": 1640995500
            }
        ],
        "total": 50,
        "page": 1,
        "limit": 20
    }
}

7.2 获取积分明细

GET /api/finance/integralLog

响应格式同资金明细

7.3 获取优惠券列表

GET /api/finance/couponList

请求参数:

参数	类型	必填	说明
status	int	否	状态：0-未使用，1-已使用，2-已过期

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 60001,
            "title": "新人专享券",
            "price": "5.00",
            "man_price": "30.00",
            "end_time": 1641081600,
            "status": 0,
            "state": 0
        }
    ]
}

8. 发货相关接口

8.1 创建发货订单

POST /api/delivery/create

请求参数:

{
    "order_list_ids": [20001, 20002],
    "name": "张三",
    "mobile": "13800138000",
    "address": "北京市朝阳区xxx街道xxx号",
    "message": "请小心轻放"
}

响应示例:

{
    "code": 200,
    "msg": "发货订单创建成功",
    "data": {
        "send_id": 70001,
        "send_num": "S202401010001",
        "freight": "10.00",
        "total_price": "10.00"
    }
}

8.2 获取发货订单列表

GET /api/delivery/list

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 70001,
                "send_num": "S202401010001",
                "freight": "10.00",
                "status": 1,
                "count": 2,
                "name": "张三",
                "mobile": "138****8000",
                "address": "北京市朝阳区xxx街道xxx号",
                "courier_number": "SF1234567890",
                "courier_name": "顺丰速运",
                "addtime": 1640995600,
                "send_time": 1640995700
            }
        ]
    }
}

8.3 获取物流信息

GET /api/delivery/track/{send_id}

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "courier_number": "SF1234567890",
        "courier_name": "顺丰速运",
        "delivery_status": 3,
        "delivery_list": [
            {
                "time": "2024-01-01 10:00:00",
                "context": "快件已发出"
            },
            {
                "time": "2024-01-01 15:30:00",
                "context": "快件已到达中转站"
            }
        ]
    }
}

9. 系统配置接口

9.1 获取系统配置

GET /api/system/config

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": {
        "app_name": "抽奖盲盒",
        "app_version": "1.0.0",
        "customer_service": "400-123-4567",
        "agreement_url": "https://example.com/agreement",
        "privacy_url": "https://example.com/privacy"
    }
}

9.2 获取轮播图

GET /api/system/banner

请求参数:

参数	类型	必填	说明
type	int	否	类型：1-首页轮播，2-抽卡机轮播

响应示例:

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "imgurl": "轮播图URL",
            "url": "跳转链接",
            "ttype": 2,
            "goods_id": 1001
        }
    ]
}

10. 错误码说明

错误码	说明
10001	参数错误
10002	用户不存在
10003	验证码错误
10004	验证码已过期
20001	商品不存在
20002	商品已下架
20003	商品库存不足
30001	订单不存在
30002	订单状态错误
30003	余额不足
40001	支付失败
40002	支付超时
50001	抽奖失败
50002	奖品库存不足

11. 接口调用示例

JavaScript示例

// 用户登录
const login = async (phone, code) => {
    const response = await fetch('/api/user/login', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            phone: phone,
            code: code
        })
    });
    
    const result = await response.json();
    if (result.code === 200) {
        localStorage.setItem('token', result.data.token);
        return result.data;
    } else {
        throw new Error(result.msg);
    }
};

// 获取商品列表
const getGoodsList = async (params = {}) => {
    const query = new URLSearchParams(params).toString();
    const response = await fetch(`/api/goods/list?${query}`, {
        headers: {
            'Authorization': `Bearer ${localStorage.getItem('token')}`
        }
    });
    
    return await response.json();
};

// 创建订单
const createOrder = async (orderData) => {
    const response = await fetch('/api/order/create', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${localStorage.getItem('token')}`
        },
        body: JSON.stringify(orderData)
    });
    
    return await response.json();
};

PHP示例

<?php
class ApiClient {
    private $baseUrl;
    private $token;
    
    public function __construct($baseUrl) {
        $this->baseUrl = $baseUrl;
    }
    
    public function setToken($token) {
        $this->token = $token;
    }
    
    public function request($method, $endpoint, $data = null) {
        $url = $this->baseUrl . $endpoint;
        $headers = ['Content-Type: application/json'];
        
        if ($this->token) {
            $headers[] = 'Authorization: Bearer ' . $this->token;
        }
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            if ($data) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            }
        }
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    public function login($phone, $code) {
        return $this->request('POST', '/api/user/login', [
            'phone' => $phone,
            'code' => $code
        ]);
    }
    
    public function getGoodsList($params = []) {
        $query = http_build_query($params);
        return $this->request('GET', '/api/goods/list?' . $query);
    }
}

// 使用示例
$client = new ApiClient('https://api.example.com');
$result = $client->login('13800138000', '123456');

if ($result['code'] === 200) {
    $client->setToken($result['data']['token']);
    $goodsList = $client->getGoodsList(['type' => 1, 'page' => 1]);
}
?>

这份API文档涵盖了抽奖盲盒系统的主要功能接口，包括用户认证、商品管理、订单处理、抽奖机制、集市交易、财务管理等核心业务模块。每个接口都提供了详细的参数说明和响应示例，便于前端开发和第三方集成。

18 KiB Raw Blame History Unescape Escape

抽奖盲盒系统API接口文档

1. 接口概览

基础信息

通用响应格式

状态码说明

2. 用户认证接口

2.1 发送验证码

2.2 用户登录/注册

2.3 获取用户信息

3. 商品相关接口

3.1 获取商品分类

3.2 获取商品列表

3.3 获取商品详情

3.4 获取商品奖品列表

4. 订单相关接口

4.1 创建订单

4.2 获取支付参数

4.3 获取订单列表

5. 抽奖相关接口

5.1 获取中奖记录

5.2 选择奖品处理方式

6. 集市相关接口

6.1 获取集市商品列表

6.2 发布集市商品

6.3 购买集市商品

7. 财务相关接口

7.1 获取资金明细

7.2 获取积分明细

7.3 获取优惠券列表

8. 发货相关接口

8.1 创建发货订单

8.2 获取发货订单列表

8.3 获取物流信息

9. 系统配置接口

9.1 获取系统配置

9.2 获取轮播图

10. 错误码说明

11. 接口调用示例

JavaScript示例

PHP示例

18 KiB

Raw Blame History