游戏通知

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

准备工作¶

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

工作方式¶

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

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

Note

应用公告查询 API 使用 JWT 认证方式。

调用 API 时，请求头 X-Access-Token 中必须包含认证令牌（JWT Access Token，请参见 OAuth Token 发行）。响应中包含公告基本信息、各语言详细信息、应用服务器 ID 列表和国家代码列表。

只有响应值满足以下条件才能查看公告。

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

Note

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

通用响应规范¶

说明调用应用公告查询 API 时返回的成功及失败响应数据示例和状态代码。

成功响应示例¶

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

错误响应示例¶

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

JWT 验证失败示例¶

{
  "result_code": 1203,
  "result_msg": "Unauthorized",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "JWT token expired"
  }
}

状态代码¶

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	JWT 验证失败（详情请参见`token_validation`）
405	`1204`	Method not allowed	HTTP 请求方法错误

Note

当JWT 验证失败时，您可以在token_validation字段中查看详细的错误信息。更多信息请参阅JWT 验证错误代码。

查询全部公告¶

返回特定应用（game_index）的完整公告列表。

请求信息¶

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

请求数据¶

说明调用“查询全部公告”时发送的数据。

请求头¶

字段	类型	必填	说明	备注
X-Access-Token	string	Y	JWT Access Token	发行方法请参见 OAuth Token 发行

请求头示例¶

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

路径参数¶

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

请求体¶

无（GET 请求）

请求示例¶

调用“查询全部公告”的示例如下。

curl -X GET "https://sandbox-social-api.qpyou.cn/v2/games/539/notices" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

响应数据¶

说明调用“查询全部公告”时收到的数据。

响应体¶

字段	类型	说明
result_code	int	响应结果代码
result_msg	string	结果消息
token_validation	object	JWT 验证结果
ㄴ result_code	int	JWT 验证结果代码（`0`=成功，详情参见JWT 验证错误码）
ㄴ result_msg	string	JWT 验证结果消息
data	object	响应数据（JWT 验证失败时不包含）
ㄴ list	array	公告列表（公告基本信息对象数组，如果没有结果，则`[]`）

响应示例¶

调用“查询全部公告”时的响应示例如下。

class=linenos data-linenos=" 1 ">{ "result_code": 0, "result_msg": "Success", "token_validation": { "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": 4, "game_index": 539, "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"] } ] } class=p>}

分页查询公告¶

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

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

请求信息¶

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

请求数据¶

说明调用“分页查询公告”时发送的数据。

请求头¶

字段	类型	必填	说明	备注
X-Access-Token	string	Y	JWT Access Token	发行方法请参见 OAuth Token 发行

请求头示例¶

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

路径参数¶

字段	类型	必填	说明
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/v2/games/539/notices?page=1&per_page=20" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

响应数据¶

说明调用“分页查询公告”时收到的数据。

响应体¶

字段	类型	说明
result_code	int	响应结果代码
result_msg	string	结果消息
token_validation	object	JWT 验证结果
ㄴ result_code	int	JWT 验证结果代码（`0`=成功，详情参见JWT 验证错误码）
ㄴ result_msg	string	JWT 验证结果消息
data	object	响应数据（JWT 验证失败时不包含）
ㄴ 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",
  "token_validation": {
    "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": 4,
        "game_index": 539,
        "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"]
      }
    ]
  }
}

响应数据详细说明¶

说明应用公告查询 API 支持的所有响应数据的详细信息。

公告基本信息¶

字段	类型	说明
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 标准