본문으로 건너뛰기

Cloudbeds PMS 통합 설정

빠른 설정

Cloudbeds 연결은 보통 약 10분 걸립니다. Cloudbeds는 이제 항목 접근 권한, 읽기 전용 add-on 접근 권한, 그리고 hotel, rate, taxes/fees에 대한 읽기 권한을 요청합니다.

이 가이드는 Cloudbeds를 연결하는 방법을 안내합니다. 예약, 게스트, 하우스키핑, 결제, 객실, 통화, 호텔, 요금, 세금 데이터를 동기화 상태로 유지합니다. Cloudbeds가 연결을 거부하면 AVA가 오류 배너에 정확한 이유를 표시합니다.

위치​

Settings → Essentials → Property Management System (PMS) Integration

시작하기 전에​

다음이 필요합니다.

  • 관리자 권한이 있는 Cloudbeds 계정
  • Cloudbeds 로그인 자격 증명
  • 타사 앱 승인을 위한 권한
경고

숙소당 한 번에 하나의 Cloudbeds 계정만 연결할 수 있습니다.

Cloudbeds에 연결하기​

1단계: PMS로 Cloudbeds 선택​

  1. Settings → Essentials로 이동합니다.
  2. Property Management System (PMS) Integration까지 스크롤합니다.
  3. Cloudbeds 카드를 클릭합니다.
  4. 선택을 확인하는 체크 표시(✓)가 나타납니다.

2단계: 연결 시작​

  1. Connect to Cloudbeds 버튼을 클릭합니다.
  2. 새 창이 Cloudbeds로 열립니다.

3단계: 액세스 승인​

  1. Cloudbeds 계정에 로그인합니다.
  2. AVA가 요청하는 권한을 검토합니다.
  3. Authorize 또는 Allow를 클릭합니다.
  4. 창이 자동으로 닫힙니다.

AVA는 이제 다음 권한을 요청합니다.

권한AVA에서 사용하는 용도
read:hotel호텔 메타데이터 보기
read:guest게스트 상세 정보 보기
write:guest게스트 상세 정보 업데이트
read:housekeeping하우스키핑 데이터 보기
write:housekeeping하우스키핑 데이터 업데이트
read:rate요금제 데이터 보기
read:payment결제 데이터 보기
write:payment결제 데이터 업데이트
read:reservation예약 데이터 보기
write:reservation예약 데이터 업데이트
read:room객실 데이터 보기
write:room객실 데이터 업데이트
read:currency숙소 통화 설정 읽기
read:taxesAndFees세금 및 수수료 데이터 보기
read:item항목 카탈로그 데이터 보기
write:item항목 카탈로그 데이터 업데이트
read:addonadd-on 카탈로그 데이터 보기
이전 연결

이 업데이트 이전에 Cloudbeds를 연결했다면, 부여된 읽기 범위를 새로 고치기 위해 다시 연결하세요.

4단계: 연결 확인​

  1. AVA 설정으로 돌아갑니다.
  2. "Finalizing connection..."이 표시될 때까지 기다립니다(5~10초).
  3. 상태에 녹색 체크 표시가 나타납니다.
  4. 메시지에 "Cloudbeds Account Linked"가 표시됩니다.

연결이 완료되었습니다! 🎉

Cloudbeds OAuth 오류​

Cloudbeds가 연결을 차단하면 AVA가 사람이 읽을 수 있는 메시지를 표시합니다. 이제는 일반적인 실패만 보고 원인을 추측할 필요가 없습니다.

보이는 내용의미할 일
Cloudbeds did not return the OAuth state parameter.Cloudbeds 콜백에 state 데이터가 없습니다.연결을 다시 시작합니다.
Cloudbeds did not return an authorization code.Cloudbeds가 인증을 끝내지 못했습니다.Settings → Essentials에서 다시 연결합니다.
Cloudbeds OAuth state verification failed.콜백 state가 유효하지 않거나 만료되었습니다.Cloudbeds에 다시 연결합니다.
Could not identify the merchant for this Cloudbeds link.AVA가 콜백을 숙소와 매칭하지 못했습니다.올바른 숙소에 로그인되어 있는지 확인합니다.
Cloudbeds rejected the authorization code exchange.Cloudbeds가 토큰 교환을 차단했습니다.scope와 redirect URI를 확인한 뒤 다시 시도합니다.
Failed to link Cloudbeds account.AVA가 백엔드 오류를 매핑하지 못했습니다.전체 메시지를 복사해 지원팀에 문의합니다.

자동으로 동기화되는 항목​

Cloudbeds는 실시간 업데이트를 위해 webhooks를 사용합니다. Cloudbeds에서 변경이 발생하면 AVA에 즉시 알림이 전달됩니다.

이벤트발생 내용
Reservation createdAVA가 알림을 받고 도착 전 메시지를 예약할 수 있습니다
Reservation dates changedAVA가 예약된 메시지를 업데이트합니다
Check-in/out status상태가 실시간으로 동기화됩니다

AVA에서 예약을 볼 때 시스템은 Cloudbeds에서 최신 데이터를 직접 가져옵니다. 덕분에 항상 최신 정보를 볼 수 있습니다.

정보

데이터는 주로 Cloudbeds → AVA 방향으로 흐릅니다. AVA에서 변경한 게스트 업데이트(예: 체크인 완료)는 Cloudbeds로 다시 전송됩니다.

Cloudbeds 읽기 보호

여러 직원이 같은 Cloudbeds 데이터를 동시에 요청하면 AVA는 하나의 읽기 요청을 공유합니다. Cloudbeds가 같은 access 또는 success:false 오류를 다시 반환하면 AVA는 반복 재시도를 잠시 멈춥니다.

Cloudbeds 도착 시간 업데이트

주 게스트가 동기화되면 AVA는 예약의 estimated arrival time을 Cloudbeds v3로 보낼 수 있습니다. 동반 게스트는 그 시간을 업데이트하지 않습니다. 잘못되었거나 없거나 비어 있는 시간은 무시하므로 AVA가 기존 PMS 데이터를 지우지 않습니다. 옵션 업데이트가 실패하거나 Cloudbeds가 이를 지원하지 않아도 게스트 동기화는 계속 성공합니다.

게스트와 직원에게 미치는 영향​

  • 게스트 양식은 Cloudbeds 규칙에 맞춰 조정됩니다. 필수 필드와 숨김 필드는 Cloudbeds 설정에 따라 바뀌므로 게스트는 필요한 내용만 보게 됩니다.
  • 예약 조회는 Cloudbeds를 사용합니다. Cloudbeds가 연결되어 있지 않으면 게스트 조회 단계가 실패합니다.
  • 예약 출처 라벨은 Cloudbeds 출처 메타데이터를 사용할 수 있습니다. 예약에 sourceName이 없으면 AVA는 연결된 Cloudbeds 출처 이름으로 대체합니다.
  • Source collect는 연결된 출처 레코드가 있으면 그 값을 사용합니다. 호텔과 채널 출처 동작을 Cloudbeds 설정과 일치하게 유지합니다.
  • Channel-collect 인보이스는 계속 면제 상태로 유지됩니다. Cloudbeds v3가 채널 수금 인보이스를 면제 처리하면 AVA는 지급 총액을 0으로 표시하고 Streamliner에 면제를 보여 줍니다.
  • 객실 상태 설정은 하우스키핑 동기화에만 영향을 줍니다. 이 설정은 AVA에서 객실을 깨끗함으로 표시할 때 AVA가 Cloudbeds에 Clean 또는 Inspected 상태를 보낼지 제어합니다. 게스트 UI는 바뀌지 않습니다.
  • 도착 예정 시간 동기화는 주 게스트만 사용합니다. 동반 게스트와 잘못된 시간은 무시되므로 AVA는 PMS 값을 그대로 유지합니다.
  • AVA는 항목 접근 권한과 읽기 전용 add-on 접근 권한을 요청합니다. write:addon은 의도적으로 제외됩니다.
  • Cloudbeds 읽기 범위는 다시 연결할 때 갱신됩니다. 이전 권한으로 hotel, rate, taxes/fees 데이터가 필요하면 다시 연결하세요.

Cloudbeds 연결 해제​

다음 경우에만 연결을 해제하세요.

  • 다른 PMS로 전환하는 경우
  • Cloudbeds 계정을 바꾸는 경우
  • 동기화 문제를 해결하는 경우

연결 해제 방법:

  1. Settings → Essentials로 이동합니다.
  2. Disconnect from Cloudbeds를 클릭합니다.
  3. 메시지가 표시되면 확인합니다.
주의

연결을 해제하면 모든 동기화가 즉시 중단됩니다. 기존 데이터는 남아 있지만 업데이트되지는 않습니다.

문제 해결​

연결이 "Connecting..."에서 멈춤​

  1. 30초 기다립니다.
  2. 페이지를 새로고칩니다.
  3. 인터넷 연결을 확인합니다.
  4. 다른 브라우저를 사용해 봅니다.
  5. 팝업 차단을 해제합니다.

Cloudbeds OAuth 오류 메시지​

보이는 내용: 배너에 Cloudbeds OAuth 메시지가 표시됩니다.

해결:

  1. 먼저 메시지를 읽습니다.
  2. 위 표와 대조합니다.
  3. 상태, code, token exchange가 언급되면 Cloudbeds에 다시 연결합니다.
  4. Cloudbeds 관리자 계정을 사용 중인지 확인합니다.
  5. token exchange가 계속 실패하면 redirect URI를 확인합니다.
정보

배너에는 이제 가능하면 Cloudbeds 자체의 오류 세부 정보가 표시됩니다. 지원 요청을 시작할 때 더 명확한 출발점이 됩니다.

예약이 동기화되지 않음​

  1. 초기 동기화를 위해 15분 기다립니다.
  2. 연결 상태가 녹색인지 확인합니다.
  3. 연결을 해제한 뒤 다시 연결해 봅니다.
  4. Cloudbeds에 예약이 실제로 존재하는지 확인합니다.

Cloudbeds 액세스 또는 숙소 오류​

보이는 내용: You don't have access to property ID 같은 메시지가 표시되거나, 같은 Cloudbeds 오류가 바로 다시 나타납니다.

이유: 연결된 Cloudbeds 계정이 해당 숙소를 읽지 못합니다. AVA도 반복 재시도를 잠시 멈춥니다.

해결:

  1. 올바른 Cloudbeds 숙소에 로그인되어 있는지 확인합니다.

  2. Cloudbeds 관리자에게 숙소 액세스와 권한을 확인해 달라고 요청합니다.

  3. 다시 Refresh를 누르기 전에 1분 정도 기다립니다.

  4. 메시지가 계속 반복되면 지원팀에 문의합니다.

    ✓ Cloudbeds 액세스 문제가 해결되면 다음 새로고침은 성공해야 합니다.

카탈로그 탭이 표시되지 않음​

보이는 내용: Items 또는 Add-ons 탭이 없습니다.

해결:

  1. Rooms 페이지를 다시 엽니다.
  2. Cloudbeds 권한 프롬프트를 확인합니다.
  3. 프롬프트에 read:item, write:item, read:addon이 포함되어 있는지 확인합니다.
  4. 카탈로그 탭이 계속 보이지 않으면 지원팀에 문의합니다.

팝업 창이 열리지 않음​

  1. 브라우저의 팝업 차단 설정을 확인합니다.
  2. AVA 도메인의 팝업을 허용합니다.
  3. 다른 브라우저나 시크릿 모드를 사용해 봅니다.

보안​

  • 연결에는 안전한 OAuth 2.0이 사용됩니다
  • 비밀번호는 AVA에 저장되지 않습니다
  • Cloudbeds에서 언제든지 액세스를 취소할 수 있습니다
  • 90일 동안 사용하지 않으면 연결이 만료될 수 있습니다

자주 묻는 질문​

여러 Cloudbeds 숙소를 연결할 수 있나요? 아니요. AVA 계정당 한 숙소만 연결할 수 있습니다.

연결을 해제하면 데이터가 삭제되나요? 아니요. 기존 데이터는 남아 있지만 업데이트되지는 않습니다.

직원도 Cloudbeds를 연결할 수 있나요? 아니요. PMS 연결은 관리자만 관리할 수 있습니다.