免費旋轉 API 參考

用於為你自己的玩家發放、列出、取消免費旋轉的自助介面——簽名方式與其他所有運營商 API呼叫相同。指南見免費旋轉。活動範本（admin 設定的可重複使用預設）由平台管理團隊管理，不透過這個 API——如果你的對接窗口已經為你設定好了某個活動範本，你可以透過 ID 引用它，否則直接提供發放請求所需的各個欄位即可。

POST /v1/operator/free-spins/grants

請求體：

type IssueGrantRequestBody = {
  playerRef: string
  campaignId?: string // 若設定了此欄位，下面的 gameId/spins/betAmountMinor/currency
                        // 都會被忽略，改為從該活動讀取
  gameId?: string          // 若省略 campaignId 則必填
  spins?: number            // 若省略 campaignId 則必填（且 > 0）
  betAmountMinor?: number  // 選填；不傳或傳 0 則使用你錢包的預設下注額
  currency?: string         // 若省略 campaignId 則必填
  idempotencyKey: string   // 必填——見下方冪等性
  expiresAt?: string        // 選填的 RFC3339 時間戳；僅供參考，目前平台不會強制執行
}

currency 必須是目標遊戲廠商支援的其中一種，且該遊戲必須對你的運營商租戶可見——和 launch 應用的是相同的檢查。

響應：新建立的發放記錄（若冪等鍵重複，則是原始那筆的發放記錄）：

type GrantStatus = 'pending' | 'active' | 'cancelled' | 'failed'
// 'expired' 和 'completed' 是為未來某個階段保留的——屆時會接入
// 廠商上報的完成狀態；目前沒有任何流程會產生這兩個值。

type GrantResponseBody = {
  id: string
  campaignId?: string
  operatorId: string
  providerId: string
  gameId: string
  playerRef: string
  spins: number
  betAmountMinor: number
  currency: string
  externalRef?: string // 廠商自己對這一批次的識別碼——在廠商端呼叫成功之前為空
  status: GrantStatus
  idempotencyKey: string
  expiresAt?: string
  lastError?: string    // 當 status 為 'failed' 時才會有值
  createdAt: string
  updatedAt: string
}

冪等性

idempotencyKey 是必填的，且作用範圍限定在 (你的 operatorId, idempotencyKey) 這對組合內：用同一個鍵重複呼叫，會原樣返回最初那次呼叫產生的發放記錄，而不會發放第二批。這是一次對廠商的同步呼叫，不是丟進佇列後不管的非同步操作——廠商端失敗會立即把這筆發放標記為 failed（見 lastError），並且永久消耗掉這個冪等鍵：如果你想再試一次，請用一個全新的鍵，而不是複用同一個。

錯誤響應：400（欄位缺失/無效、spins 不是正數、貨幣不支援，或者——對基於活動的發放而言——該活動未啟用或已超出其有效期）、403（該遊戲對你的運營商租戶不可見）、404（沒有這個活動，或沒有這個遊戲）、502（廠商端呼叫本身失敗——見產生的 failed 發放記錄上的 lastError）、401/429（與每個運營商 API 介面共用——見錯誤與重試）。

GET /v1/operator/free-spins/grants?playerRef=<ref>

列出你的運營商租戶下的發放記錄。playerRef 是選填的——不傳則列出你租戶已發放的每一筆記錄。

響應：GrantResponseBody[]。

GET /v1/operator/free-spins/grants/{id}

依 ID 返回單筆發放記錄，範圍限定在你的運營商租戶內（屬於其他運營商的發放 ID，表現得就像不存在一樣）。

錯誤響應：404（你的租戶下沒有這筆發放記錄）、400（id 不是合法的識別碼）。

POST /v1/operator/free-spins/grants/{id}/cancel

作廢一筆發放記錄中剩餘、尚未使用的旋轉次數。只有 active 狀態的發放才能被取消——對處於 pending、已經 cancelled、或 failed 狀態的發放呼叫此介面會返回 400（ErrGrantNotCancellable）。和發放一樣，這是一次對廠商的同步呼叫：如果廠商端的取消呼叫本身失敗，你這邊的本地記錄不會被標記為已取消（那些旋轉次數在廠商那一側可能仍然有效），所以這裡出現 502 意味著應該重試取消操作，而不是假定它已經生效。

響應：更新後的 GrantResponseBody。

錯誤響應：404（你的租戶下沒有這筆發放記錄）、400（不可取消——見上文）、502（廠商端的取消呼叫失敗）、401/429（共用，見錯誤與重試）。