API設計書

Version 1.0.0 | SB-Ticket（シュートボクシング）

SB-Ticket API リファレンス

Version: 0.1.0 Base URL: https://sb-ticket.com (本番) / http://localhost:8000 (ローカル) 認証方式: JWT (HttpOnly Cookie) ドキュメントURL: /docs (Swagger UI) / /redoc (ReDoc)

---

目次

• エンドポイント一覧
• 認証・ロール
• 共通レスポンス
• 列挙型 (Enum)
• 1. Health Check
• 2. Authentication (認証)
• 3. Events (イベント)
• 4. Tickets (チケット)
• 5. Players (選手)
• 6. Landing Pages (LP)
• 7. Fans (ファン)
• 8. Sponsors (スポンサー)
• 9. Kickbacks (キックバック)
• 10. Notifications (通知)
• 11. Rankings (ランキング)
• 12. Admin (管理者)
• 13. Concept Pipeline (営業パイプライン)
• 14. Rewards (報酬)

---

エンドポイント一覧

#	メソッド	パス	説明	認証
1	GET	/health	ヘルスチェック	不要
認証
2	POST	/api/auth/login	ログイン	不要
3	POST	/api/auth/logout	ログアウト	不要
4	POST	/api/auth/refresh	トークンリフレッシュ	Cookie
5	POST	/api/auth/password-change	パスワード変更	必要
6	POST	/api/auth/sms-send	SMS認証コード送信	不要
7	POST	/api/auth/sms-verify	SMS認証コード検証	不要
8	POST	/api/auth/phone-register	電話番号登録	必要
イベント
9	GET	/api/events/	イベント一覧	必要
10	GET	/api/events/{event_id}	イベント詳細	必要
11	POST	/api/events/	イベント作成	Admin
12	PUT	/api/events/{event_id}	イベント更新	Admin
13	DELETE	/api/events/{event_id}	イベント削除	Admin
14	GET	/api/events/{event_id}/players	イベント参加選手一覧	必要
15	POST	/api/events/{event_id}/players	選手をイベントにアサイン	Admin
16	PUT	/api/events/{event_id}/players/{player_id}	ノルマ更新	Admin
17	GET	/api/events/{event_id}/sales-stats	販売統計	必要
チケット
18	GET	/api/tickets/	チケット一覧	必要
19	GET	/api/tickets/{ticket_id}	チケット詳細	必要
20	POST	/api/tickets/manual-sale	手動チケット販売登録	必要
21	PUT	/api/tickets/{ticket_id}	チケット更新	必要
22	DELETE	/api/tickets/{ticket_id}	チケット削除	必要
23	POST	/api/tickets/webhook/pia	チケットぴあ Webhook	署名検証
選手
24	GET	/api/players/	選手一覧	Admin/Association
25	GET	/api/players/me	自分のプロフィール	必要
26	PUT	/api/players/me	プロフィール更新	必要
27	POST	/api/players/me/image	プロフィール画像アップロード	必要
28	GET	/api/players/public/{slug}	公開プロフィール	不要
29	GET	/api/players/{player_id}	選手詳細	必要
30	GET	/api/players/{player_id}/qr/{event_id}	QRコード生成	必要
31	POST	/api/players/	選手作成	Admin
32	PUT	/api/players/{player_id}	選手更新	Admin
33	DELETE	/api/players/{player_id}	選手削除(論理)	Admin
LP
34	GET	/api/lps/	LP一覧	必要
35	GET	/api/lps/{lp_id}	LP詳細	必要
36	POST	/api/lps/generate/{event_id}	LP生成 (Claude AI)	Admin
37	POST	/api/lps/generate	LP生成 (リクエストボディ)	必要
38	PUT	/api/lps/{lp_id}	LP更新	Admin
39	POST	/api/lps/{lp_id}/publish	LP公開	Admin
40	POST	/api/lps/{lp_id}/unpublish	LP非公開	Admin
41	GET	/api/lps/{lp_id}/preview	LPプレビュー (HTML)	必要
ファン
42	GET	/api/fans/	ファン一覧	必要
43	GET	/api/fans/dig-out	掘り起こしリスト	必要
44	GET	/api/fans/{fan_id}	ファン詳細	必要
45	GET	/api/fans/{fan_id}/purchases	ファン購入履歴	必要
46	POST	/api/fans/	ファン作成	必要
47	PUT	/api/fans/{fan_id}	ファン更新	必要
48	DELETE	/api/fans/{fan_id}	ファン削除	必要
スポンサー
49	GET	/api/sponsors/	スポンサー一覧	必要
50	GET	/api/sponsors/{sponsor_id}	スポンサー詳細	必要
51	POST	/api/sponsors/	スポンサー作成	Admin
52	PUT	/api/sponsors/{sponsor_id}	スポンサー更新	Admin
53	DELETE	/api/sponsors/{sponsor_id}	スポンサー論理削除	Admin
54	PUT	/api/sponsors/{sponsor_id}/concept-status	コンセプトステータス更新	Admin/Association
55	POST	/api/sponsors/{sponsor_id}/publish	協会公開トグル	Admin/Association
56	POST	/api/sponsors/{sponsor_id}/approve	公開承認	Admin
キックバック
57	GET	/api/kickbacks/	キックバック一覧	Admin/Association
58	GET	/api/kickbacks/{kickback_id}	キックバック詳細	Admin/Association
59	POST	/api/kickbacks/	キックバック作成	Admin/Association
60	PUT	/api/kickbacks/{kickback_id}	キックバック更新	Admin/Association
61	POST	/api/kickbacks/{kickback_id}/mark-paid	支払済マーク	Admin/Association
62	GET	/api/kickbacks/summary	キックバックサマリー	Admin/Association
63	GET	/api/kickbacks/export-csv	CSV エクスポート	Admin
通知
64	GET	/api/notifications/	通知一覧	必要
65	GET	/api/notifications/unread-count	未読数	必要
66	POST	/api/notifications/{notification_id}/read	既読にする	必要
67	POST	/api/notifications/read-all	全て既読にする	必要
68	POST	/api/notifications/send	通知送信	Admin
69	POST	/api/notifications/bulk-deadline	締切アラート一斉送信	Admin
ランキング
70	GET	/api/rankings/sales	チケット販売ランキング	必要
71	GET	/api/rankings/views	ページビューランキング	必要
72	GET	/api/rankings/daily/{event_id}	日別販売データ	必要
73	GET	/api/rankings/daily	前日販売ランキング	必要
管理者
74	GET	/api/admin/dashboard	ダッシュボード統計	Admin
75	GET	/api/admin/audit-logs	監査ログ	Admin
76	GET	/api/admin/players	選手管理一覧	Admin
77	POST	/api/admin/players	選手アカウント作成	Admin
78	POST	/api/admin/players/{player_id}/lock	アカウントロック	Admin
79	POST	/api/admin/players/{player_id}/unlock	アカウントアンロック	Admin
80	POST	/api/admin/players/{player_id}/reset-password	パスワードリセット	Admin
営業パイプライン
81	GET	/api/concept/leads	リード一覧	Association
82	GET	/api/concept/leads/pipeline-summary	パイプラインサマリー	Association
83	PUT	/api/concept/leads/{sponsor_id}/advance	ステージ進行	Association
84	PUT	/api/concept/leads/{sponsor_id}/status	ステータス設定	Association
85	POST	/api/concept/leads/{sponsor_id}/publish	協会公開トグル	Association
86	GET	/api/concept/kickbacks	キックバック一覧(営業)	Association
87	POST	/api/concept/kickbacks	キックバック作成(営業)	Association
報酬
88	GET	/api/rewards/	報酬一覧	必要
89	GET	/api/rewards/my	自分の収入サマリー	必要
90	POST	/api/rewards/calculate/{event_id}	報酬計算	Admin
91	POST	/api/rewards/{reward_id}/mark-paid	報酬支払済マーク	Admin
92	GET	/api/rewards/summary	報酬サマリー	Admin

合計: 92エンドポイント

---

認証・ロール

認証方式

JWTトークンをHttpOnly Cookieで管理する。ログイン成功時に access_token と refresh_token がCookieにセットされる。

Cookie名	有効期限	用途
access_token	設定値 (デフォルト30分)	API認証
refresh_token	7日間	トークン更新

ロール一覧

ロール	値	説明
Player	player	一般選手。自分のデータのみアクセス可
Admin	admin	管理者。全データへのフルアクセス
Association	association	協会/コンセプト管理者。営業パイプライン管理

認証レベル

レベル	説明
不要	認証なしでアクセス可能
必要	有効なJWTトークンが必要
Admin	admin ロールが必要
Admin/Association	admin または association ロールが必要
Association	association ロールが必要
署名検証	HMAC-SHA256署名によるWebhook認証

---

Rate Limiting

Category	Limit	Scope
Authentication endpoints	10 requests/min	Per IP
General API	100 requests/min	Per user
Webhook callbacks	1000 requests/min	Per endpoint
LP generation (Claude API)	5 requests/min	Per user

Rate limit headers:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Remaining requests in window
• X-RateLimit-Reset: UTC epoch seconds when window resets

Exceeding limits returns 429 Too Many Requests.

---

共通レスポンス

SuccessResponse

{
  "success": true,
  "message": "OK"
}

ErrorResponse

{
  "error": "string",
  "message": "Human-readable error message",
  "detail": "Additional error detail (optional)"
}

ページネーション

多くのリストエンドポイントは以下のクエリパラメータをサポート:

パラメータ	型	デフォルト	説明
page	int	1	ページ番号 (1始まり)
per_page	int	20	1ページあたりの件数 (最大100)

---

列挙型 (Enum)

PlayerRole

値	説明
player	一般選手
admin	管理者
association	協会

EventStatus

値	説明
draft	下書き
published	公開中
closed	終了
cancelled	キャンセル

TicketRoute

値	説明
lp	ランディングページ経由
pia	チケットぴあ経由
manual	手動登録
other	その他

LPStatus

値	説明
draft	下書き
published	公開中
unpublished	非公開

ConceptStatus

値	説明
lead	リード
proposal	提案中
negotiation	交渉中
contracted	契約済
declined	辞退

NotificationType

値	説明
sms	SMS通知
web_push	Webプッシュ通知
in_app	アプリ内通知

---

1. Health Check

GET /health

ロードバランサー・監視用ヘルスチェック。

認証: 不要

レスポンス:

{
  "status": "ok",
  "service": "sb-ticket-api",
  "version": "0.1.0"
}

---

2. Authentication (認証)

POST /api/auth/login

選手ログイン。認証成功時にJWTトークンをHttpOnly Cookieにセット。

認証: 不要

リクエストボディ:

フィールド	型	必須	説明
login_id	string	Yes	ログインID
password	string	Yes	パスワード (8文字以上)

レスポンス (TokenResponse):

フィールド	型	説明
access_token	string	JWTアクセストークン
token_type	string	"bearer"
expires_in	int	有効期限 (秒)

備考:

• ログイン失敗時に failed_attempts がインクリメントされる
• 5回失敗でアカウントロック
• 電話番号登録済みの場合 requires_sms フラグが返される

---

POST /api/auth/logout

ログアウト。JWT Cookieを削除。

認証: 不要

レスポンス: SuccessResponse

---

POST /api/auth/refresh

リフレッシュトークンから新しいアクセストークンを発行。

認証: refresh_token Cookie

レスポンス: TokenResponse

---

POST /api/auth/password-change

認証済み選手のパスワード変更。

認証: 必要

リクエストボディ:

フィールド	型	必須	説明
current_password	string	Yes	現在のパスワード (8文字以上)
new_password	string	Yes	新しいパスワード (8文字以上)

レスポンス: SuccessResponse

備考: 新パスワードは現在・過去のパスワードと異なる必要がある。bcrypt (cost 12) でハッシュ化。

---

POST /api/auth/sms-send

SMS認証コード送信 (Twilio Verify)。

認証: 不要

リクエストボディ:

フィールド	型	必須	説明
phone_number	string	Yes	E.164形式の電話番号 (例: +819012345678)

レスポンス: SuccessResponse

---

POST /api/auth/sms-verify

SMS認証コードを検証しログイン完了。

認証: 不要

リクエストボディ:

フィールド	型	必須	説明
phone_number	string	Yes	E.164形式の電話番号
code	string	Yes	6桁の認証コード

レスポンス: TokenResponse

---

POST /api/auth/phone-register

認証済み選手の電話番号登録。AES-256で暗号化して保存。

認証: 必要

リクエストボディ:

フィールド	型	必須	説明
phone_number	string	Yes	E.164形式の電話番号

レスポンス: SuccessResponse

---

3. Events (イベント)

GET /api/events/

イベント一覧取得。ステータスフィルタ・ページネーション対応。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	デフォルト	説明
status	string	No	-	ステータスフィルタ
page	int	No	1	ページ番号
per_page	int	No	20	件数 (最大100)

レスポンス: EventResponse[]

---

GET /api/events/{event_id}

イベント詳細取得。

認証: 必要 パスパラメータ: event_id (UUID)

レスポンス (EventResponse):

フィールド	型	説明
id	string	イベントUUID
name	string	イベント名
date	date	開催日
venue	string	会場名
door_time	time?	開場時間
start_time	time?	開始時間
sale_start_date	date?	販売開始日
sale_deadline	date?	販売締切日
seat_types	SeatType[]	席種と価格
sales_channels	string[]	販売チャネル
pia_base_url	string?	チケットぴあURL
promo_text	string	プロモーションテキスト
status	EventStatus	ステータス
created_at	datetime	作成日時

SeatType:

フィールド	型	説明
name	string	席種名 (例: S席, A席)
price	int	価格 (JPY)

---

POST /api/events/

イベント作成。

認証: Admin 監査ログ: あり

リクエストボディ (EventCreate):

フィールド	型	必須	説明
name	string	Yes	イベント名
date	date	Yes	開催日
venue	string	Yes	会場名
door_time	time	No	開場時間
start_time	time	No	開始時間
sale_start_date	date	No	販売開始日
sale_deadline	date	No	販売締切日
seat_types	SeatType[]	No	席種リスト
sales_channels	string[]	No	販売チャネル
pia_base_url	string	No	チケットぴあURL
promo_text	string	No	プロモーションテキスト

レスポンス: EventResponse

---

PUT /api/events/{event_id}

イベント更新。指定フィールドのみ更新 (部分更新)。

認証: Admin 監査ログ: あり

リクエストボディ (EventUpdate): EventCreate と同じフィールド (全てOptional) + status (EventStatus)

レスポンス: EventResponse

---

DELETE /api/events/{event_id}

イベント削除。

認証: Admin 監査ログ: あり

レスポンス: SuccessResponse

---

GET /api/events/{event_id}/players

イベントにアサインされた選手一覧。ノルマ・達成率を含む。

認証: 必要

レスポンス:

[
  {
    "player_id": "uuid",
    "player_name": "選手名",
    "gym": "ジム名",
    "weight_class": "階級",
    "target_quantity": 100,
    "target_amount": 500000,
    "reward_rate": 0.1,
    "sold_quantity": 45,
    "sold_amount": 225000,
    "achievement_rate": 45.0
  }
]

---

POST /api/events/{event_id}/players

選手をイベントにアサインし、ノルマ (販売目標) を設定。

認証: Admin 監査ログ: あり

リクエストボディ (NormaSet):

フィールド	型	必須	説明
player_id	string	Yes	選手UUID
event_id	string	Yes	イベントUUID
target_quantity	int	Yes	目標枚数
target_amount	int	Yes	目標金額 (JPY)

レスポンス: SuccessResponse

---

PUT /api/events/{event_id}/players/{player_id}

選手のノルマ更新。

認証: Admin 監査ログ: あり

リクエストボディ: NormaSet レスポンス: SuccessResponse

---

GET /api/events/{event_id}/sales-stats

イベントの販売統計。ルート別・選手別・席種別の内訳を返す。

認証: 必要

レスポンス:

{
  "event_id": "uuid",
  "total_quantity": 200,
  "total_amount": 1000000,
  "by_route": [
    {"route": "lp", "quantity": 100, "amount": 500000}
  ],
  "by_player": [
    {"player_id": "uuid", "player_name": "選手名", "quantity": 50, "amount": 250000}
  ],
  "by_seat_type": [
    {"seat_type": "S席", "quantity": 80, "amount": 640000}
  ]
}

---

4. Tickets (チケット)

GET /api/tickets/

チケット一覧取得。Player ロールの場合は自分のチケットのみ返す。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
event_id	string	No	イベントフィルタ
player_id	string	No	選手フィルタ
route	string	No	ルートフィルタ
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (TicketResponse[]):

フィールド	型	説明
id	string	チケットUUID
fan_id	string?	ファンUUID
player_id	string	選手UUID
event_id	string	イベントUUID
quantity	int	枚数
route	TicketRoute	販売ルート
seat_type	string	席種
amount	int	金額 (JPY)
paid	bool	支払済フラグ
paid_date	datetime?	支払日
buyer_name	string	購入者名
memo	string	メモ
purchased_at	datetime	購入日時

---

GET /api/tickets/{ticket_id}

チケット詳細。Player は自分のチケットのみアクセス可。

認証: 必要 レスポンス: TicketResponse

---

POST /api/tickets/manual-sale

手動チケット販売登録 (会場現金販売等)。

認証: 必要 監査ログ: あり

リクエストボディ (ManualSaleCreate):

フィールド	型	必須	説明
player_id	string	Yes	選手UUID
event_id	string	Yes	イベントUUID
fan_id	string	No	ファンUUID
quantity	int	No	枚数 (デフォルト1, 最小1)
seat_type	string	Yes	席種名
amount	int	Yes	金額 (JPY, 0以上)
buyer_name	string	No	購入者名
memo	string	No	メモ
paid	bool	No	支払済フラグ (デフォルトfalse)

レスポンス: TicketResponse

備考: 販売通知が選手に自動送信される。

---

PUT /api/tickets/{ticket_id}

チケット更新。

認証: 必要 監査ログ: あり リクエストボディ: ManualSaleCreate レスポンス: TicketResponse

---

DELETE /api/tickets/{ticket_id}

チケット削除。Player は自分のチケットのみ削除可。

認証: 必要 監査ログ: あり レスポンス: SuccessResponse

---

POST /api/tickets/webhook/pia

チケットぴあからのWebhookコールバック。HMAC-SHA256署名検証あり。

認証: X-Webhook-Signature ヘッダーによるHMAC-SHA256署名検証 監査ログ: あり

ヘッダー:

ヘッダー	必須	説明
X-Webhook-Signature	Yes	HMAC-SHA256署名

リクエストボディ (WebhookPayload):

フィールド	型	必須	説明
event_id	string	Yes	外部イベントID
order_id	string	Yes	ぴあ注文ID
buyer_name	string	Yes	購入者名
seat_type	string	Yes	席種名
quantity	int	Yes	枚数
amount	int	Yes	金額 (JPY)
player_ref	string	No	選手参照コード
purchased_at	string	Yes	購入日時 (ISO8601)

レスポンス: SuccessResponse

---

5. Players (選手)

GET /api/players/

選手一覧取得。

認証: Admin または Association

クエリパラメータ:

パラメータ	型	必須	デフォルト	説明
page	int	No	1	ページ番号
per_page	int	No	20	件数

レスポンス (PlayerResponse[]):

フィールド	型	説明
id	string	選手UUID
login_id	string	ログインID
name	string	表示名
gym	string	所属ジム
weight_class	string	階級
profile_image_url	string?	プロフィール画像URL
sns_links	object	SNSリンク
slug	string	URLスラグ
is_locked	bool	ロック状態
role	PlayerRole	ロール
created_at	datetime	作成日時
updated_at	datetime	更新日時

---

GET /api/players/me

認証済み選手の自分のプロフィール取得。

認証: 必要 レスポンス: PlayerResponse

---

PUT /api/players/me

認証済み選手の自分のプロフィール更新。

認証: 必要 監査ログ: あり

リクエストボディ (PlayerUpdate):

フィールド	型	必須	説明
name	string	No	表示名
gym	string	No	所属ジム
weight_class	string	No	階級
phone	string	No	電話番号 (AES-256暗号化)
profile_image_url	string	No	プロフィール画像URL
sns_links	object	No	SNSリンク
slug	string	No	URLスラグ

レスポンス: PlayerResponse

---

POST /api/players/me/image

プロフィール画像アップロード (Supabase Storage)。

認証: 必要 監査ログ: あり Content-Type: multipart/form-data

リクエスト:

フィールド	型	必須	説明
file	UploadFile	Yes	画像ファイル (image/* のみ)

レスポンス: SuccessResponse

---

GET /api/players/public/{slug}

選手の公開プロフィールページ。認証不要。

認証: 不要 パスパラメータ: slug (URLスラグ)

レスポンス (PlayerPublicResponse):

フィールド	型	説明
name	string	表示名
gym	string	所属ジム
weight_class	string	階級
profile_image_url	string?	プロフィール画像URL
sns_links	object	SNSリンク
slug	string	URLスラグ

---

GET /api/players/{player_id}

選手詳細取得。Player は自分のプロフィールのみアクセス可。

認証: 必要 レスポンス: PlayerResponse

---

GET /api/players/{player_id}/qr/{event_id}

選手のLP用QRコード (PNG画像) を生成。

認証: 必要 パスパラメータ: player_id (UUID), event_id (UUID) レスポンス: image/png (StreamingResponse)

備考: QRコードのURLは https://sb-ticket.com/lp/{event_id}?ref={slug} 形式。

---

POST /api/players/

選手アカウント作成。

認証: Admin 監査ログ: あり

リクエストボディ (PlayerCreate):

フィールド	型	必須	説明
login_id	string	Yes	ログインID
name	string	Yes	表示名
password	string	Yes	初期パスワード (8文字以上)
gym	string	No	所属ジム
weight_class	string	No	階級
phone	string	No	電話番号 (AES-256暗号化)
role	PlayerRole	No	ロール (デフォルト: player)

レスポンス: PlayerResponse

---

PUT /api/players/{player_id}

選手情報更新。

認証: Admin 監査ログ: あり リクエストボディ: PlayerUpdate レスポンス: PlayerResponse

---

DELETE /api/players/{player_id}

選手論理削除 (アカウントロック)。

認証: Admin 監査ログ: あり レスポンス: SuccessResponse

---

6. Landing Pages (LP)

GET /api/lps/

LP一覧取得。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
event_id	string	No	イベントフィルタ
status	LPStatus	No	ステータスフィルタ

レスポンス (LPResponse[]):

フィールド	型	説明
id	string	LP UUID
event_id	string	イベントUUID
html_content	string	HTML コンテンツ
status	LPStatus	ステータス
hero_image_url	string?	ヒーロー画像URL
published_at	datetime?	公開日時
created_at	datetime	作成日時
updated_at	datetime	更新日時

---

GET /api/lps/{lp_id}

LP詳細取得。lp_id または event_id で検索可能。

認証: 必要 レスポンス: LPResponse

---

POST /api/lps/generate/{event_id}

Claude AIを使用してLPを自動生成。

認証: Admin

クエリパラメータ:

パラメータ	型	必須	説明
hero_image_url	string	No	ヒーロー画像URL
additional_prompt	string	No	追加プロンプト

レスポンス: LPResponse

備考: イベント・選手データを取得し、Claude APIでHTMLを生成して保存。

---

POST /api/lps/generate

LP生成 (リクエストボディでパラメータ指定)。

認証: 必要

リクエストボディ (LPGenerateRequest):

フィールド	型	必須	説明
event_id	string	Yes	イベントUUID
player_id	string	Yes	選手UUID
hero_image_url	string	No	ヒーロー画像URL
additional_prompt	string	No	追加プロンプト

レスポンス: LPResponse

---

PUT /api/lps/{lp_id}

LPコンテンツ・ヒーロー画像を更新。

認証: Admin 監査ログ: あり

リクエストボディ (LPUpdateRequest):

フィールド	型	必須	説明
html_content	string	No	HTMLコンテンツ
hero_image_url	string	No	ヒーロー画像URL

レスポンス: LPResponse

---

POST /api/lps/{lp_id}/publish

LPを公開状態にする。

認証: Admin 監査ログ: あり

レスポンス: LPResponse

備考: LP公開時に全選手へ通知が送信される。既に公開済みの場合は400エラー。

---

POST /api/lps/{lp_id}/unpublish

LPを非公開にする。

認証: Admin 監査ログ: あり レスポンス: LPResponse

---

GET /api/lps/{lp_id}/preview

LPのHTMLプレビュー。

認証: 必要 レスポンス: text/html (HTMLResponse)

---

7. Fans (ファン)

GET /api/fans/

ファン一覧取得。Player は自分のファンのみ。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
player_id	string	No	選手フィルタ (Admin のみ)
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (FanResponse[]):

フィールド	型	説明
id	string	ファンUUID
player_id	string	選手UUID
name	string	ファン名
has_phone	bool	電話番号登録済
has_email	bool	メール登録済
memo	string	メモ
created_at	datetime	作成日時

---

GET /api/fans/dig-out

掘り起こしリスト。最近チケットを購入していないファンの一覧。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	デフォルト	説明
player_id	string	No	-	選手フィルタ
days_threshold	int	No	90	最終購入からの日数閾値

レスポンス (DigOutListResponse[]):

フィールド	型	説明
fan_id	string	ファンUUID
fan_name	string	ファン名
last_purchase_date	datetime?	最終購入日
total_purchases	int	購入回数
total_amount	int	購入総額 (JPY)
days_since_last_purchase	int?	最終購入からの日数

---

GET /api/fans/{fan_id}

ファン詳細取得。Player は自分のファンのみアクセス可。

認証: 必要 レスポンス: FanResponse

---

GET /api/fans/{fan_id}/purchases

ファンの購入履歴。イベント名付きのチケット一覧。

認証: 必要

レスポンス:

[
  {
    "ticket_id": "uuid",
    "event_id": "uuid",
    "event_name": "イベント名",
    "seat_type": "S席",
    "quantity": 2,
    "amount": 16000,
    "route": "lp",
    "paid": true,
    "purchased_at": "2026-03-01T12:00:00Z"
  }
]

---

POST /api/fans/

ファン登録。電話番号・メールはAES-256で暗号化。

認証: 必要 監査ログ: あり

リクエストボディ (FanCreate):

フィールド	型	必須	説明
player_id	string	Yes	選手UUID
name	string	Yes	ファン名
phone	string	No	電話番号 (AES-256暗号化)
email	string	No	メール (AES-256暗号化)
memo	string	No	メモ

レスポンス: FanResponse

---

PUT /api/fans/{fan_id}

ファン更新。

認証: 必要 監査ログ: あり

リクエストボディ (FanUpdate):

フィールド	型	必須	説明
name	string	No	ファン名
phone	string	No	電話番号
email	string	No	メール
memo	string	No	メモ

レスポンス: FanResponse

---

DELETE /api/fans/{fan_id}

ファン削除。Player は自分のファンのみ削除可。

認証: 必要 監査ログ: あり レスポンス: SuccessResponse

---

8. Sponsors (スポンサー)

GET /api/sponsors/

スポンサー一覧取得。

認証: 必要 アクセス制御: Admin=全件, Player=自分の紐付け分, Association=全件

クエリパラメータ:

パラメータ	型	必須	説明
player_id	string	No	選手フィルタ
concept_status	ConceptStatus	No	パイプラインステータスフィルタ
search	string	No	会社名検索
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (SponsorResponse[]):

フィールド	型	説明
id	string	スポンサーUUID
player_id	string	選手UUID
company_name	string	会社名
industry	string	業種
contact_name	string	担当者名
has_contact_phone	bool	電話番号登録済
has_contact_email	bool	メール登録済
contract_amount	int	契約金額 (JPY)
contract_start	date?	契約開始日
contract_end	date?	契約終了日
concept_status	ConceptStatus	パイプラインステータス
memo	string	メモ
is_public_to_association	bool	協会公開フラグ
created_at	datetime	作成日時

---

GET /api/sponsors/{sponsor_id}

スポンサー詳細取得。Player は自分の紐付けのみ。

認証: 必要 レスポンス: SponsorResponse

---

POST /api/sponsors/

スポンサー作成。連絡先はAES-256暗号化。

認証: Admin 監査ログ: あり

リクエストボディ (SponsorCreate):

フィールド	型	必須	説明
player_id	string	Yes	選手UUID
company_name	string	Yes	会社名
industry	string	No	業種
contact_name	string	No	担当者名
contact_phone	string	No	電話番号 (暗号化)
contact_email	string	No	メール (暗号化)
contract_amount	int	No	契約金額 (JPY)
contract_start	date	No	契約開始日
contract_end	date	No	契約終了日
memo	string	No	メモ

レスポンス: SponsorResponse

---

PUT /api/sponsors/{sponsor_id}

スポンサー更新。

認証: Admin 監査ログ: あり リクエストボディ: SponsorUpdate (SponsorCreate と同じフィールド + concept_status, is_public_to_association, 全てOptional) レスポンス: SponsorResponse

---

DELETE /api/sponsors/{sponsor_id}

スポンサー論理削除 (deleted_at タイムスタンプを設定)。

認証: Admin 監査ログ: あり レスポンス: SuccessResponse

---

PUT /api/sponsors/{sponsor_id}/concept-status

コンセプトパイプラインステータス更新。

認証: Admin または Association 監査ログ: あり

クエリパラメータ:

パラメータ	型	必須	説明
concept_status	ConceptStatus	Yes	新しいステータス
concept_memo	string	No	ステータス変更メモ

レスポンス: SponsorResponse

---

POST /api/sponsors/{sponsor_id}/publish

協会への公開/非公開をトグル。

認証: Admin または Association 監査ログ: あり

クエリパラメータ:

パラメータ	型	必須	説明
is_public	bool	Yes	協会への公開フラグ

レスポンス: SponsorResponse

---

POST /api/sponsors/{sponsor_id}/approve

スポンサーの公開承認。

認証: Admin 監査ログ: あり

クエリパラメータ:

パラメータ	型	必須	説明
is_approved	bool	Yes	公開承認フラグ

レスポンス: SponsorResponse

---

9. Kickbacks (キックバック)

GET /api/kickbacks/

キックバック一覧。Player はアクセス不可 (403)。

認証: Admin/Association (Player は403)

クエリパラメータ:

パラメータ	型	必須	説明
sponsor_id	string	No	スポンサーフィルタ
paid	bool	No	支払済フィルタ
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (KickbackResponse[]):

フィールド	型	説明
id	string	キックバックUUID
sponsor_id	string	スポンサーUUID
player_id	string	選手UUID
contract_amount	int	契約金額 (JPY)
kickback_rate	float	キックバック率 (0.0-1.0)
kickback_amount	int	キックバック金額 (自動計算)
payment_due_date	date?	支払期日
paid_flag	bool	支払済フラグ
paid_date	date?	支払日
memo	string	メモ
created_at	datetime	作成日時

---

GET /api/kickbacks/{kickback_id}

キックバック詳細。Player はアクセス不可 (403)。

認証: Admin/Association レスポンス: KickbackResponse

---

POST /api/kickbacks/

キックバック作成。kickback_amount は contract_amount * kickback_rate で自動計算。

認証: Admin/Association 監査ログ: あり

リクエストボディ (KickbackCreate):

フィールド	型	必須	説明
sponsor_id	string	Yes	スポンサーUUID
player_id	string	Yes	選手UUID
contract_amount	int	Yes	契約金額 (JPY)
kickback_rate	float	Yes	キックバック率 (0.0-1.0)
payment_due_date	date	No	支払期日
memo	string	No	メモ

レスポンス: KickbackResponse

---

PUT /api/kickbacks/{kickback_id}

キックバック更新。金額再計算あり。

認証: Admin/Association 監査ログ: あり リクエストボディ: KickbackCreate レスポンス: KickbackResponse

---

POST /api/kickbacks/{kickback_id}/mark-paid

キックバックを支払済にマーク。

認証: Admin/Association 監査ログ: あり レスポンス: SuccessResponse

---

GET /api/kickbacks/summary

キックバックサマリー統計。Player はアクセス不可 (403)。

認証: Admin/Association

レスポンス:

{
  "total_contract_amount": 10000000,
  "total_kickback_amount": 1000000,
  "paid_amount": 600000,
  "unpaid_amount": 400000,
  "total_records": 15
}

---

GET /api/kickbacks/export-csv

キックバックデータをCSVエクスポート。暗号化された振込先情報を復号して出力。

認証: Admin 監査ログ: あり レスポンス: text/csv (StreamingResponse, ファイル名: kickbacks_export.csv)

CSV列: ID, Sponsor, Player, Contract Amount, Kickback Rate, Kickback Amount, Payment Due Date, Paid, Paid Date, Transfer Info, Memo, Created At

---

10. Notifications (通知)

GET /api/notifications/

通知一覧取得 (自分宛て)。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
unread_only	bool	No	未読のみ
type	NotificationType	No	通知種別フィルタ
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (NotificationResponse[]):

フィールド	型	説明
id	string	通知UUID
type	NotificationType	通知種別
title	string	タイトル
body	string	本文
is_read	bool	既読フラグ
sent_at	datetime?	送信日時
created_at	datetime	作成日時

---

GET /api/notifications/unread-count

未読通知数を取得。

認証: 必要

レスポンス:

{
  "unread_count": 5
}

---

POST /api/notifications/{notification_id}/read

通知を既読にする。

認証: 必要 レスポンス: SuccessResponse

---

POST /api/notifications/read-all

全通知を既読にする。

認証: 必要 レスポンス: SuccessResponse

---

POST /api/notifications/send

通知を送信。SMSの場合はTwilio経由、Web Pushの場合はプッシュサービス経由。

認証: Admin 監査ログ: あり

リクエストボディ (SendNotificationRequest):

フィールド	型	必須	説明
player_id	string	No	送信先選手UUID
fan_id	string	No	送信先ファンUUID
type	NotificationType	Yes	通知種別
title	string	Yes	タイトル
body	string	Yes	本文

レスポンス: SuccessResponse

---

POST /api/notifications/bulk-deadline

販売締切が近いイベントの選手へ一斉アラート送信。

認証: Admin 監査ログ: あり

リクエストボディ (BulkDeadlineRequest):

フィールド	型	必須	デフォルト	説明
days_ahead	int	No	3	締切何日前にアラートするか (1-30)

レスポンス:

{
  "events_notified": 3,
  "sent_count": 3
}

---

11. Rankings (ランキング)

GET /api/rankings/sales

チケット販売ランキング。Admin は枚数・金額も表示、それ以外は順位のみ。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	デフォルト	説明
event_id	string	No	-	イベントフィルタ
limit	int	No	20	取得件数 (最大100)

レスポンス (SalesRankingEntry[]):

フィールド	型	説明
rank	int	順位
player_id	string	選手UUID
player_name	string	選手名
player_slug	string	URLスラグ
profile_image_url	string?	プロフィール画像URL
total_quantity	int?	販売枚数 (Admin のみ)
total_amount	int?	販売金額 (Admin のみ)

---

GET /api/rankings/views

LPページビューランキング。Admin はビュー数も表示。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
event_id	string	No	イベントフィルタ
period	string	No	期間 (daily, weekly, monthly)
limit	int	No	取得件数

レスポンス (PageViewRankingEntry[]):

フィールド	型	説明
rank	int	順位
player_id	string	選手UUID
player_name	string	選手名
total_views	int?	ビュー数 (Admin のみ)

---

GET /api/rankings/daily/{event_id}

イベントの日別販売データ。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
start_date	date	No	開始日
end_date	date	No	終了日

レスポンス (DailySalesEntry[]):

フィールド	型	説明
date	date	日付
quantity	int	販売枚数
amount	int	販売金額 (JPY)

---

GET /api/rankings/daily

前日の販売ランキング。

認証: 必要

レスポンス (DailyRankingEntry[]):

フィールド	型	説明
rank	int	順位
player_id	string	選手UUID
player_name	string	選手名
date	string	日付 (前日)
total_quantity	int?	販売枚数 (Admin のみ)
total_amount	int?	販売金額 (Admin のみ)

---

12. Admin (管理者)

全エンドポイントに Admin ロールが必要。ルーター全体に require_role(PlayerRole.ADMIN) が適用されている。

GET /api/admin/dashboard

管理ダッシュボードの統計情報。

認証: Admin

レスポンス (DashboardStats):

フィールド	型	説明
total_players	int	登録選手数
total_events	int	イベント数
total_tickets_sold	int	販売チケット枚数
total_revenue	int	総売上 (JPY)
active_lps	int	公開中LP数
total_fans	int	ファン数
total_sponsors	int	スポンサー数
pending_kickbacks	int	未払いキックバック数

---

GET /api/admin/audit-logs

監査ログ照会。

認証: Admin

クエリパラメータ:

パラメータ	型	必須	説明
actor_id	string	No	操作者フィルタ
action	string	No	アクションフィルタ
resource_type	string	No	リソースタイプフィルタ
page	int	No	ページ番号
per_page	int	No	件数 (デフォルト50, 最大200)

レスポンス (AuditLogEntry[]):

フィールド	型	説明
id	string	ログID
actor_id	string	操作者ID
actor_role	string	操作者ロール
action	string	アクション
resource_type	string	リソースタイプ
resource_id	string	リソースID
details	object	詳細情報
ip_address	string?	IPアドレス
created_at	string	日時

---

GET /api/admin/players

選手管理一覧。チケット販売数を含む。

認証: Admin

レスポンス (PlayerManagementResponse[]):

フィールド	型	説明
id	string	選手UUID
login_id	string	ログインID
name	string	表示名
role	string	ロール
is_locked	bool	ロック状態
failed_attempts	int	ログイン失敗回数
total_tickets_sold	int	販売チケット数

---

POST /api/admin/players

選手アカウント作成。

認証: Admin 監査ログ: あり リクエストボディ: PlayerCreate レスポンス: PlayerResponse

---

POST /api/admin/players/{player_id}/lock

選手アカウントをロック (ログイン不可にする)。

認証: Admin レスポンス: SuccessResponse

---

POST /api/admin/players/{player_id}/unlock

選手アカウントのロックを解除し、失敗回数をリセット。

認証: Admin レスポンス: SuccessResponse

---

POST /api/admin/players/{player_id}/reset-password

選手のパスワードを一時パスワードにリセット。

認証: Admin 監査ログ: あり レスポンス: SuccessResponse (一時パスワードがメッセージに含まれる)

---

13. Concept Pipeline (営業パイプライン)

スポンサー営業パイプラインの管理。全エンドポイントに Association ロールが必要。

GET /api/concept/leads

リード (営業案件) 一覧。暗号化された連絡先を復号して返す。

認証: Association

クエリパラメータ:

パラメータ	型	必須	説明
status	ConceptStatus	No	ステータスフィルタ
search	string	No	会社名検索
player_id	string	No	選手フィルタ
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (LeadResponse[]):

フィールド	型	説明
sponsor_id	string	スポンサーUUID
company_name	string	会社名
industry	string	業種
contact_name	string	担当者名
contact_phone	string?	電話番号 (復号済)
contact_email	string?	メール (復号済)
player_id	string	担当選手UUID
player_name	string	担当選手名
concept_status	ConceptStatus	ステータス
concept_memo	string	メモ
contract_amount	int	契約金額 (JPY)
is_public_to_association	bool	協会公開フラグ
created_at	datetime	作成日時

---

GET /api/concept/leads/pipeline-summary

パイプラインサマリー (ステージ別件数と潜在金額)。

認証: Association

レスポンス (PipelineSummary):

フィールド	型	説明
lead	int	リード数
proposal	int	提案中数
negotiation	int	交渉中数
contracted	int	契約済数
declined	int	辞退数
total_potential_value	int	潜在合計金額 (JPY)

---

PUT /api/concept/leads/{sponsor_id}/advance

リードを次のステージへ進行。lead -> proposal -> negotiation -> contracted。

認証: Association 監査ログ: あり レスポンス: LeadResponse

エラー: 辞退済み・最終ステージの場合は400エラー。

---

PUT /api/concept/leads/{sponsor_id}/status

リードのステータスを直接設定。

認証: Association 監査ログ: あり

クエリパラメータ:

パラメータ	型	必須	説明
concept_status	ConceptStatus	Yes	新しいステータス
concept_memo	string	No	メモ

レスポンス: LeadResponse

---

POST /api/concept/leads/{sponsor_id}/publish

協会への公開/非公開トグル。

認証: Association 監査ログ: あり

クエリパラメータ:

パラメータ	型	必須	説明
is_public	bool	Yes	公開フラグ

レスポンス: SuccessResponse

---

GET /api/concept/kickbacks

キックバック一覧 (営業ビュー)。

認証: Association

クエリパラメータ:

パラメータ	型	必須	説明
sponsor_id	string	No	スポンサーフィルタ
paid	bool	No	支払済フィルタ
page	int	No	ページ番号
per_page	int	No	件数

レスポンス: KickbackResponse[]

---

POST /api/concept/kickbacks

キックバック作成 (営業側)。

認証: Association 監査ログ: あり リクエストボディ: KickbackCreate レスポンス: KickbackResponse

---

14. Rewards (報酬)

LP経由チケット販売の選手報酬 (レベニューシェア) 管理。

GET /api/rewards/

報酬一覧。Admin は全件、Player は自分の分のみ。

認証: 必要

クエリパラメータ:

パラメータ	型	必須	説明
event_id	string	No	イベントフィルタ
page	int	No	ページ番号
per_page	int	No	件数

レスポンス (RewardResponse[]):

フィールド	型	説明
id	string	報酬UUID
player_id	string	選手UUID
player_name	string	選手名
event_id	string	イベントUUID
event_name	string	イベント名
lp_id	string	LP UUID
total_revenue	int	LP総売上 (JPY)
reward_rate	float	報酬率
reward_amount	int	報酬金額 (JPY)
status	string	ステータス (pending/confirmed/paid)
paid_flag	bool	支払済フラグ
paid_date	datetime?	支払日
memo	string	メモ
created_at	datetime	作成日時

---

GET /api/rewards/my

自分の収入サマリー。手売り売上とLP報酬の合計。

認証: 必要

レスポンス (PlayerIncomeSummary):

フィールド	型	説明
player_id	string	選手UUID
personal_sales_total	int	手売り合計 (JPY)
lp_reward_confirmed	int	確定済みLP報酬 (JPY)
lp_reward_estimated	int	見込みLP報酬 (JPY)
cumulative_received	int	受取済み合計 (JPY)
pending_amount	int	未払い確定報酬 (JPY)

---

POST /api/rewards/calculate/{event_id}

イベントの報酬を一括計算。LP経由販売 x 報酬率で算出し、player_rewards テーブルにupsert。

認証: Admin 監査ログ: あり

レスポンス: list[dict] (計算結果の配列)

---

POST /api/rewards/{reward_id}/mark-paid

報酬を支払済にマーク。選手に支払完了通知を送信。

認証: Admin 監査ログ: あり レスポンス: SuccessResponse

備考: アプリ内通知も自動作成される。

---

GET /api/rewards/summary

報酬サマリー。全体の支払済/未払い合計とイベント別内訳。

認証: Admin

レスポンス (RewardSummary):

フィールド	型	説明
total_unpaid	int	未払い合計 (JPY)
total_paid	int	支払済合計 (JPY)
total_rewards	int	報酬総額 (JPY)
by_event	list[dict]	イベント別内訳

by_event の各要素:

{
  "event_id": "uuid",
  "event_name": "イベント名",
  "paid": 100000,
  "unpaid": 50000,
  "total": 150000
}

---

ミドルウェア

ミドルウェア	説明
CORS	許可オリジン: localhost:3000, sb-ticket.com, sb-ticket-dev.aidreams-factory.com
SecurityHeaders	セキュリティヘッダー付与
RateLimit	レートリミット
Audit	監査ログ記録

---

セキュリティ

項目	実装
認証	JWT (HttpOnly Cookie, SameSite=Lax, Secure)
パスワード	bcrypt (cost 12)
個人情報暗号化	AES-256 (電話番号, メール, 振込先情報)
Webhook検証	HMAC-SHA256署名
アカウントロック	5回ログイン失敗で自動ロック
RBAC	ロールベースアクセス制御 (player, admin, association)
監査ログ	全変更操作を記録