개요
Core 서비스의 숙박시설 도메인은 숙박시설(Accommodation) 정보 관리, 키오스크 설정, 테마 관리, 게시물 관리 등 숙박시설 운영에 필요한 전반적인 기능을 제공합니다.권한 체계
숙박시설 API는 다음과 같은 권한 레벨을 사용합니다:- OWNER: 숙박시설 소유자 (모든 권한)
- MANAGER: 관리자 (키오스크, 테마, 게시물 관리)
- STAFF: 직원 (기본 조회)
- MAID: 객실 관리자 (청소 및 객실 상태 관리)
Queries
getMyAccommodations
현재 사용자가 관리하는 숙박시설 목록을 조회합니다.GraphQL Signature
권한 요구사항
파트너 계정 이상의 권한 필요
응답
숙박시설 고유 ID (ULID 형식)
숙박시설 이름
주소 (도로명/지번)
상세 주소
대표 연락처
고객 서비스 연락처
활성화 상태
홈 화면 기본 숙박시설 여부
예제
getSingleAccommodation
특정 숙박시설의 상세 정보를 조회합니다.GraphQL Signature
파라미터
조회할 숙박시설 ID
권한 요구사항
- 숙박시설 관리 권한 (MAID 이상) 또는
- 서드파티 API 접근 권한 (
ACC_ROOMTYPE_READ)
응답
숙박시설 설정 옵션 배열
defaultCheckOut: 기본 체크아웃 시간defaultInitTemperature: 기본 초기 온도- 기타 커스텀 설정
숙박시설에 속한 객실 목록
숙박시설에 설치된 키오스크 목록
숙박시설 상태:
inactive: 비활성화needKiosk: 키오스크 설치 필요error: 키오스크 오류 발생normal: 정상 운영
예제
getSingleAccommodationByName
숙박시설 이름으로 공개 정보를 조회합니다.GraphQL Signature
파라미터
조회할 숙박시설 이름 (정확히 일치해야 함)
특징
인증 없이 접근 가능한 공개 API입니다. 민감한 정보(등록번호, 암호화키 등)는 반환되지 않습니다.
getBriefAccommodationById
숙박시설 ID로 공개 정보를 조회합니다.GraphQL Signature
파라미터
조회할 숙박시설 ID
getAccommodationKiosks
숙박시설의 키오스크 목록을 조회합니다.GraphQL Signature
파라미터
숙박시설 ID
권한 요구사항
관리자 이상의 권한 필요
응답
키오스크 상태:
NORMAL: 정상ERROR: 오류OFFLINE: 오프라인
getAccommodationArticles
숙박시설 게시물 목록을 조회합니다.GraphQL Signature
파라미터
숙박시설 ID
게시물 타입:
ACC_INTRO: 숙박시설 소개KIOSK_INTRO: 키오스크 안내KIOSK_MAIN_INTRO: 키오스크 메인 화면TERMS_INTRO: 이용약관
응답
첨부 이미지 파일명 배열
조회수 (IP 기반 중복 방지)
Mutations
createAccommodation
새로운 숙박시설을 생성합니다.GraphQL Signature
파라미터
숙박시설 이름 (중복 불가)
대표 연락처
주소
상세 주소
고객 서비스 연락처
등록자 이름
사업자등록번호
권한 요구사항
파트너 관리자 권한 필요
특징
- 생성 시 자동으로 기본 RoomType 생성
- 생성자가 자동으로 OWNER 권한으로 등록
- 초기 상태는
isActive: false(관리자 승인 필요)
예제
updateAccommodation
숙박시설 정보를 수정합니다.GraphQL Signature
파라미터
수정할 숙박시설 ID
숙박시설 이름
설정 옵션 배열
- 존재하지 않는 키는 새로 생성
- 존재하는 키는 값 업데이트
권한 요구사항
소유자 권한 필요
제약사항
예제
deleteAccommodation
숙박시설을 삭제합니다.GraphQL Signature
파라미터
삭제할 숙박시설 ID
권한 요구사항
소유자 권한 필요
addUserToAccommodation
숙박시설에 사용자를 추가합니다.GraphQL Signature
파라미터
추가할 사용자 ID
숙박시설 ID
부여할 권한:
OWNER: 소유자MANAGER: 관리자STAFF: 직원 (기본값)MAID: 객실 관리자
권한 요구사항
소유자 권한 또는 시스템 관리자 권한 필요
deleteUserFromAccommodation
숙박시설에서 사용자를 제거합니다.GraphQL Signature
제약사항
activateSingleAccommodation
숙박시설을 활성화합니다.GraphQL Signature
권한 요구사항
시스템 관리자 권한 필요
setHomeAccommodation
사용자의 기본(홈) 숙박시설을 설정합니다.GraphQL Signature
특징
- 이전 홈 숙박시설은 자동으로
isHome: false로 변경 - 사용자당 1개의 홈 숙박시설만 설정 가능
키오스크 관리
createAccommodationKiosk
숙박시설에 새 키오스크를 생성합니다.GraphQL Signature
파라미터
숙박시설 ID
키오스크 이름 (숙박시설 내 중복 불가)
키오스크 타입
설치 위치
초기 상태
권한 요구사항
소유자 권한 필요
updateAccommodationKiosk
키오스크 정보를 수정합니다.GraphQL Signature
권한 요구사항
관리자 이상의 권한 필요
deleteAccommodationKiosk
키오스크를 삭제합니다.GraphQL Signature
권한 요구사항
소유자 권한 필요
setKioskOptions
키오스크 설정 옵션을 변경합니다.GraphQL Signature
파라미터
키오스크 ID
설정할 옵션 배열
특징
- 존재하지 않는 키는 새로 생성
- 존재하는 키는 값 업데이트
- 캐시 자동 갱신
이미지 업로드
uploadAuthImages
키오스크 인증용 이미지를 업로드합니다.GraphQL Signature
파라미터
키오스크 ID
업로드할 이미지 파일 배열
제약사항
- 허용 형식: PNG, JPEG, JPG, GIF
- 최대 크기: 20MB/파일
- 업로드된 이미지는 인증용 스토리지에 저장
응답
업로드된 이미지의 사전 서명된 URL 배열
uploadKioskBannerImages
키오스크 배너 이미지를 업로드하고 관리합니다.GraphQL Signature
파라미터
키오스크 ID
새로 업로드할 이미지 파일 배열
유지할 기존 파일명 배열 (이 배열에 없는 기존 파일은 삭제됨)
권한 요구사항
관리자 이상의 권한 필요
게시물 관리
createAccommodationArticle
숙박시설 게시물을 생성합니다.GraphQL Signature
파라미터
숙박시설 ID
게시물 제목
게시물 내용
게시물 타입:
ACC_INTRO: 숙박시설 소개KIOSK_INTRO: 키오스크 안내KIOSK_MAIN_INTRO: 키오스크 메인 화면TERMS_INTRO: 이용약관
권한 요구사항
관리자 이상의 권한 또는 시스템 관리자 권한 필요
uploadAccommodationArticleImages
게시물에 이미지를 업로드합니다.GraphQL Signature
특징
- 새 이미지 업로드 및 기존 이미지 관리
persistFiles에 없는 기존 파일은 자동 삭제- 이미지는 게시물별 디렉토리에 저장
updateAccommodationArticle
게시물을 수정합니다.GraphQL Signature
deleteAccommodationArticle
게시물을 삭제합니다.GraphQL Signature
테마 관리
createTheme
숙박시설에 새 테마를 생성합니다.GraphQL Signature
파라미터
테마 이름 (숙박시설 내 중복 불가)
숙박시설 ID
권한 요구사항
관리자 이상의 권한 필요
updateTheme
테마 정보를 수정합니다.GraphQL Signature
deleteTheme
테마를 삭제합니다.GraphQL Signature
OCR 및 얼굴 인식
verifyIdByOCR
신분증 이미지를 OCR로 인식하고 검증합니다.GraphQL Signature
파라미터
신분증 이미지 파일
권한 요구사항
파트너 관리자 권한 필요
응답
신분증 유효성 검증 결과
신분증 타입 (자동 감지)
주민등록번호 등 식별자
인식된 이름
개인정보 마스킹 영역 좌표
신분증 영역 좌표
특징
- Google Vision API를 사용한 OCR
- 국가 자동 감지 (한국, 외국인등록증 등)
- 개인정보 자동 마스킹 좌표 제공
- 보안을 위해 처리 후 이미지 버퍼 즉시 삭제
requestFaceDetection
이미지에서 얼굴을 감지하고 연령/성별을 추정합니다.GraphQL Signature
파라미터
얼굴 감지할 이미지 파일 배열
제약사항
- 허용 형식: PNG, JPEG, JPG, GIF
- 최대 크기: 10MB/파일
응답
감지된 얼굴 정보 배열
추정 연령 하한
추정 연령 상한
추정 연령 (하한 + 30%)
성별:
MALE 또는 FEMALE얼굴 영역 X 좌표 (비율)
얼굴 영역 Y 좌표 (비율)
얼굴 영역 너비 (비율)
얼굴 영역 높이 (비율)
특징
- AWS Rekognition을 사용한 얼굴 감지
- 여러 이미지 동시 처리 가능
- 이미지당 여러 얼굴 감지 지원
오디오 옵션 관리
createAccommodationAudioOption
숙박시설 오디오 옵션을 생성합니다.GraphQL Signature
updateAccommodationAudioOption
오디오 옵션을 수정합니다.GraphQL Signature
deleteAccommodationAudioOption
오디오 옵션을 삭제합니다.GraphQL Signature
유효성 검증
validateAccommodationInfo
숙박시설 정보의 유효성을 검증합니다 (중복 확인 등).GraphQL Signature
파라미터
검증할 숙박시설 이름
응답
유효성 검증 결과:
true: 사용 가능한 이름false: 이미 존재하는 이름
예제
라이선스 관리
activateLicense
숙박시설의 제품 라이선스를 활성화합니다.GraphQL Signature
파라미터
숙박시설 ID
제품 타입:
VPMS: 숙박 관리 시스템
inactivateLicense
숙박시설의 제품 라이선스를 비활성화합니다.GraphQL Signature
시스템 제어
sendCcuControlPacket
CCU(중앙 제어 장치)에 제어 패킷을 전송합니다.GraphQL Signature
sendKioskControlPacket
키오스크에 제어 패킷을 전송합니다.GraphQL Signature
checkAccommodationRoomDevicesIntegrity
숙박시설의 객실 장치 무결성을 검사합니다.GraphQL Signature
checkAllAccommodationsRoomDevicesIntegrity
모든 활성화된 숙박시설의 객실 장치 무결성을 검사합니다.GraphQL Signature
권한 요구사항
슈퍼 관리자 권한 필요
에러 코드
DATA_NOT_FOUND_ON_ID
요청한 ID의 데이터를 찾을 수 없습니다.
DUPLICATED_DATA_FOUND
중복된 데이터가 존재합니다 (이름, 키오스크명 등).
REQUIRED_ACTIVATED_ACCOMMODATION
활성화된 숙박시설에서만 수행 가능한 작업입니다.
LAST_OWNER_CANNOT_BE_DELETED
마지막 소유자는 삭제할 수 없습니다.
INVALID_PARAMETER
잘못된 파라미터입니다.
EXTERNAL_API_ERROR
외부 API (Google Vision, AWS Rekognition) 호출 중 오류가 발생했습니다.
관련 API
- 객실 관리 API - 숙박시설의 객실 관리
- 예약 관리 API - 숙박시설의 예약 관리
- 사용자 관리 API - 숙박시설 사용자 권한 관리
- 마일리지 API - 숙박시설의 마일리지 설정