시작하기

뮤즈캣 봇 API는 내 계정의 권한으로 오락실을 생성하고 정보를 수정하는 자동화용 API입니다. 봇 페이지의 키 관리에서 이름을 입력하고 키를 발급하세요. 발급된 키는 한 번만 표시됩니다.

현재 발급 권한은 뮤즈캣 초기 서포터, 뮤즈캣 서포터, 뮤즈캣 디자이너, 뮤즈캣 모더레이터, 뮤즈캣 개발자 계정에 있습니다. 오락실 공식 계정 권한만으로는 발급할 수 없습니다. 계정이 활성 상태이고 가입을 완료해야 하며, 권한은 매 요청마다 다시 확인합니다.

연결과 인증

백엔드 주소에 /bot/v1을 붙여 요청하고 Authorization: Bearer <봇 키> 헤더로 인증합니다. 아래 예제는 로컬 백엔드를 사용합니다. 배포 환경에서는 해당 환경의 HTTPS 백엔드 주소로 바꾸세요. 웹사이트 주소나 /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, 쿼리 문자열, 공개 코드, 로그에 넣지 마세요. 봇 키는 웹 로그인 토큰으로 교환할 수 없으며 일반 계정 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=ko-KR로 게임 버전 ID를 확인하고, 오락실 상세를 expand=game으로 조회합니다. 상세 응답의 game.state_id가 현재 게임 상태 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 사진을 한 요청에 최대 10개까지 photos 필드로 업로드할 수 있습니다. 업로드만으로는 오락실 사진 목록이 바뀌지 않습니다. 응답의 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 위치 인증을 제공하지 않습니다. 지도 좌표는 방문 증거가 아니며, 공개 요건이 부족하면 초안을 유지해야 합니다.

제한과 오류 처리

• 키에는 자동 만료 기한이 없습니다. 이전에 발급한 키도 동일하며, 폐기하지 않은 키는 계정당 최대 5개입니다.
• 키 하나당 분당 60개의 허용 요청이 가능합니다. IP 기반 제한도 별도로 적용됩니다.
• 400: 필수 값, ID, JSON 형식 등 요청 내용을 확인하세요.
• 401: 키의 폐기 여부, 발급 계정의 현재 권한 및 상태를 확인하세요. 비밀번호 로그인으로 자동 우회하지 마세요.
• 403: 해당 오락실을 수정하거나 공개할 권한이 있는지 확인하세요.
• 404: 경로, 대상 ID, 공개 범위를 확인하세요.
• 409: 최신 편집 상태를 다시 조회하고 변경분을 재계산하세요.
• 429: Retry-After 헤더를 따르세요. 키 제한 응답은 60초를 안내합니다.
• 네트워크 오류나 서버 오류가 난 편집 요청은 실제 적용 여부를 조회한 뒤 재시도하세요.

계정 관리, 메시지, 출석, 방문 인증, 메모 편집, 모더레이션 API는 봇 키로 사용할 수 없습니다.

이력과 개인정보

봇 편집의 작성자는 키를 발급한 내 계정이며, 오락실 수정 이력에는 닉네임 옆 BOT 배지가 표시됩니다. 봇 이름은 소유자에게만 공개되며 타인의 API 응답에는 포함되지 않습니다. 내 봇 페이지에서는 봇별로 편집 이력을 확인할 수 있습니다. 봇 작업은 경험치를 지급하지 않습니다.

키 교체와 폐기

새 키를 발급해 봇 설정을 교체한 뒤 기존 키를 폐기하세요. 키 관리에서 폐기하면 이후 요청은 거부됩니다. 이미 수락된 요청은 완료될 수 있으며 과거 편집 이력은 유지됩니다.

키 관리에는 로그인한 웹 세션이 필요합니다. 봇 키로 키 목록 조회, 새 키 발급, 키 폐기를 수행할 수 없습니다.