免費旋轉

不需要透過平台管理團隊，你就可以為自己的玩家發放、列出並取消免費旋轉——本指南所依據的精確請求/回應結構，見免費旋轉 API 參考。

臨時發放與活動發放

你可以用兩種方式發放：

• 臨時發放（ad hoc） —— 直接在請求上指定 gameId、spins、betAmountMinor 和 currency。
• 從活動（campaign）發放 —— 改為傳入 campaignId，這四個欄位會從活動範本讀取，你另外傳入的任何值都會被忽略。活動是你的整合聯絡人為你預先設定好、可重複使用的範本；如果你有它的 ID，直接引用即可。

const path = '/v1/operator/free-spins/grants'
const body = JSON.stringify({
  playerRef,
  gameId,
  spins: 10,
  betAmountMinor: 100, // 或省略/傳 0，使用你錢包的預設下注金額
  currency: 'USD',
  idempotencyKey: crypto.randomUUID(), // 見下方「冪等性」
})

const headers = signRequest('POST', path, operatorSecret, body, operatorId)
const res = await fetch(`${platformUrl}${path}`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body,
})
const grant = await res.json()
// grant.status: 'pending' | 'active' | 'cancelled' | 'failed'
// grant.externalRef —— 一旦發放成功，廠商自己對這一批發放的識別碼

這個呼叫是同步的

和錢包交易不同，發放一筆免費旋轉是一個即時、同步的呼叫，會一路打到廠商的遊戲伺服器——它不是排隊處理，也不是發完即忘。你會立刻知道結果是否成功：回應中的 failed 狀態代表廠商自己的發放呼叫失敗了（見 lastError），而且這次嘗試會永久消耗掉 idempotencyKey——重試時請用一個全新的 key，不要重複用同一個。

冪等性

idempotencyKey 是必填的，且作用範圍限定在你的運營商租戶內。用同一個 key 重複呼叫，會回傳原本那筆發放目前的狀態，而不是再發放一批新的——所以在網路失敗後用同一個 key 重試是安全的，但一旦某筆發放進入 failed 狀態，這個 key 就算用掉了；下一次嘗試請產生一個新的。

查詢狀態與取消

// GET /v1/operator/free-spins/grants/{id} —— 某一筆發放目前的狀態
// GET /v1/operator/free-spins/grants?playerRef=<ref> —— 某位玩家的所有發放記錄
// POST /v1/operator/free-spins/grants/{id}/cancel —— 作廢剩餘、尚未使用的旋轉次數

只有 active 狀態的發放才能取消。和發放一樣，取消也是同步呼叫到廠商——如果這次呼叫失敗，你的發放記錄會維持原狀（不會被標記為已取消），因為這些旋轉次數在廠商那一側可能依然可用。請重試取消，而不要假設它已經生效。

派彩仍透過錢包回調結算

免費旋轉的派彩不屬於這個 API 的範疇——當玩家透過免費旋轉獲勝時，廠商會透過 POST /v1/wallet/transaction 把它當成一筆普通的 WIN 提交，由你的錢包回調像處理其他任何一筆獲勝一樣處理。這個 API 只負責搬運「發放了多少旋轉次數／還剩多少」，從不涉及金錢本身。