Skip to main content

개요

Third Party 도메인은 외부 시스템과의 통합 기능을 제공합니다. PMS, CMS, 도어락, 주차 시스템 등 다양한 외부 서비스와의 연동을 지원합니다.

Enums

ThirdPartyProvider

지원하는 외부 서비스 제공자 목록입니다.
  • SamsungSmartAccess: 삼성 스마트 도어락
  • SanhaWings: 산하 Wings PMS
  • TheMR: The MR 솔루션
  • AmanoKorea: 아마노 주차 시스템
  • NicePark: 나이스 주차 시스템
  • TlLincoln: TL Lincoln 솔루션
  • V_Booking: Vendit 부킹 엔진
  • HotelStory: 호텔스토리 PMS
  • V_CMS: Vendit CMS

ThirdPartyProviderType

외부 서비스의 카테고리를 정의합니다.
  • CMS: 콘텐츠 관리 시스템
  • PMS: 숙박 관리 시스템
  • Facility: 시설 관리
  • Parking: 주차 관리
  • Guest: 게스트 관리
  • BookingEngine: 예약 엔진
  • DoorLock: 도어락 시스템

Types

ThirdPartyApp

외부 서비스 앱 정보를 나타냅니다.
id
ID
앱 ID
provider
String!
서비스 제공자 이름
scope
String!
연동 범위 (숙박 시설 ID)
type
String
서비스 타입
createdAt
Date!
생성 일시
properties
[ThirdPartyProperty]
연동 속성 목록

ThirdPartyProperty

외부 서비스의 속성 정보를 나타냅니다.
id
ID
속성 ID
provider
String!
서비스 제공자 이름
type
String!
속성 타입 (예: “room_mapping”, “config”)
thirdPartyId
String
외부 시스템의 ID
VPMS 내부 ID (예: 객실 ID)
name
String
속성 이름
description
String
속성 설명
data
String
추가 데이터 (JSON 문자열)

Queries

getAccommodationThirdPartyApps

특정 숙박 시설에 연동된 외부 서비스 목록을 조회합니다.

GraphQL Signature

query GetAccommodationThirdPartyApps(
  $accommodationId: ID!
  $type: ThirdPartyProviderType
) {
  getAccommodationThirdPartyApps(
    accommodationId: $accommodationId
    type: $type
  ) {
    id
    provider
    scope
    type
    createdAt
    properties {
      id
      provider
      type
      thirdPartyId
      relatedId
      name
      description
      data
    }
  }
}

파라미터

accommodationId
ID!
required
숙박 시설 ID
type
ThirdPartyProviderType
서비스 타입 필터 (선택사항)
  • CMS: CMS만 조회
  • PMS: PMS만 조회
  • DoorLock: 도어락만 조회
  • Parking: 주차 시스템만 조회
  • 등등…

응답

apps
[ThirdPartyApp!]!
연동된 외부 서비스 목록

예제

query {
  getAccommodationThirdPartyApps(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
  ) {
    id
    provider
    type
    createdAt
    properties {
      id
      type
      name
    }
  }
}

Mutations

thirdPartySignIn

외부 서비스에 로그인하고 연동을 설정합니다.

GraphQL Signature

mutation ThirdPartySignIn(
  $provider: ThirdPartyProvider!
  $code: String
  $credential: String
  $scope: String!
  $accommodationId: ID!
  $isRenew: Boolean
) {
  thirdPartySignIn(
    provider: $provider
    code: $code
    credential: $credential
    scope: $scope
    accommodationId: $accommodationId
    isRenew: $isRenew
  )
}

파라미터

provider
ThirdPartyProvider!
required
외부 서비스 제공자예: SamsungSmartAccess, HotelStory, AmanoKorea
code
String
OAuth 인증 코드 (OAuth 방식 사용 시)
credential
String
인증 정보 (API 키 또는 토큰)
scope
String!
required
연동 범위 (일반적으로 숙박 시설 ID)
accommodationId
ID!
required
숙박 시설 ID
isRenew
Boolean
기존 연동을 갱신할지 여부 (기본값: false)

응답

result
Boolean
연동 성공 여부

예제

mutation {
  thirdPartySignIn(
    provider: SamsungSmartAccess
    code: "oauth_auth_code_xyz123"
    scope: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
  )
}

deleteAccommodationThirdParty

특정 외부 서비스 연동을 해제합니다.

GraphQL Signature

mutation DeleteAccommodationThirdParty(
  $accommodationId: ID!
  $provider: ThirdPartyProvider!
) {
  deleteAccommodationThirdParty(
    accommodationId: $accommodationId
    provider: $provider
  )
}

파라미터

accommodationId
ID!
required
숙박 시설 ID
provider
ThirdPartyProvider!
required
해제할 외부 서비스 제공자

응답

result
Boolean
해제 성공 여부

예제

mutation {
  deleteAccommodationThirdParty(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    provider: SamsungSmartAccess
  )
}
연동 해제 시 해당 서비스와 관련된 모든 속성(properties)도 함께 삭제됩니다.

registerThirdPartyProperty

외부 서비스 속성을 등록합니다.

GraphQL Signature

mutation RegisterThirdPartyProperty($input: ThirdPartyPropertyInput!) {
  registerThirdPartyProperty(input: $input) {
    id
    provider
    type
    thirdPartyId
    relatedId
    name
    description
    data
  }
}

파라미터

input.accommodationId
ID!
required
숙박 시설 ID
input.provider
String!
required
외부 서비스 제공자 이름
input.type
String!
required
속성 타입일반적인 타입:
  • room_mapping: 객실 매핑
  • config: 설정
  • credential: 인증 정보
  • webhook: 웹훅 설정
input.thirdPartyId
String
외부 시스템의 ID
VPMS 내부 관련 ID
input.name
String
속성 이름
input.description
String
속성 설명
input.data
String
추가 데이터 (JSON 문자열)

응답

property
ThirdPartyProperty
등록된 속성 정보

예제

mutation {
  registerThirdPartyProperty(input: {
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    provider: "SamsungSmartAccess"
    type: "room_mapping"
    thirdPartyId: "SSA-ROOM-101"
    relatedId: "01HQKS9V8Z"
    name: "101호 도어락 매핑"
    description: "101호 객실과 삼성 도어락 연결"
  }) {
    id
    type
    thirdPartyId
    relatedId
  }
}

modifyThirdPartyProperty

외부 서비스 속성을 수정합니다.

GraphQL Signature

mutation ModifyThirdPartyProperty(
  $id: ID!
  $input: ThirdPartyPropertyInput!
) {
  modifyThirdPartyProperty(id: $id, input: $input) {
    id
    provider
    type
    thirdPartyId
    relatedId
    name
    description
    data
  }
}

파라미터

id
ID!
required
수정할 속성 ID
input
ThirdPartyPropertyInput!
required
수정할 속성 정보 (변경할 필드만 포함)

응답

property
ThirdPartyProperty
수정된 속성 정보

예제

mutation {
  modifyThirdPartyProperty(
    id: "01HQKS9V8Y"
    input: {
      accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      provider: "SamsungSmartAccess"
      type: "room_mapping"
      thirdPartyId: "SSA-ROOM-102"
      name: "102호 도어락 매핑 (수정)"
    }
  ) {
    id
    thirdPartyId
    name
  }
}

deleteThirdPartyProperty

외부 서비스 속성을 삭제합니다.

GraphQL Signature

mutation DeleteThirdPartyProperty($id: ID!) {
  deleteThirdPartyProperty(id: $id)
}

파라미터

id
ID!
required
삭제할 속성 ID

응답

result
Boolean
삭제 성공 여부

devThirdPartyTest

개발/테스트 목적으로 외부 서비스 연동을 테스트합니다.

GraphQL Signature

mutation DevThirdPartyTest($accommodationId: ID, $boolData: Boolean) {
  devThirdPartyTest(accommodationId: $accommodationId, boolData: $boolData)
}

파라미터

accommodationId
ID
테스트할 숙박 시설 ID
boolData
Boolean
테스트 플래그
이 API는 개발 환경에서만 사용 가능하며, 프로덕션 환경에서는 비활성화됩니다.

사용 흐름

외부 서비스 연동 설정

  1. 서비스 연동: thirdPartySignIn으로 외부 서비스 인증
  2. 속성 등록: registerThirdPartyProperty로 객실 매핑, 설정 등록
  3. 연동 확인: getAccommodationThirdPartyApps로 연동 상태 확인

객실-도어락 매핑 예시

1

도어락 시스템 연동

mutation {
  thirdPartySignIn(
    provider: SamsungSmartAccess
    credential: "api_key_xyz"
    scope: "01HQKS9V8X"
    accommodationId: "01HQKS9V8X"
  )
}
2

객실별 매핑 등록

mutation {
  registerThirdPartyProperty(input: {
    accommodationId: "01HQKS9V8X"
    provider: "SamsungSmartAccess"
    type: "room_mapping"
    thirdPartyId: "SSA-ROOM-101"
    relatedId: "room_01HQKS9V8Z"
    name: "101호 매핑"
  }) {
    id
  }
}
3

매핑 확인

query {
  getAccommodationThirdPartyApps(
    accommodationId: "01HQKS9V8X"
    type: DoorLock
  ) {
    properties {
      thirdPartyId
      relatedId
      name
    }
  }
}

지원 서비스별 연동 방법

도어락 시스템

삼성 스마트 도어락 (SamsungSmartAccess)
  • 인증 방식: API 키
  • 필수 속성: room_mapping (객실-도어락 매핑)
TL Lincoln
  • 인증 방식: OAuth 2.0
  • 필수 속성: room_mapping, config

주차 시스템

아마노 주차 (AmanoKorea)
  • 인증 방식: API 키
  • 필수 속성: config (엔드포인트, 타임아웃 설정)
나이스 파크 (NicePark)
  • 인증 방식: API 키
  • 필수 속성: config, webhook

PMS

호텔스토리 (HotelStory)
  • 인증 방식: OAuth 2.0
  • 필수 속성: room_mapping, rate_mapping
산하 Wings (SanhaWings)
  • 인증 방식: API 키
  • 필수 속성: room_mapping

에러 처리

연동 실패

INVALID_CREDENTIALS
인증 정보가 유효하지 않습니다. 올바른 API 키 또는 OAuth 코드를 사용하세요.
PROVIDER_NOT_AVAILABLE
외부 서비스가 현재 사용 불가능합니다. 나중에 다시 시도하세요.
DUPLICATE_INTEGRATION
이미 연동된 서비스입니다. isRenew: true를 사용하여 갱신하세요.

속성 등록 실패

INTEGRATION_NOT_FOUND
먼저 thirdPartySignIn으로 서비스를 연동해야 합니다.
INVALID_PROPERTY_TYPE
지원하지 않는 속성 타입입니다. 서비스 문서를 확인하세요.

관련 API