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