共有チケットテンプレート

管理APIの /admin/v2 では、プレイチケットとギフトのテンプレートを共有資源として扱います。 BearerトークンまたはHMAC APIキーで認証した管理ユーザーが操作できます。 テンプレートには所有者がなく、一覧は担当ガチャに限定されません。

テンプレートの操作

メソッド	パス（/admin/v2 配下）	操作
GET	/play_ticket_templates	プレイチケットテンプレートの共有一覧
POST	/play_ticket_templates	テンプレートの作成
PUT	/play_ticket_templates/:id	属性の全置換
PUT	/play_ticket_templates/:id/gacha_restrictions	担当ガチャの制限の置き換え
GET	/gift_templates	ギフトテンプレートの共有一覧
POST	/gift_templates	ギフトテンプレートの作成
PATCH	/gift_templates/:id	ギフトテンプレートの部分更新
GET	/play_ticket_templates/:id/codes	対象チケットを配布するコードの履歴
POST	/gift_templates/:id/codes	既存のギフトテンプレートからコードを発行
POST	/gachas/:gacha_id/gift_code_issues	ギフトテンプレートの作成とコード発行

一覧は items と next_cursor を返します。 続きがある場合は next_cursor を次の要求の cursor に指定します。 limit の上限は200件です。 書き込みに Idempotency-Key を付けると、同じ要求の再送で重複した書き込みを防げます。

ガチャ制限

プレイチケットテンプレートの作成本文は gacha_restrictions を省略できます。 指定する場合は gacha_id と is_allowed の配列を渡し、各ガチャの書き込み権限が必要です。

制限の置き換え本文は { "entries": [{ "gacha_id": "...", "is_allowed": true }] } です。 書き込み権限のあるガチャの制限だけが置き換わり、担当外の制限は保持されます。 担当外のガチャを本文に指定すると403を返します。 ガチャ単位のAPIキースコープもこの判定に適用します。

共有テンプレートの属性変更は、そのテンプレートを使うすべてのガチャに及びます。 共有資源の操作にはガチャ単位のスコープ制限を適用しません。 ギフトテンプレートの配布内容の変更は、発行済みで未使用のコードにも及びます。

コードの発行と履歴

既存のギフトテンプレートからの発行では、本文に quantity を指定します。 ガチャ配下の発行では、本文に play_ticket_template_id、code_quantity、ticket_quantity と任意の expire_at を指定します。 ガチャへの書き込み権限と、そのガチャで利用を許可されたプレイチケットテンプレートが必要です。 ギフトテンプレートの作成とコードの保存は同一トランザクションで行います。

コードの発行枚数は1回につき1枚から1000枚までです。 1コードあたりのチケット枚数は1以上の整数です。 履歴もカーソルでページングし、コードごとに gift_template_id、assigned_user_id、created_at、expire_at を返します。