使用者

使用者代表一個跨遊戲的玩家身分。一位 user 可以擁有多個 game_account（每個遊戲一筆）與多個 oauth_account（綁多個第三方登入）。

資料模型

使用者列表項

Name
id
Type
integer
Description
使用者 ID。
Name
email
Type
string
Description
Email。訪客會被 mask 為 {uuid}@guest.com。
Name
name
Type
string | null
Description
使用者名稱。
Name
games
Type
string[]
Description
該使用者有帳號的遊戲名稱清單。
Name
auth_providers_count
Type
object
Description
各 OAuth provider 的綁定數量，例如 { "Google": 1, "Apple": 0 }。
Name
last_login_at
Type
datetime | null
Description
最後登入時間。
Name
created_at
Type
datetime
Description
建立時間。

GET/users

列出使用者

分頁列出全部使用者。可依 email、auth_provider、game 過濾。

選填參數

Name
search
Type
string
Description
依 email 模糊搜尋。
Name
auth_provider_id
Type
integer
Description
過濾特定 OAuth provider。
Name
game_id
Type
integer
Description
過濾特定遊戲。
Name
per_page
Type
integer
Description
每頁筆數（預設 15）。

Request

GET

/users

curl -G https://api.poshentw.com/users \
  -H "Authorization: Bearer {token}" \
  -d search=alice \
  -d per_page=20

Response

{
  "data": [
    {
      "id": 42,
      "email": "alice@example.com",
      "name": "Alice",
      "games": ["咖波疊疊樂"],
      "auth_providers_count": { "Google": 1 },
      "last_login_at": "2026-04-27T10:23:00+08:00",
      "created_at": "2025-12-01T00:00:00+08:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1 }
}

GET/users/{id}

取得單一使用者

回傳完整使用者資料，含 game_accounts、oauth_accounts 與彙總 statistics。

Request

GET

/users/42

curl https://api.poshentw.com/users/42 \
  -H "Authorization: Bearer {token}"

Response（節選）

{
  "data": {
    "id": 42,
    "email": "alice@example.com",
    "name": "Alice",
    "game_accounts": [...],
    "oauth_accounts": [...],
    "statistics": {
      "total_game_accounts": 1,
      "total_oauth_accounts": 1,
      "total_games": 1,
      "accounts_by_game": [...]
    }
  }
}

DELETE/users/{id}

刪除使用者

刪除使用者及其所有關聯資料。回 204 No Content，無 response body。

Request

DELETE

/users/42

curl https://api.poshentw.com/users/42 \
  -X DELETE \
  -H "Authorization: Bearer {token}"

GET/new-users

新會員報表

取得指定期間內新註冊的使用者統計。period 與 start_date / end_date 互斥；皆未提供時預設 14 天。

選填參數

Name
period
Type
integer
Description
回看天數（1–365，預設 14）。
Name
game_id
Type
integer
Description
過濾特定遊戲。
Name
start_date
Type
date
Description
起始日（Y-m-d）。需與 end_date 配對。
Name
end_date
Type
date
Description
結束日（Y-m-d）。需與 start_date 配對。

Request

GET

/new-users

curl -G https://api.poshentw.com/new-users \
  -H "Authorization: Bearer {token}" \
  -d period=30 \
  -d game_id=1

GET/users/redemptions

使用者兌換歷史

依 email 查該使用者所有兌換紀錄。分頁回傳。

必填參數

Name
email
Type
string
Description
使用者 email。

選填參數

Name
per_page
Type
integer
Description
每頁筆數。

Request

GET

/users/redemptions

curl -G https://api.poshentw.com/users/redemptions \
  -H "Authorization: Bearer {token}" \
  -d email=alice@example.com

Response

{
  "data": [
    {
      "id": 7,
      "redeemed_at": "2026-04-15T13:00:00+08:00",
      "redemption_code": {
        "id": 99,
        "code": "WELCOME2026",
        "rewards": [
          { "id": 1, "name": "金幣 100", "code": "GOLD_100", "value": 100 }
        ]
      }
    }
  ],
  "meta": { "current_page": 1, "total": 1 }
}