はじめに

Musecat ボット API は、自分のアカウントの権限でゲームセンターの登録と情報編集を自動化します。ボットページのキー管理で名前を入力し、キーを発行してください。シークレットは一度だけ表示されます。

発行できるのは創設サポーター、サポーター、デザイナー、モデレーター、開発者です。ゲームセンター公式アカウントの権限だけでは発行できません。有効な登録済みアカウントが必要で、権限はリクエストごとに確認されます。

接続と認証

バックエンドのオリジンに /bot/v1 を付け、Authorization: Bearer <ボットキー> ヘッダーを送信します。以下はローカル環境の例です。公開環境では、その環境の HTTPS バックエンドアドレスに置き換えてください。Web サイトのオリジンや /api プロキシは使用しません。

export MUSECAT_API_URL="http://localhost:8090"
export MUSECAT_BOT_KEY="YOUR_BOT_KEY"

curl --fail-with-body \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  "$MUSECAT_API_URL/bot/v1/arcade/drafts"

キーは環境変数またはシークレットストアに保管してください。URL、クエリ文字列、公開コード、ログに含めないでください。Web セッションへの交換や、通常のアカウント API、PocketBase コレクション API での使用はできません。

対応 API

以下のパスにはすべて /bot/v1 を付けます。一覧にない API は使用できません。

参照には URL クエリ、通常の編集には JSON 本文と Content-Type: application/json を使用します。写真のアップロードは multipart 形式です。公開範囲や作成者の権限など、既存のアクセス条件も適用されます。

登録と参照

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Example Arcade","address":"Tokyo","location":{"lat":35.6895,"lon":139.6917}}' \
  "$MUSECAT_API_URL/bot/v1/arcade/new"

応答の id がゲームセンター ID です。登録直後は非公開の下書きで、自動公開されません。自分の下書きは GET /arcade/drafts、下書きの詳細は GET /arcade/draft?id=ARCADE_ID&expand=all、公開済みの詳細は GET /arcade?id=ARCADE_ID&expand=all で取得します。

登録の応答が途切れた場合は、まず下書き一覧を確認してください。無条件の再送信は重複登録につながります。

基本情報と営業時間の編集

詳細応答の basic.id を base_basic_id に指定し、参照したバージョンを基準に編集します。変更するフィールドだけを送ってください。例の ID は実際の値に置き換えます。

curl --fail-with-body -X PUT \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  -H "Content-Type: application/json" \
  --data '{"arcade":"ARCADE_ID","base_basic_id":"CURRENT_BASIC_ID","direction":"Basement entrance"}' \
  "$MUSECAT_API_URL/bot/v1/arcade/basic"

PUT /arcade/hour には以下のように曜日別の営業時間を送ります。時刻は24時間制の HHMM 整数です。省略した曜日は変更されません。

{"arcade":"ARCADE_ID","Monday":{"start":1000,"end":2300}}

ゲーム情報の編集

GET /game/catalog?locale=ja-JP でバージョン ID を確認し、expand=game で詳細を取得します。現在の状態 ID は game.state_id です。ゲームが未登録なら base_state_id は空文字列にします。

PUT /arcade/game は全件置換の games ではなく、add、modify、remove の差分を受け取ります。modify には既存項目の id、remove には削除する項目の ID を指定します。game はシリーズ ID ではなくカタログのバージョン ID です。

{
  "arcade": "ARCADE_ID",
  "base_state_id": "CURRENT_GAME_STATE_ID",
  "add": [{
    "game": "VERSION_ID_FROM_CATALOG",
    "quantity": 1,
    "location": "1F",
    "price": {"currency": "JPY", "type": "free", "list": [], "accept": []},
    "tag": []
  }],
  "modify": [],
  "remove": []
}

409 の場合は最新の状態を取得し、差分を再計算してください。古い差分に新しい状態 ID だけを付けて再送信しないでください。

写真のアップロードと適用

PNG、APNG、JPEG の写真を、photos フィールドで1リクエストにつき最大10枚アップロードできます。アップロードだけでは写真一覧は変わりません。応答の uploaded[].atomId を集め、最終的な一覧を PUT /arcade/photo に送ってください。既存の写真を残す場合は、その atom ID も含めます。一部だけ失敗した場合は失敗したファイルだけを再送信してください。

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $MUSECAT_BOT_KEY" \
  -F "arcade=ARCADE_ID" -F "photos=@photo.jpg" \
  "$MUSECAT_API_URL/bot/v1/arcade/photo/upload"

{"arcade":"ARCADE_ID","photos":["ATOM_ID_FROM_UPLOAD"]}

下書きの公開

GET /arcade/public?arcade=ARCADE_ID で条件を確認してから、PUT /arcade/public に {"arcade":"ARCADE_ID"} を送ります。公開できるのは作成者だけです。登録済みゲームと、アカウントレベルに応じた写真、連絡先または営業時間の条件を満たす必要があります。

ボット API では GPS 位置認証を行えません。地図の座標は訪問の証拠にはなりません。条件を満たさない場合は下書きを非公開のまま保持してください。

制限とエラー処理

• キーに自動の有効期限はありません。発行済みのキーも同様です。1アカウントにつき未失効のキーは最大5個です。
• 1キーにつき1分間に60件の受理リクエストが可能です。IP ごとの制限も適用されます。
• 400：必須項目、ID、JSON 形式を確認してください。
• 401：失効の有無と発行アカウントの権限と状態を確認してください。パスワードログインに自動で切り替えないでください。
• 403：編集または公開の権限を確認してください。
• 404：パス、対象 ID、公開範囲を確認してください。
• 409：最新の状態を取得して差分を再計算してください。
• 429：Retry-After に従ってください。キーの制限では60秒を指定します。
• 編集中に通信エラーやサーバーエラーが起きた場合は、反映済みかを確認してから再試行してください。

アカウント管理、メッセージ、出席、訪問認証、メモ編集、モデレーション API は対象外です。

履歴とプライバシー

編集者はキーを発行したアカウントのままです。ゲームセンターの履歴にはニックネームの横に BOT バッジを表示します。ボット名は所有者だけに公開され、他人向けの API 応答には含まれません。自分のボットページではボット別に履歴を確認できます。ボットの操作に経験値は付与されません。

キーの交換と失効

新しいキーを発行してボットの設定を更新し、その後キー管理で古いキーを失効させてください。以後のリクエストは拒否されますが、受理済みのリクエストは完了する場合があります。過去の編集履歴は保持されます。

キー管理には Web ログインが必要です。ボットキーでキーの一覧取得、発行、失効はできません。