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 선택
- Settings → Essentials로 이동합니다.
- Property Management System (PMS) Integration까지 스크롤합니다.
- Cloudbeds 카드를 클릭합니다.
- 선택을 확인하는 체크 표시(✓)가 나타납니다.
2단계: 연결 시작
- Connect to Cloudbeds 버튼을 클릭합니다.
- Cloudbeds 새 창이 열립니다.
3단계: 액세스 승인
- Cloudbeds 계정에 로그인합니다.
- AVA가 요청하는 권한을 검토합니다.
- Authorize 또는 Allow를 클릭합니다.
- 창이 자동으로 닫힙니다.
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:addon | add-on 카탈로그 데이터 보기 |
이 업데이트 이전에 Cloudbeds를 연결했다면, 부여된 읽기 범위를 새로 고치기 위해 다시 연결하세요.
4단계: 연결 확인
- AVA 설정으로 돌아갑니다.
- "Finalizing connection..."이 표시될 때까지 기다립니다(5-10초).
- 상태에 녹색 체크 표시가 나타납니다.
- 메시지에 "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 created | AVA가 알림을 받고 도착 전 메시지를 예약할 수 있습니다 |
| Reservation dates changed | AVA가 예약된 메시지를 업데이트합니다 |
| Check-in/out status | 상태가 실시간으로 동기화됩니다 |
AVA에서 예약을 볼 때 시스템은 Cloudbeds에서 최신 데이터를 직접 가져옵니다. 덕분에 항상 최신 정보를 볼 수 있습니다.
데이터는 주로 Cloudbeds → AVA 방향으로 흐릅니다. AVA에서 변경한 투숙객 업데이트(예: 체크인 완료)는 Cloudbeds로 다시 전송됩니다.
투숙객 및 직원에게 미치는 영향
- 투숙객 양식은 Cloudbeds 규칙에 맞춰 조정됩니다. 필수 필드와 숨김 필드는 Cloudbeds 설정에 따라 바뀌므로 투숙객은 필요한 내용만 보게 됩니다.
- 예약 조회는 Cloudbeds를 사용합니다. Cloudbeds가 연결되어 있지 않으면 투숙객 조회 단계가 실패합니다.
- 객실 상태 설정은 하우스키핑 동기화에만 영향을 줍니다. 이 설정은 AVA에서 객실을 깨끗함으로 표시할 때 AVA가 Cloudbeds에 Clean 또는 Inspected 상태를 보낼지 제어합니다. 투숙객 UI는 바뀌지 않습니다.
- AVA는 항목 접근 권한과 읽기 전용 add-on 접근 권한을 요청합니다.
write:addon은 의도적으로 제외됩니다. - Cloudbeds 읽기 범위는 다시 연결할 때 갱신됩니다. 이전 권한으로 hotel, rate, taxes/fees 데이터가 필요하면 다시 연결하세요.
Cloudbeds 연결 해제
다음 경우에만 연결을 해제하세요.
- 다른 PMS로 전환하는 경우
- Cloudbeds 계정을 바꾸는 경우
- 동기화 문제를 해결하는 경우
연결 해제 방법:
- Settings → Essentials로 이동합니다.
- Disconnect from Cloudbeds를 클릭합니다.
- 메시지가 표시되면 확인합니다.
연결을 해제하면 모든 동기화가 즉시 중단됩니다. 기존 데이터는 남아 있지만 업데이트되지 않습니다.
문제 해결
연결이 "Connecting..."에서 멈춤
- 30초 기다립니다.
- 페이지를 새로고침합니다.
- 인터넷 연결을 확인합니다.
- 다른 브라우저를 사용해 봅니다.
- 팝업 차단을 해제합니다.
Cloudbeds OAuth 오류 메시지
보이는 내용: 배너에 Cloudbeds OAuth 메시지가 표시됩니다.
해결:
- 먼저 메시지를 읽습니다.
- 위의 표와 대조합니다.
- 상태, code, token exchange가 언급되면 Cloudbeds에 다시 연결합니다.
- Cloudbeds 관리자 계정을 사용 중인지 확인합니다.
- token exchange가 계속 실패하면 redirect URI를 확인합니다.
배너에는 이제 가능하면 Cloudbeds 자체의 오류 세부 정보가 표시됩니다. 지원 요청을 시작할 때 더 명확한 출발점이 됩니다.
예약이 동기화되지 않음
- 초기 동기화를 위해 15분 기다립니다.
- 연결 상태가 녹색인지 확인합니다.
- 연결을 해제한 뒤 다시 연결해 봅니다.
- Cloudbeds에 예약이 실제로 존재하는지 확인합니다.
카탈로그 탭이 표시되지 않음
보이는 내용: Items 또는 Add-ons 탭이 없습니다.
해결:
- Rooms 페이지를 다시 엽니다.
- Cloudbeds 권한 프롬프트를 확인합니다.
- 프롬프트에
read:item,write:item,read:addon이 포함되어 있는지 확인합니다. - 카탈로그 탭이 계속 보이지 않으면 지원팀에 문의합니다.
팝업 창이 열리지 않음
- 브라우저의 팝업 차단 설정을 확인합니다.
- AVA 도메인의 팝업을 허용합니다.
- 다른 브라우저나 시크릿 모드를 사용해 봅니다.
보안
- 연결에는 안전한 OAuth 2.0이 사용됩니다
- 비밀번호는 AVA에 저장되지 않습니다
- Cloudbeds에서 언제든지 액세스를 취소할 수 있습니다
- 90일 동안 사용하지 않으면 연결이 만료됩니다
자주 묻는 질문
여러 Cloudbeds 숙소를 연결할 수 있나요? 아니요, AVA 계정당 하나의 숙소만 연결할 수 있습니다.
연결을 해제하면 데이터가 삭제되나요? 아니요, 기존 데이터는 남아 있지만 업데이트되지 않습니다.
직원도 Cloudbeds를 연결할 수 있나요? 아니요, 관리자만 PMS 연결을 관리할 수 있습니다.
아직 막혔나요?
다음에 해당하면 success@vouch-technologies.com으로 문의하세요.
- ❌ 다시 연결한 뒤에도 같은 OAuth 오류가 계속 표시됩니다.
- ❌ Cloudbeds가 authorization code exchange를 계속 거부합니다.
- ❌ 올바른 Cloudbeds 계정 또는 숙소를 확인할 수 없습니다.
함께 보내면 좋은 정보:
- 오류 배너 스크린샷
- 문제가 시작된 시간
- AVA에 표시된 정확한 메시지