游戏通知

本指南介紹應用程式公告查詢 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	公告清單（公告基本資訊物件陣列，如果沒有結果，則`[]`）

回應範例¶

呼叫「查詢全部公告」時的回應範例如下。

href=#__codelineno-5-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 標準