兌換碼群組

兌換碼群組（redemption_code_group）用於把一批兌換碼當成一個活動管理。建立群組時可指定 quantity 直接批次產生 N 個碼，並設定每個碼的最大使用次數與整體過期時間。

資料模型

Name
id
Type
integer
Description
群組 ID。
Name
name
Type
string
Description
群組名稱（顯示用）。
Name
game
Type
object
Description
所屬遊戲，{ id, name }。
Name
redemption_codes_count
Type
integer
Description
群組底下的兌換碼總數。
Name
used_count
Type
integer
Description
所有碼累計被使用的次數總和。
Name
max_uses_per_code
Type
integer | null
Description
每個碼可被使用的最大次數。
Name
total_max_uses
Type
integer | null
Description
群組整體可使用次數（codes_count × max_uses_per_code）。
Name
expired_at
Type
datetime | null
Description
過期時間（Asia/Taipei，存為當日結束）。

GET/redemption-code-groups

列出群組

分頁列出所有群組。

選填參數

Name
game_id
Type
integer
Description
過濾特定遊戲。
Name
per_page
Type
integer
Description
每頁筆數。

Request

GET

/redemption-code-groups

curl -G https://api.poshentw.com/redemption-code-groups \
  -H "Authorization: Bearer {token}" \
  -d game_id=1

POST/redemption-code-groups

批次建立群組 + 兌換碼

建立一個群組，並一次性產生 quantity 個兌換碼，全部關聯到指定獎勵。

必填欄位

Name
name
Type
string
Description
群組名稱（1–10 字，僅允許英數字與中文）。
Name
game_id
Type
integer
Description
所屬遊戲 ID。
Name
quantity
Type
integer
Description
要建立的兌換碼數量（1–10000）。
Name
rewards
Type
array
Description
關聯獎勵，至少 1 個，元素為 { "reward_id": integer }。

選填欄位

Name
max_uses
Type
integer
Description
每個兌換碼最多可被使用幾次（預設不限）。
Name
expired_at
Type
date
Description
過期日（必須是未來日期），會被存成當日 23:59:59。

Request

POST

/redemption-code-groups

curl https://api.poshentw.com/redemption-code-groups \
  -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "新春活動",
    "game_id": 1,
    "quantity": 100,
    "max_uses": 1,
    "expired_at": "2026-12-31",
    "rewards": [{ "reward_id": 1 }, { "reward_id": 2 }]
  }'

Response (201)

{
  "data": {
    "redemption_code_group_id": 5,
    "name": "新春活動",
    "count": 100
  }
}

群組名稱重複會回 409 GroupNameAlreadyExistsException。

PUT/redemption-code-groups/{id}

更新群組

僅支援更新 name 與 expired_at。

可更新欄位

Name
name
Type
string
Description
群組名稱，需唯一（自己除外）。
Name
expired_at
Type
date | null
Description
過期日（必須是未來日期）。

Request

PUT

/redemption-code-groups/5

curl https://api.poshentw.com/redemption-code-groups/5 \
  -X PUT \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "expired_at": "2027-01-31" }'

DELETE/redemption-code-groups/{id}

刪除群組

回 204 No Content。

Request

DELETE

/redemption-code-groups/5

curl https://api.poshentw.com/redemption-code-groups/5 \
  -X DELETE \
  -H "Authorization: Bearer {token}"