兌換

兌換是「玩家輸入兌換碼後取得獎勵」的核心動作。POST /redemptions 執行兌換、GET /redemptions 查詢歷史。

別名：本資源同時支援 /redemptions 與 /redeem 兩個路徑，行為完全相同（為相容性而保留）。

資料模型

Name
id
Type
integer
Description
兌換紀錄 ID。
Name
user
Type
object
Description
兌換的使用者，含 id、unity_player_id、email。
Name
redemption_code
Type
object
Description
使用的兌換碼，含 id、code、group_id、total_uses。
Name
redeemed_at
Type
datetime | null
Description
兌換完成時間。

POST/redemptions

兌換獎勵

執行一次兌換。後端會在 transaction 中：

驗證兌換碼合法（存在 / 未過期 / 未達使用上限）
取得或建立使用者（從 Unity Cloud 取資料）
確認該使用者尚未兌換過此碼
發放獎勵並同步至 Unity

必填欄位

Name
redemption_code
Type
string
Description
兌換碼字串。
Name
unity_player_id
Type
string
Description
玩家 Unity Player ID。

Request

POST

/redemptions

curl https://api.poshentw.com/redemptions \
  -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "redemption_code": "WELCOME2026",
    "unity_player_id": "unity-12345"
  }'

Response

{
  "data": [
    { "id": 1, "code": "GOLD_100", "name": "金幣 100", "type": "金幣" },
    { "id": 2, "code": "GEM_10", "name": "寶石 10", "type": "寶石" }
  ]
}

可能的錯誤

狀態	例外	含義
404	RedemptionException::invalidCode	兌換碼錯誤或不存在
409	RedemptionException::expired	兌換碼已過期
409	RedemptionException::maxUsesExceeded	兌換碼已被全部用完
409	RedemptionException::alreadyRedeemed	該使用者已兌換過

GET/redemptions

列出兌換歷史

分頁列出所有兌換紀錄。可依使用者、兌換碼、日期區間過濾。

選填參數

Name
user_id
Type
integer
Description
過濾特定使用者。
Name
redemption_code_id
Type
integer
Description
過濾特定兌換碼 ID。
Name
redemption_code
Type
string
Description
過濾特定兌換碼字串。
Name
start_date
Type
date
Description
起始日期。
Name
end_date
Type
date
Description
結束日期。
Name
per_page
Type
integer
Description
每頁筆數。

Request

GET

/redemptions

curl -G https://api.poshentw.com/redemptions \
  -H "Authorization: Bearer {token}" \
  -d redemption_code=WELCOME2026 \
  -d per_page=20

Response

{
  "data": [
    {
      "id": 7,
      "redemption_id": 7,
      "user": {
        "id": 42,
        "unity_player_id": "unity-12345",
        "email": "alice@example.com"
      },
      "redemption_code": {
        "id": 99,
        "code": "WELCOME2026",
        "group_id": 5,
        "total_uses": 12
      },
      "redeemed_at": "2026-04-15T13:00:00+08:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1 }
}