에어비앤비 인증 구현
에어비앤비는 숙소마다 호스트의 에어비앤비 계정 승인(OAuth) 이 필요한 채널입니다. 호스트가 직접 로그인해 접근 권한을 승인해야 ONDA가 그 계정 권한으로 리스팅 조회·요금재고 전송·예약 수신을 할 수 있습니다.
공급사 시스템이 대신 처리할 수 없고, 반드시 호스트 본인의 브라우저에서 진행됩니다. 이미 승인한 적 있는 계정이면 승인 화면이 생략되고 바로 완료되기도 합니다.
- 채널 메타의
requires_cms_authorization이true인 채널이 대상입니다 → 직연동 레거시 채널 오픈 - 에어비앤비의
channel_id는GET /gds/vendor/channels로 확인하세요. 아래 예시는133을 사용합니다.
언제 필요한가
| 시점 | 인증 필요 여부 |
|---|---|
| 숙소를 에어비앤비에 처음 연동할 때 | 필요 — 최초 1회 |
| 호스트가 다른 에어비앤비 계정으로 바꿀 때 | 필요 — 재인증 |
| 토큰 만료 | 불필요 — ONDA가 자동 갱신합니다 |
전체 온보딩에서의 위치는 아래와 같습니다. 인증이 끝나기 전에는 객실·요금제 매핑을 진행할 수 없습니다.
숙소 등록(연동) 완료 → 호스트 인증(이 가이드) → 객실·요금제 매핑 → 판매 개시
공급사가 구현할 것
- 연동 시작 진입점 — 관리 화면에 "에어비앤비 계정 연동" 버튼을 두고, 클릭 시 인증 URL 발급 API를 호출해 받은
url로 호스트를 이동시킵니다 (새 창 권장) - 복귀 전용 경로 — 인증 결과가 돌아올 전용 콜백 경로(예:
/airbnb/callback). ONDA가 이 경로에auth_result를 붙여 복귀시키므로, 경로에서 결과를 읽어 화면을 분기합니다 - 완료 판정 —
auth_result는 화면 힌트일 뿐이므로, 최종 연동 여부는 매핑 조회 API로 확인합니다
전체 흐름
1단계 · 인증 URL 발급
공급사 서버에서 GET /gds/vendor/channels/{channel_id}/authorization을 호출합니다.
curl -H "Authorization: {vendor_access_token}" \
"https://vendor.dapi.tport.dev/gds/vendor/channels/133/authorization?vendor_property_id=VP-001&redirect_url=https%3A%2F%2Fvendor.example.com%2Fairbnb%2Fcallback"
| 쿼리 파라미터 | 필수 | 설명 |
|---|---|---|
vendor_property_id | 필수 | 공급사 시스템의 숙소 ID |
redirect_url | 필수 | 인증 완료 후 복귀할 전용 경로. http(s)만 허용하며 파이프 문자(|)는 넣을 수 없습니다. ONDA가 복귀 시 auth_result를 덧붙이며, 공급사가 미리 붙여 둔 쿼리 파라미터는 그대로 보존됩니다 |
성공 응답 (200)
{
"url": "https://www.airbnb.com/oauth2/auth?client_id=...&redirect_uri=...&scope=...&state=..."
}
발급된 url은 1시간 동안 유효합니다. 만료된 URL로 진행하면 복귀 없이 실패하므로 재발급 후 다시 시도해야 합니다.
오류 응답
| 상태 | 원인 | 공급사 조치 |
|---|---|---|
400 | redirect_url 형식 오류 — http(s) URL이 아니거나 파이프 문자 포함 | 요청 값 수정 |
401 | 인증 토큰 오류 | 토큰 확인 |
403 UnsupportedChannel | 해당 채널이 OAuth 인증 대상이 아님 | 이 인증이 불필요한 채널입니다 |
404 Property not found | 숙소가 아직 미연동이거나 소유가 아님 | 숙소 등록 절차를 먼저 완료 |
2단계 · 호스트 인증 진행
발급받은 url을 그대로 새 창으로 엽니다. 호스트는 연동하려는 에어비앤비 계정으로 로그인해 권한을 승인합니다.
3단계 · 복귀 처리
ONDA는 인증 처리 후 호스트 브라우저를 redirect_url로 302 복귀시키며, 결과를 auth_result 파라미터로 붙입니다.
| 복귀 형태 | 의미 | 처리 |
|---|---|---|
redirect_url?auth_result=success | 성공 | 곧바로 매핑 조회로 실제 연동 여부를 확정 |
redirect_url?auth_result=fail | 실패 | "인증 실패, 다시 시도"를 안내 |
| 복귀 자체가 없음 | 미확정 | 호스트가 이탈했거나 콜백이 ONDA에 도달하지 못한 경우 |
4단계 · 완료 확인
GET /gds/vendor/properties/{vendor_property_id}/channels/{channel_id}/mappings로 확인합니다.
curl -H "Authorization: {vendor_access_token}" \
"https://vendor.dapi.tport.dev/gds/vendor/properties/VP-001/channels/133/mappings"
{
"vendor_property_id": "VP-001",
"channel_id": "133",
"channel_name": "Airbnb",
"status": "enabled",
"channel_property_id": "123456789",
"roomtype_mappings": [],
"rateplan_mappings": []
}
channel_property_id에 인증된 호스트 계정 ID가 채워져 있으면 인증 완료입니다. 매핑 저장은 성공 복귀(302)를 보내기 전에 끝나므로, 성공 복귀 후라면 보통 첫 조회에서 바로 확인됩니다.
성공 · 실패 판정 기준
| 관측된 상태 | 판정 | 다음 행동 |
|---|---|---|
auth_result=success + 매핑에 channel_property_id 있음 | 인증 완료 | 객실·요금제 매핑 진행 |
auth_result=success + 매핑에 값 없음 | 비정상 조합 | vendor_property_id가 맞는지 확인 후 1~2회 재조회. 그래도 없으면 실패로 보고 재인증 |
auth_result=fail | 인증 실패 | 재시도 안내 |
| 복귀 자체가 없음 | 미확정 | 매핑 조회를 1회 더 → 값이 있으면 완료, 없으면 재시도 |
auth_result는 어떤 화면을 보여줄지 정하는 힌트일 뿐입니다. 브라우저 주소는 호스트가 조작할 수 있으므로(손으로 ?auth_result=success를 붙여 들어올 수 있음) 연동 완료의 증거로 삼으면 안 됩니다. 성공 표시 전 반드시 매핑 조회로 확정하세요.
복귀가 없을 때
두 경우로 갈리며, 처리가 정반대입니다.
| 경우 | ONDA 상태 | 공급사 처리 |
|---|---|---|
| A. 콜백이 ONDA에 도달하지 않음 (호스트가 에어비앤비 화면에서 이탈·거부) | 토큰·매핑 아무것도 생성되지 않음. 인증 코드는 일회성이라 그대로 소멸 | URL 재발급부터 다시 시도 |
| B. ONDA에는 도달했으나 브라우저 복귀만 실패 (공급사 사이트 다운·창 닫힘) | 토큰·매핑 이미 생성됨. 공급사만 복귀 신호를 못 받은 상태 | 매핑 조회를 하면 완료로 잡힘 |
창 닫힘·타임아웃을 "실패 확정"이 아니라 "매핑 조회를 한 번 더 하라"는 트리거로 다루세요. 조회해도 비어 있을 때만 미완료(경우 A)로 처리합니다.
재인증 · 계정 교체
| 케이스 | ONDA 동작 | 공급사가 알아야 할 것 |
|---|---|---|
| 같은 계정으로 재인증 | 토큰만 갱신, 기존 객실·요금제 매핑 유지 | 추가 작업 없음 |
| 다른 계정으로 재인증 (호스트 교체) | 숙소 매핑이 새 계정으로 교체되고, 기존 객실·요금제 매핑은 전부 미매핑으로 초기화 | 객실·요금제 매핑을 처음부터 다시 진행해야 판매 재개 가능 |
계정 교체는 매핑 초기화를 동반합니다. 재인증 진입 시 "다른 계정으로 인증하면 객실·요금제 매핑이 초기화됩니다" 안내를 권장합니다.
구현 팁
복귀는 전용 경로로 받기 — 인증 복귀 전용 경로(예: /airbnb/callback)를 두면 그 경로에 들어온 것 자체가 복귀 신호가 됩니다. 별도 마커 파라미터 없이 auth_result만 읽으면 됩니다.
redirect_url은 URL 인코딩해서 전달 — 발급 API의 쿼리 값이라 인코딩 없이 보내면 :// 등에서 값이 잘립니다. https%3A%2F%2F... 형태로 전달하세요.
새 창으로 열고 부모 화면에 알리기 — 새 창에서 진행하면 호스트가 관리 화면을 잃지 않습니다. 복귀 경로에서 부모 창에 결과를 알리고(window.opener.postMessage 등) 창을 닫으면, 부모 화면이 매핑 조회와 결과 표시를 이어갈 수 있습니다.
완료 확인 재조회에는 상한을 둘 것 — 보통 첫 조회로 충분하지만, 일시적 조회 실패에 대비한 재조회에는 상한을 두세요. 무한 폴링은 금물입니다. 예를 들어 2초 간격 최대 5회 조회 후에도 channel_property_id가 비어 있으면 실패로 판정하고 재인증을 안내합니다.
엉뚱한 계정으로 승인되지 않게 안내 — 새 창은 브라우저 로그인 세션을 공유하므로, 이미 로그인돼 있으면 그 계정으로 바로 승인될 수 있습니다. 재인증이라면 계정 교체로 간주되어 기존 매핑이 초기화됩니다. 인증 시작 전에 "연동할 계정으로 로그인돼 있는지 확인하세요" 안내를 권장합니다.
인증은 숙소 단위 — 같은 호스트 계정이 여러 숙소를 운영하더라도 인증은 vendor_property_id 단위로 진행됩니다. 숙소마다 발급 → 승인 → 확인을 반복해야 합니다.
인증 URL은 버튼을 누르는 시점에 발급 — 발급된 URL은 1시간만 유효하므로, 미리 발급해 화면·메일에 저장해 두면 호스트가 열 때 이미 만료돼 있을 수 있습니다.
자주 겪는 문제
에어비앤비 화면에 "You can only authorize a test app to a test user created under that same app"이 뜹니다
개발 환경은 에어비앤비 테스트 앱으로 동작합니다. 테스트 앱은 그 앱 아래에서 생성된 테스트 유저로만 인증할 수 있으므로, 실계정을 로그아웃하고 안내받은 테스트 유저 계정으로 진행하세요.
auth_result=success로 복귀했는데 매핑 조회에 값이 없습니다
정상 흐름에서는 없는 조합입니다. 매핑 저장이 끝난 뒤에 성공 복귀가 일어나기 때문입니다. 조회한 vendor_property_id가 인증한 숙소와 같은지 먼저 확인하고, 1~2회 재조회 후에도 비어 있으면 인증 실패로 보고 재인증합니다. 주소창에 손으로 붙인 auth_result일 가능성도 있습니다.
복귀 자체가 오지 않습니다
콜백이 ONDA에 도달하지 못한 경우(경우 A)로, 대개 아무것도 생성되지 않습니다. 다만 매핑 조회를 한 번 해보세요 — 경우 B라면 이미 연동돼 있을 수 있습니다. 비어 있으면 URL 재발급부터 재시도합니다.
인증 후 객실·요금제 매핑이 사라졌습니다
이전과 다른 계정으로 인증한 경우입니다. 재매핑이 필요합니다.