跳转至

游戏通知

本指南介绍游戏公告查询 API 的使用方法。

调用 API 前，您需要先在 Hive 控制台中注册公告，以便在游戏中显示。

概述

游戏公告查询 API 通过服务器间通信从游戏中直接调用，根据查询方式支持以下两种接口。

  • 查询全部公告：一次性查询特定游戏（game_index）的所有公告列表。
  • 分页查询公告：以分页（Pagination）方式查询特定游戏（game_index）的公告列表。

调用 API 时，请求头 Authorization 中必须包含认证令牌（Hive 认证密钥）。响应中包含公告基本信息、各语言详细信息、游戏服务器 ID 列表和国家代码列表。

仅当满足以下所有条件时，公告才会出现在响应结果中：

  • status = 1：激活状态
  • start_time <= 当前时间：当前时间在显示开始时间之后
  • end_time >= 当前时间：当前时间在显示结束时间之前
Note

所有时间均以 KST (UTC+9) 为基准。

通用响应规范

说明所有游戏公告查询 API 调用时通用的响应示例和响应代码。

成功响应示例

{
  "result_code": 0,
  "result_msg": "Success",
  "data": { ... }
}

错误响应示例

{
  "result_code": 1100,
  "result_msg": "Unknown error"
}

响应代码

HTTP 状态码 代码 消息 说明
200 0 Success 处理成功
500 1100 Unknown error 原因不明错误
500 1101 Internal server error 服务器内部错误
400 1201 详细消息
(例: Missing required parameter: game_index)		 请求格式错误
400 1202 详细消息
(例: `game_index` must be a positive integer)		 参数值错误
401 1203 Unauthorized 权限错误
405 1204 Method not allowed HTTP 请求方法错误


查询全部公告

返回特定游戏（game_index）的完整公告列表。

请求信息

项目 内容
正式环境 URL https://social-api.qpyou.cn/games/{game_index}/notices
沙盒 URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices
HTTP Method GET
Response Format JSON

请求数据

请求头

字段 类型 必填 说明 备注
Authorization string Y Bearer 令牌
(Hive 认证密钥)		 AppCenter > 项目管理 > 游戏详情 > 基本信息 > Hive 认证密钥

请求头示例

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

路径参数

字段 类型 必填 说明
game_index int Y 游戏索引（正整数）

请求体

无（GET 请求）

请求示例

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

响应数据

响应体

字段 类型 说明
result_code int 响应结果代码
result_msg string 结果消息
data object 响应数据
ㄴ list array 公告列表（公告基本信息对象数组，无结果时返回 []）

响应示例

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

分页查询公告

以分页方式返回特定游戏（game_index）的公告列表。

当查询全部公告的查询参数中包含 page 或 per_page 时，将切换为分页查询模式。

请求信息

项目 内容
正式环境 URL https://social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
沙盒 URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
HTTP Method GET
Response Format JSON

请求数据

请求头

字段 类型 必填 说明 备注
Authorization string Y Bearer 令牌
(Hive 认证密钥)		 AppCenter > 项目管理 > 游戏详情 > 基本信息 > Hive 认证密钥

请求头示例

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

路径参数

字段 类型 必填 说明
game_index int Y 游戏索引（正整数）

查询参数

Note

如果 page 或 per_page 不是正整数，将使用默认值。

参数 类型 必填 默认值 说明
page int N 1 页码（从 1 开始）
per_page int N 20 每页条数

请求体

无（GET 请求）

请求示例

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices?page=1&per_page=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

响应数据

响应体

字段 类型 说明
result_code int 响应结果代码
result_msg string 结果消息
data object 响应数据
ㄴ pagination object 分页元数据
  ㄴ page int 当前页码
  ㄴ per_page int 每页条数
  ㄴ total_count int 总数据条数
  ㄴ total_pages int 总页数（ceil(total_count / per_page)；total_count = 0 时为 0）
ㄴ list array 公告列表（公告基本信息对象数组，无结果时返回 []）

响应示例

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_count": 50,
      "total_pages": 3
    },
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

响应数据详细说明

公告基本信息

字段 类型 说明
notice_id int 公告唯一 ID
status int 状态（1：激活；仅返回激活状态的公告）
type string 公告类型（参见 type 代码）
view_count int 浏览次数
registrant string 注册人
top_placed int|null 置顶（1 以上：置顶，null：不置顶）
start_time string 显示开始时间（yyyy-MM-dd HH:mm:ss，KST）
end_time string 显示结束时间（yyyy-MM-dd HH:mm:ss，KST）
company_index int 公司索引
game_index int 游戏索引
country_expose_type string|null 国家显示类型（参见 country_expose_type 代码；默认值：null）
details object 各语言详细信息（参见 details）
game_servers array 游戏服务器 ID 列表（参见 game_servers）
country_codes array 国家代码列表（参见 country_codes）

type 代码

代码 说明
I 信息
C 维护
U 更新
N 公告
A 通知
E 活动
D 错误

country_expose_type 代码

代码 说明
null 无限制（在所有国家显示）
W 白名单（仅在 country_codes 中包含的国家显示）
B 黑名单（对 country_codes 中包含的国家屏蔽）

details

details 是以语言代码为键的对象。仅包含公告中已注册的语言；若无详细信息则返回空对象（{}）。

字段 类型 说明
game_name string 游戏名称
title string 公告标题
content string 公告内容
crop_image string 裁剪图片 URL

支持的语言代码

代码 语言
ko 韩语
en 英语
ja 日语
zh-hans 中文（简体）
zh-hant 中文（繁体）
de 德语
fr 法语
ru 俄语
es 西班牙语
pt 葡萄牙语
id 印度尼西亚语
th 泰语
vi 越南语
it 意大利语
tr 土耳其语
ar 阿拉伯语

game_servers

  • 游戏服务器 ID 列表。无数据时返回空数组（[]）。
  • 示例：["server1", "server2", "server3"]

country_codes

  • 国家代码列表。无数据时返回空数组（[]）。
  • 示例：["KR", "US", "JP"]
  • 参考：ISO 3166 标准