외부 연동 (Third Party Integration)

개요

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

String!

서비스 제공자 이름

String!

연동 범위 (숙박 시설 ID)

String

서비스 타입

Date!

생성 일시

[ThirdPartyProperty]

연동 속성 목록

ThirdPartyProperty

외부 서비스의 속성 정보를 나타냅니다.

속성 ID

String!

서비스 제공자 이름

String!

속성 타입 (예: “room_mapping”, “config”)

String

외부 시스템의 ID

VPMS 내부 ID (예: 객실 ID)

String

속성 이름

String

속성 설명

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
    }
  }
}

파라미터

ID!

required

숙박 시설 ID

ThirdPartyProviderType

서비스 타입 필터 (선택사항)

CMS: CMS만 조회
PMS: PMS만 조회
DoorLock: 도어락만 조회
Parking: 주차 시스템만 조회
등등…

응답

[ThirdPartyApp!]!

연동된 외부 서비스 목록

예제

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

query {
  getAccommodationThirdPartyApps(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    type: DoorLock
  ) {
    id
    provider
    type
    properties {
      id
      type
      thirdPartyId
      relatedId
    }
  }
}

{
  "data": {
    "getAccommodationThirdPartyApps": [
      {
        "id": "01HQKS9V8X",
        "provider": "SamsungSmartAccess",
        "type": "DoorLock",
        "createdAt": "2025-01-01T00:00:00Z",
        "properties": [
          {
            "id": "01HQKS9V8Y",
            "type": "room_mapping",
            "thirdPartyId": "SSA-ROOM-101",
            "relatedId": "01HQKS9V8Z"
          }
        ]
      }
    ]
  }
}

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
  )
}

파라미터

ThirdPartyProvider!

required

외부 서비스 제공자예: SamsungSmartAccess, HotelStory, AmanoKorea

String

OAuth 인증 코드 (OAuth 방식 사용 시)

String

인증 정보 (API 키 또는 토큰)

String!

required

연동 범위 (일반적으로 숙박 시설 ID)

ID!

required

숙박 시설 ID

Boolean

기존 연동을 갱신할지 여부 (기본값: false)

응답

Boolean

연동 성공 여부

예제

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

mutation {
  thirdPartySignIn(
    provider: AmanoKorea
    credential: "api_key_abc123"
    scope: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
  )
}

mutation {
  thirdPartySignIn(
    provider: HotelStory
    credential: "new_api_key_def456"
    scope: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    isRenew: true
  )
}

{
  "data": {
    "thirdPartySignIn": true
  }
}

deleteAccommodationThirdParty

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

GraphQL Signature

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

파라미터

ID!

required

숙박 시설 ID

ThirdPartyProvider!

required

해제할 외부 서비스 제공자

응답

Boolean

해제 성공 여부

예제

mutation {
  deleteAccommodationThirdParty(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    provider: SamsungSmartAccess
  )
}

{
  "data": {
    "deleteAccommodationThirdParty": true
  }
}

연동 해제 시 해당 서비스와 관련된 모든 속성(properties)도 함께 삭제됩니다.

registerThirdPartyProperty

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

GraphQL Signature

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

파라미터

ID!

required

숙박 시설 ID

String!

required

외부 서비스 제공자 이름

String!

required

속성 타입일반적인 타입:

room_mapping: 객실 매핑
config: 설정
credential: 인증 정보
webhook: 웹훅 설정

String

외부 시스템의 ID

VPMS 내부 관련 ID

String

속성 이름

String

속성 설명

String

추가 데이터 (JSON 문자열)

응답

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
  }
}

mutation {
  registerThirdPartyProperty(input: {
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    provider: "AmanoKorea"
    type: "config"
    name: "주차 시스템 설정"
    data: "{\"apiEndpoint\": \"https://api.amano.kr\", \"timeout\": 30000}"
  }) {
    id
    type
    name
    data
  }
}

{
  "data": {
    "registerThirdPartyProperty": {
      "id": "01HQKS9V8Y",
      "type": "room_mapping",
      "thirdPartyId": "SSA-ROOM-101",
      "relatedId": "01HQKS9V8Z"
    }
  }
}

modifyThirdPartyProperty

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

GraphQL Signature

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

파라미터

ID!

required

수정할 속성 ID

ThirdPartyPropertyInput!

required

수정할 속성 정보 (변경할 필드만 포함)

응답

ThirdPartyProperty

수정된 속성 정보

예제

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

{
  "data": {
    "modifyThirdPartyProperty": {
      "id": "01HQKS9V8Y",
      "thirdPartyId": "SSA-ROOM-102",
      "name": "102호 도어락 매핑 (수정)"
    }
  }
}

deleteThirdPartyProperty

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

GraphQL Signature

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

파라미터

ID!

required

삭제할 속성 ID

응답

Boolean

삭제 성공 여부

devThirdPartyTest

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

GraphQL Signature

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

파라미터

테스트할 숙박 시설 ID

Boolean

테스트 플래그

이 API는 개발 환경에서만 사용 가능하며, 프로덕션 환경에서는 비활성화됩니다.

사용 흐름

외부 서비스 연동 설정

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

객실-도어락 매핑 예시

도어락 시스템 연동

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

객실별 매핑 등록

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

매핑 확인

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

에러 처리

연동 실패

인증 정보가 유효하지 않습니다. 올바른 API 키 또는 OAuth 코드를 사용하세요.

외부 서비스가 현재 사용 불가능합니다. 나중에 다시 시도하세요.

이미 연동된 서비스입니다. isRenew: true를 사용하여 갱신하세요.

속성 등록 실패

먼저 thirdPartySignIn으로 서비스를 연동해야 합니다.

지원하지 않는 속성 타입입니다. 서비스 문서를 확인하세요.

​개요

​Enums

​ThirdPartyProvider

​ThirdPartyProviderType

​Types

​ThirdPartyApp

​ThirdPartyProperty

​Queries

​getAccommodationThirdPartyApps

​GraphQL Signature

​파라미터

​응답

​예제

​Mutations

​thirdPartySignIn

​GraphQL Signature

​파라미터

​응답

​예제

​deleteAccommodationThirdParty

​GraphQL Signature

​파라미터

​응답

​예제

​registerThirdPartyProperty

​GraphQL Signature

​파라미터

​응답

​예제

​modifyThirdPartyProperty

​GraphQL Signature

​파라미터

​응답

​예제

​deleteThirdPartyProperty

​GraphQL Signature

​파라미터

​응답

​devThirdPartyTest

​GraphQL Signature

​파라미터

​사용 흐름

​외부 서비스 연동 설정

​객실-도어락 매핑 예시

​지원 서비스별 연동 방법

​도어락 시스템

​주차 시스템

​PMS

​에러 처리

​연동 실패

​속성 등록 실패

​관련 API

개요

Enums

ThirdPartyProvider

ThirdPartyProviderType

Types

ThirdPartyApp

ThirdPartyProperty

Queries

getAccommodationThirdPartyApps

GraphQL Signature

파라미터

응답

예제

Mutations

thirdPartySignIn

GraphQL Signature

파라미터

응답

예제

deleteAccommodationThirdParty

GraphQL Signature

파라미터

응답

예제

registerThirdPartyProperty

GraphQL Signature

파라미터

응답

예제

modifyThirdPartyProperty

GraphQL Signature

파라미터

응답

예제

deleteThirdPartyProperty

GraphQL Signature

파라미터

응답

devThirdPartyTest

GraphQL Signature

파라미터

사용 흐름

외부 서비스 연동 설정

객실-도어락 매핑 예시

지원 서비스별 연동 방법

도어락 시스템

주차 시스템

PMS

에러 처리

연동 실패

속성 등록 실패

관련 API