獎勵

獎勵代表可以被發放的資源項目。每個獎勵歸屬於一個獎勵分類（reward_category），並可被掛在多個兌換碼下。

資料模型

  • Name
    id
    Type
    integer
    Description
    獎勵 ID。
  • Name
    code
    Type
    string
    Description
    獎勵代碼，遊戲端用此值對應實際資源。
  • Name
    name
    Type
    string
    Description
    人類可讀的獎勵名稱。
  • Name
    type
    Type
    string
    Description
    所屬分類名稱（從 reward_category 帶出）。
GET/rewards

列出獎勵

分頁列出獎勵。可依名稱/代碼搜尋，或依分類過濾。

選填參數

  • Name
    search
    Type
    string
    Description
    依名稱或代碼模糊搜尋。
  • Name
    reward_category_id
    Type
    integer
    Description
    過濾特定分類。
  • Name
    per_page
    Type
    integer
    Description
    每頁筆數。

Request

GET
/rewards
curl -G https://api.poshentw.com/rewards \
  -H "Authorization: Bearer {token}" \
  -d search=GOLD

Response

{
  "data": [
    { "id": 1, "code": "GOLD_100", "name": "金幣 100", "type": "金幣" }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1 }
}
POST/rewards

建立獎勵

必填欄位

  • Name
    reward_category_id
    Type
    integer
    Description
    所屬分類 ID。
  • Name
    code
    Type
    string
    Description
    獎勵代碼，最多 255 字。
  • Name
    name
    Type
    string
    Description
    獎勵名稱，最多 255 字。

選填欄位

  • Name
    value
    Type
    numeric
    Description
    獎勵數值（如金幣數量）。

Request

POST
/rewards
curl https://api.poshentw.com/rewards \
  -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reward_category_id": 1,
    "code": "GEM_50",
    "name": "寶石 50",
    "value": 50
  }'

Response (201)

{
  "data": { "id": 3, "code": "GEM_50", "name": "寶石 50", "type": "寶石" }
}
GET/rewards/{id}

取得單一獎勵

依 ID 取得獎勵詳細資料。

Request

GET
/rewards/3
curl https://api.poshentw.com/rewards/3 \
  -H "Authorization: Bearer {token}"
PUT/rewards/{id}

更新獎勵

支援部分更新，傳哪幾個欄位就更新哪幾個。

可更新欄位

  • Name
    reward_category_id
    Type
    integer
    Description
    分類 ID。
  • Name
    code
    Type
    string
    Description
    獎勵代碼，需在所有獎勵中唯一（自己除外）。
  • Name
    name
    Type
    string
    Description
    獎勵名稱。
  • Name
    value
    Type
    numeric
    Description
    獎勵數值。
  • Name
    image_url
    Type
    string | null
    Description
    圖片 URL。

Request

PUT
/rewards/3
curl https://api.poshentw.com/rewards/3 \
  -X PUT \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "寶石 50（特賣）" }'
DELETE/rewards/{id}

刪除獎勵

回 204 No Content。

注意：若獎勵已被任何兌換碼或 user_reward 紀錄引用，會回 409 RewardInUseException。需要先清除引用紀錄才能刪除。

Request

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

Was this page helpful?