跳轉至

游戏通知

本指南介紹遊戲公告查詢 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 標準