小游戏服务平台 - 接口详细设计（入参/出参）
1. 用户服务
1.1 登录接口
POST /api/v1/auth/login
入参
1
2
3
4
5
6
7
|
{
"login_type": "password", // password / oauth
"username": "test_user", // 当 login_type=password
"password": "123456",
"oauth_provider": "wechat", // 当 login_type=oauth
"oauth_token": "wx_xxx"
}
|
出参
1
2
3
4
5
6
7
8
9
10
|
{
"code": 0,
"message": "success",
"data": {
"user_id": "100928374923",
"access_token": "eyJhbGciOiJIUzI1...",
"refresh_token": "eyJhbGciOiJIUzI1...",
"expires_in": 1800
}
}
|
1.2 刷新 Token
POST /api/v1/auth/refresh
入参
1
2
3
|
{
"refresh_token": "eyJhbGciOiJIUzI1..."
}
|
出参
1
2
3
4
5
6
7
8
|
{
"code": 0,
"message": "success",
"data": {
"access_token": "new_token_xxx",
"expires_in": 1800
}
}
|
1.3 获取用户信息
GET /api/v1/users/{user_id}
出参
1
2
3
4
5
6
7
8
9
10
11
12
13
|
{
"code": 0,
"message": "success",
"data": {
"user_id": "100928374923",
"username": "test_user",
"age": 22,
"gender": 1,
"region": "Beijing",
"status": 1,
"created_at": "2025-09-26T10:00:00Z"
}
}
|
2. 游戏服务
2.1 上传游戏
POST /api/v1/games/upload
入参
multipart/form-data
file: game.zip
metadata: {
"name": "Jump Game",
"description": "A casual jump game",
"version": "1.0.0",
"tags": ["casual","jump"]
}
出参
1
2
3
4
5
6
7
8
|
{
"code": 0,
"message": "upload success",
"data": {
"game_id": "200123891237",
"status": "pending_review"
}
}
|
2.2 获取游戏详情
GET /api/v1/games/{id}
出参
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
{
"code": 0,
"message": "success",
"data": {
"game_id": "200123891237",
"name": "Jump Game",
"description": "A casual jump game",
"version": "1.0.0",
"status": "online",
"cdn_url": "https://cdn.xxx.com/games/200123891237/v1/index.html",
"tags": ["casual","jump"],
"created_at": "2025-09-26T12:00:00Z"
}
}
|
2.3 搜索游戏
GET /api/v1/games?tag=casual&keyword=jump&page=1&size=10
出参
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
{
"code": 0,
"message": "success",
"data": {
"total": 125,
"list": [
{
"game_id": "200123891237",
"name": "Jump Game",
"tags": ["casual","jump"],
"status": "online"
}
]
}
}
|
3. 广告服务
3.1 请求广告
GET /api/v1/ads/request?slot_id=3001&user_id=100928374923
出参
1
2
3
4
5
6
7
8
9
10
11
|
{
"code": 0,
"message": "success",
"data": {
"ad_id": "ad_789123",
"type": "reward",
"material_url": "https://cdn.xxx.com/ads/ad_789123.mp4",
"duration": 30,
"click_url": "https://track.xxx.com/click?ad_id=ad_789123&user_id=100928374923"
}
}
|
3.2 上报广告事件
POST /api/v1/ads/report
入参
1
2
3
4
5
6
7
|
{
"user_id": "100928374923",
"game_id": "200123891237",
"ad_id": "ad_789123",
"event_type": "click",
"ts": "2025-09-26T12:00:00Z"
}
|
出参
1
2
3
4
|
{
"code": 0,
"message": "event logged"
}
|
4. 支付服务
4.1 创建订单
POST /api/v1/payments/create
入参
1
2
3
4
5
6
7
|
{
"user_id": "100928374923",
"game_id": "200123891237",
"amount": 9.99,
"currency": "USD",
"pay_method": "wechat" // wechat / alipay / stripe / paypal
}
|
出参
1
2
3
4
5
6
7
8
9
|
{
"code": 0,
"message": "order created",
"data": {
"order_id": "500123981273",
"out_trade_no": "wx202509261200xx",
"pay_url": "https://pay.wechat.com/order/wx202509261200xx"
}
}
|
4.2 支付回调
POST /api/v1/payments/notify
入参（由支付网关推送）
1
2
3
4
5
6
|
{
"out_trade_no": "wx202509261200xx",
"status": "paid",
"transaction_id": "wx_txn_001",
"paid_at": "2025-09-26T12:01:00Z"
}
|
出参
1
2
3
4
|
{
"code": 0,
"message": "callback processed"
}
|
4.3 开发者提现
POST /api/v1/developers/withdraw
入参
1
2
3
4
5
6
7
8
9
|
{
"developer_id": "dev_1001",
"amount": 500.00,
"currency": "USD",
"account": {
"method": "paypal",
"account_id": "dev@example.com"
}
}
|
出参
1
2
3
4
5
6
7
8
|
{
"code": 0,
"message": "withdraw request submitted",
"data": {
"settlement_id": "600918237182",
"status": "pending"
}
}
|
总结
我为 用户、游戏、广告、支付 四大模块整理了接口的 详细入参/出参 JSON 格式，同时包含：
- 错误码规范（
code）
- 状态字段（status）
- 时间戳统一 ISO8601 UTC
- 幂等保障字段（如订单 out_trade_no）