免費道具
讓玩家無需輸入代碼或付款即可領取活動獎勵。您的伺服器查詢活動狀態、為接收者提交領取請求,再處理 redemption.completed Webhook,在遊戲中發放獎勵。
完整的請求與回應結構請參閱免費道具 API 參考。
身份驗證與接收者識別碼
從伺服器使用金鑰呼叫 API。查詢狀態需要 FreeItemStatus 許可權,領取需要 FreeItemClaim 許可權。金鑰只儲存在後端,recipientId 應來自遊戲中已登入並通過身份驗證的玩家。
recipientId 是您自己系統中接收者(即接收獎勵的帳號)的識別碼。Tokenz 不會查詢遊戲帳號,只根據這個字串識別接收者。
- 會去除首尾空白,不允許空白值。
- 最多 100 個字元。超長值會返回
request.decoding-failed,不會被截斷。 - 區分大小寫。
Player_123和player_123是不同的接收者,各有獨立額度。 - 所有呼叫都應使用同一個穩定識別碼,不要轉為小寫或通過其他方式合併不同識別碼。
- 相同識別碼在不同裝置、會話或店面中共享領取額度。
活動設定與狀態
在 Tokenz Dashboard 中配置活動時間、獎勵、活動總額度、每位接收者的額度以及重複週期,並管理暫停、恢復和結束操作。如果看不到免費道具設定,請聯絡 Tokenz 支援,確認您的帳號是否已開放此功能。
draft:草稿,不能領取,所有欄位可編輯。scheduled:已釋出,等待開始;到達startAt即可領取。active:活動進行中,可以領取。paused:已暫停,不能領取,可恢復為active。ended:已結束,不能領取,此狀態不可撤銷。
查詢與領取要求活動類型為免費道具,狀態為 active,或為 scheduled 且已到達 startAt,並且尚未到達 endAt。即使儲存的狀態尚未更新,已到開始時間的 scheduled 活動也可使用。時間按絕對時刻比較,玩家所在地不會改變活動結束時刻。
額度與重複週期
每次領取都會檢查兩個獨立的額度:
- 活動總額度:所有接收者的領取次數總和。達到上限後返回
campaign.limit-reached。 - 每位接收者的額度:同一
recipientId的領取次數。一次性活動達到上限返回campaign.recipient-limit-reached;重複活動返回campaign.recipient-period-limit-reached。其他接收者不受影響。
一次性活動的兩個額度均適用於活動整個生命週期,不會重置。重複活動的兩個額度都會在每個週期開始時重置。被拒絕的領取不會消耗任一額度。
| 頻率 | 週期開始時間 |
|---|---|
| 一次性 | 不重置 |
| 每日 | 當地時間午夜 |
| 每週 | 週一當地時間午夜 |
| 每月 | 每月第一天當地時間午夜 |
使用活動的時區,而非玩家時區。API 不返回該時區,因此不要自行計算週期邊界。使用 nextResetAt 顯示倒計時,到達該時刻後重新查詢狀態。該時刻及之後的領取屬於新週期。重置不會延長 endAt。
例如,每日活動總額度為 100 次、每位接收者限 1 次,則每天最多 100 位接收者各領取一次。次日重置後,總額度恢復到 100 次,前一天已領取的接收者也可再次領取。
領取流程
- 在自己的系統中儲存
campaignId。 - 伺服器呼叫
GET /v3/free-items/{campaignId}?recipientId=...,顯示獎勵與剩餘額度。 - 玩家點選領取後,伺服器呼叫
POST /v3/free-items/claim。 - Tokenz 建立領取記錄,返回
201,並發送redemption.completedWebhook。 - 後端驗證簽名,使用
redemptionId防止重複發放,再發放獎勵。
查詢狀態
campaignId 是必需的路徑引數,recipientId 是可選的查詢引數。狀態查詢不會預留額度,提交領取時可用額度可能已改變。額度耗盡時,狀態介面返回剩餘次數 0,而不是額度錯誤。
curl --request GET \
--url 'https://api.tokenz.one/v3/free-items/campaign_1p4LPTRKB5Z_t?recipientId=player_98765' \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'
成功回應(200)
{
"campaign": {
"id": "campaign_1p4LPTRKB5Z_t",
"name": "Weekly Free Pack"
},
"rewardPreview": {
"name": "Marathon Energy Gift",
"imageUrl": "https://images.example.com/rewards/energy.png",
"quantity": 1
},
"campaignRemaining": 842,
"remainingForRecipient": 1,
"nextResetAt": "2026-09-14T00:00:00Z"
}
campaignRemaining:所有接收者可用的剩餘次數。重複活動為當前週期,一次性活動為整個生命週期。未設定活動總額度時省略。remainingForRecipient:此接收者的剩餘次數。未提供recipientId或未設定每位接收者的額度時省略。nextResetAt:兩個額度下次重置的絕對時刻。一次性活動省略。
領取免費道具
請求主體中的 campaignId 和 recipientId 均為必填項。活動必須可領取,且兩個額度都未耗盡。API 建立記錄;實際獎勵由您的後端處理 Webhook 時發放。
curl --request POST \
--url https://api.tokenz.one/v3/free-items/claim \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
--header 'Idempotency-Key: claim_player_98765_2026-09-10T08:10:00Z_a1b2c3d4' \
--data '{
"campaignId": "campaign_1p4LPTRKB5Z_t",
"recipientId": "player_98765"
}'
成功回應(201)
{
"redemption": {
"redemptionId": "redemption_1p4LPTRKB5Z_t",
"recipientId": "player_98765",
"campaign": {
"id": "campaign_1p4LPTRKB5Z_t",
"name": "Weekly Free Pack"
},
"reward": {
"skuRedemptionReward": {
"type": "EXTERNAL_SKU",
"sku": "ITEM_ENERGY_GIFT",
"name": "Marathon Energy Gift",
"quantity": 1
}
},
"redeemedAt": "2026-09-10T08:10:00Z",
"kind": "FREE_ITEM_CLAIM",
"source": "FREE_ITEM_CLAIM",
"nextPeriodStart": "2026-09-14T00:00:00Z"
},
"remainingForRecipient": 0,
"nextResetAt": "2026-09-14T00:00:00Z"
}
remainingForRecipient 是本次領取後的剩餘次數,未設定每位接收者的額度時省略。一次性活動省略 nextResetAt。redemption 物件欄位與下方 Webhook 相同。
Webhook 與獎勵發放
Tokenz 向訂閱此事件的端點發送 redemption.completed,與禮品碼(原名為兌換碼)兌換使用同一事件。
發放獎勵前先驗證 Tokenz-Signature。 針對原始請求主體驗證,再解析內容。跳過驗證會使偽造請求獲得獎勵。請參閱保護你的 webhook 端點。
{
"id": "f75ff6f0-bdf9-4b25-bb96-968f8733a7e3",
"object": "redemption.completed",
"createdAt": "2026-09-10T08:10:00Z",
"test": true,
"eventData": {
"type": "redemption",
"version": "v3",
"data": {
"redemption": {
"redemptionId": "redemption_1p4LPTRKB5Z_t",
"campaign": {
"id": "campaign_1p4LPTRKB5Z_t",
"name": "Weekly Free Pack"
},
"recipientId": "player_98765",
"reward": {
"skuRedemptionReward": {
"type": "EXTERNAL_SKU",
"sku": "ITEM_ENERGY_GIFT",
"name": "Marathon Energy Gift",
"quantity": 1
}
},
"redeemedAt": "2026-09-10T08:10:00Z",
"kind": "FREE_ITEM_CLAIM",
"source": "FREE_ITEM_CLAIM",
"nextPeriodStart": "2026-09-14T00:00:00Z"
}
}
}
}
kind:免費道具為FREE_ITEM_CLAIM,禮品碼為CODE_REDEMPTION。新事件都會設定此欄位,但較早進入佇列的事件可能省略。source:已棄用,僅為相容現有整合保留。新整合使用kind。code:僅禮品碼兌換包含此欄位,免費道具領取會省略。請檢查現有處理程序是否錯誤地要求其存在。nextPeriodStart:僅重複免費道具活動包含。它根據redeemedAt時的活動週期計算下一週期開始時刻,而非根據 Webhook 投遞時間計算。一次性領取和禮品碼兌換均省略。
通常只需根據 redemptionId、recipientId 和 reward 共用一套發放邏輯。kind 缺失或未知時不要猜測類型,仍使用這三個欄位發放,並標記事件以供核對。頂層事件 id 用於追蹤投遞,redemptionId 用於防止重複發放。
冪等與重試
在 POST /v3/free-items/claim(v1 同樣適用)上傳送可選的 Idempotency-Key 請求標頭,不要放在 JSON 請求本體中。每次新的領取嘗試應產生新值(例如玩家點擊領取時);僅在網路錯誤、逾時或回應遺失後重試同一次嘗試時複用同一值。
省略 Idempotency-Key 時行為與舊版整合一致:額度允許時,每次成功請求都可能再建立一條領取記錄。沒有該標頭時不要盲目重試。
提供該標頭時,僅當 campaignId 與 recipientId 與首次請求一致才會回放已有領取;同一鍵用於不同活動或接收者時視為新的領取。若已有領取,Tokenz 回傳 201 及原 redemptionId,不會再次消耗額度。
Webhook 處理仍應依 redemptionId 去重;Webhook 去重不能代替領取請求的冪等標頭。
Webhook 投遞重試
端點未接受 Webhook 時,Tokenz 會逐漸增加間隔並加入隨機變化進行重試。重試安排在首次嘗試後的最長 72 小時視窗內;這不是保證在視窗內送達,實際執行可能延後。不要依賴固定次數或準確時間。投遞可能晚到數天,因此應將已發放的 redemptionId 持久儲存,而非放入短期快取,並保證同一 ID 的獎勵只發放一次。
錯誤處理
400/request.decoding-failed:無效 ID、空白或超長的recipientId、空白或超長的Idempotency-Key,或格式錯誤的請求。401:缺少或無效的 API 金鑰。403:缺少所需許可權。404/entity.not-found:活動不存在、屬於其他商戶,或測試模式與金鑰不匹配。422/campaign.kind-invalid:不是免費道具活動。422/campaign.status-invalid:草稿、暫停、結束,或尚未開始的預定活動。422/campaign.expired:已到結束時刻;結束狀態也可能返回campaign.status-invalid。422/campaign.limit-reached:總額度耗盡;重複活動為當前週期,一次性活動為整個生命週期。422/campaign.recipient-limit-reached:每位接收者的額度耗盡。422/campaign.recipient-period-limit-reached:當前週期的每位接收者額度耗盡,可在nextResetAt後重試。429:超過速率限制。兩個介面均按 API 金鑰限制;提供接收者識別碼時,也按接收者限制。500:意外的伺服器錯誤。
測試
使用以 secret_test_ 開頭的金鑰,在 Dashboard 測試模式下建立活動。測試與正式資料隔離,金鑰只能操作模式匹配的活動。測試 ID 以 _t 結尾;測試 Webhook 僅傳送到測試端點,承載內容包含 "test": true。
測試成功領取與獎勵發放、兩個額度耗盡、週期重置、暫停與過期、重複投遞,以及使用相同 Idempotency-Key 重試並返回相同 redemptionId 的情況。也應驗證空白和超長 recipientId、速率限制以及測試與正式模式隔離,並確認每個 redemptionId 只發放一次獎勵。