호텔 공급사 연동
Hotelbeds API 연동: 콘텐츠, 매핑, 실시간 예약
Hotelbeds API 연동은 하나가 아니라 두 가지 작업입니다. 먼저 호텔 콘텐츠를 다운로드해 저장하고, 그다음 실시간 요금으로 예약합니다. PHPTRAVELS는 고객님의 Hotelbeds 계약과 키로 호텔 모듈 안에서 두 작업을 모두 처리합니다.
- Content API 동기화
- Booking API 흐름
- BOOKABLE 및 RECHECK 요금
- 호텔 매핑
Hotelbeds API의 구성 방식
Hotelbeds API 연동: 한쪽은 콘텐츠, 다른 쪽은 예약
Hotelbeds는 호텔 API를 둘로 나눕니다. Content API는 설명, 이미지, 시설, 식사 유형, 객실 같은 정적 데이터를 반환합니다. Booking API는 실시간 객실과 요금을 반환하고 예약을 받습니다. 가운데 단계를 선택하면 어떤 호출을 사용하는지 볼 수 있습니다.
Content API
정적 데이터, 고객님 쪽에 저장- 호텔 목록
hotels · from=1&to=1000포트폴리오의 모든 호텔을 요청당 최대 1,000개씩 페이지 단위로 받습니다. - 시설, 식사 유형, 객실
facilities · boards · roomsBooking API 코드를 고객이 이해할 수 있는 문구로 바꿔 주는 코드 테이블입니다. - 이미지
photos.hotelbeds.com/giata/부분 이미지 경로를 Hotelbeds 사진 호스트와 결합해 필요한 크기로 사용합니다. - 일일 변경분
lastUpdateTime첫 로드 이후에는 lastUpdateTime을 포함한 하루 한 번의 요청으로 변경된 내용만 받습니다.
요청 흐름
Booking API
실시간, 고객별 호출- 객실 조회
POST /hotels호텔 코드, 날짜, 인원에 맞는 객실, 식사, 요금, 취소 수수료를 반환합니다. - 요금 재확인
POST /checkratesRECHECK로 표시된 요금의 최신 가격과 조건, 업셀 옵션을 반환합니다. - 예약
POST /bookings예약자와 투숙객 이름으로 선택한 rateKey를 확정하고 예약 번호를 반환합니다. - 취소
DELETE /bookings · simulate취소를 시뮬레이션해 수수료를 보여 주거나 실제로 예약을 취소합니다.
실패하는 Hotelbeds 프로젝트 대부분은 이 두 부분을 섞어 버립니다. 고객 검색 중에 Content API를 호출하면 느리고, Hotelbeds가 경고하듯 인증 정보가 차단될 수 있습니다. 반대로 저장된 코드 없이 실시간 검색하면 이미지나 시설을 보여 줄 수 없습니다. PHPTRAVELS는 둘을 분리합니다. 콘텐츠는 백그라운드에서 동기화하고, 고객이 기다리는 동안에는 객실 조회, 요금 재확인, 예약 호출만 실행합니다.
공급사 자체, 상품, 계정 개설 방법이 궁금하시다면 Hotelbeds 공급사 소개을 읽어 보세요. 이 페이지는 기술 연동을 다룹니다.
요금 유형
결제 과정을 바꾸는 네 가지 요금 필드
모든 Hotelbeds 요금에는 바로 예약할 수 있는지, 어떤 가격을 표시할 수 있는지, 누가 대금을 받는지를 결정하는 속성이 있습니다. 엔진이 모든 결과에서 읽어야 하는 항목은 다음과 같습니다.
| 필드 | 첫 번째 경우 | 두 번째 경우 | PHPTRAVELS의 처리 |
|---|---|---|---|
바로 예약 또는 재확인rateType | BOOKABLE요금이 최신입니다. 추가 호출 없이 예약할 수 있습니다. | RECHECK최신 가격과 조건을 받으려면 먼저 요금 재확인을 호출해야 합니다. | RECHECK 요금은 결제 단계 전에 재확인하고, 변경 사항이 있으면 고객에게 보여 줍니다. |
넷 또는 커미션net · sellingRate | net넷 모델: 요금이 넷 가격이므로 직접 마진을 더합니다. | sellingRate커미션 모델: 커미션이 이미 sellingRate에 포함되어 있으며, 그 가격이 최종 가격입니다. | 넷 요금에는 마크업 규칙을 적용하고, 커미션 요금은 sellingRate로 판매합니다. |
고정 판매가hotelMandatory | truehotelMandatory가 true: 반드시 sellingRate로 판매해야 합니다. | false · null넷 요금에서 false 또는 빈 값: 자체 마진을 설정할 수 있습니다. | 호텔이 요구하면 마크업 규칙과 상관없이 표시 가격을 sellingRate로 고정합니다. |
고객 결제 시점paymentType | AT_WEB예약 시 고객님의 사이트에서 결제합니다. | AT_HOTEL고객이 호텔에 직접 결제합니다. | 요금에 지금 결제 또는 현장 결제 표시를 붙이고 그에 맞게 결제 과정을 연결합니다. |
어떤 요금 모델을 받게 되는지는 Hotelbeds 계약에 따라 다릅니다. Hotelbeds에 따르면 담당 영업 매니저가 비즈니스에 맞는 모델을 추천합니다.
호텔 매핑
Hotelbeds 호텔을 이미 판매 중인 호텔과 매칭
직접 계약이나 다른 공급사가 있다면 같은 호텔이 서로 다른 코드로 들어옵니다. 매핑으로 이를 연결하면 고객은 세 개의 중복이 아니라 최저 요금의 호텔 하나를 보게 됩니다.
- Harbour View Hotel리스본48291397%매칭됨
- Old Town Suites프라하11735492%매칭됨
- Palm Court Resort두바이66201874%검토
- Casa Azul Boutique세비야–0%일치 없음
- Northern Lights Lodge트롬쇠90522766%검토
- Riverside Apartments부다페스트33076198%매칭됨
가상의 호텔과 코드로 만든 샘플 화면입니다.
Hotelbeds XML 또는 JSON
모든 요청에 서명하고, 테스트는 작게 시작합니다
여전히 Hotelbeds XML로 검색하는 팀이 많지만, 현재 문서에는 JSON 요청이 나와 있습니다. 어느 쪽이든 작업은 같으며, 각 요청에는 두 개의 헤더가 붙습니다.
1# X-Signature = SHA256(api key + secret + unix time in seconds) 2TS=$(date +%s) 3SIG=$(printf "%s%s%s" "$API_KEY" "$SECRET" "$TS" | sha256sum | cut -d" " -f1) 4 5curl -X POST https://api.test.hotelbeds.com/hotel-api/1.0/hotels \ 6 -H "Api-key: $API_KEY" \ 7 -H "X-Signature: $SIG" \ 8 -H "Accept: application/json" \ 9 -H "Content-Type: application/json" \10 -d '{11 "stay": { "checkIn": "2026-11-14", "checkOut": "2026-11-17" },12 "occupancies": [{ "rooms": 1, "adults": 2, "children": 0 }],13 "hotels": { "hotel": [482913, 117354] }14 }'1516# hotel codes come from your stored Content API data, never a live content call
- 두 개의 헤더
- Api-key에는 키를, X-Signature에는 키, 시크릿, 현재 시각(초)의 SHA256 해시를 넣습니다.
- 테스트 호스트
- Hotelbeds에 따르면 테스트 서버는 운영 환경과 같지만, 그곳의 예약은 실제가 아니며 카드도 청구되지 않습니다.
- 하루 50건 요청
- 새 키는 하루 50건 요청 한도의 평가 환경으로 시작합니다. 인증을 마치면 한도가 늘어납니다.
- 실시간 콘텐츠 호출 금지
- Hotelbeds는 Content API를 실시간으로 호출하면 인증 정보가 차단될 수 있다고 경고합니다. PHPTRAVELS는 절대 그렇게 하지 않습니다.
콘텐츠 동기화 플래너
호텔 목록에 필요한 Content API 호출 수
Hotelbeds에 따르면 호텔 목록은 최대 1,000개씩 페이지로 제공되며, 첫 로드 이후에는 하루 한 번의 lastUpdateTime 요청으로 변경분만 받습니다. 숫자를 입력해 동기화를 계획하세요.
- 첫 전체 로드 요청 수
- 20
- 일일 업데이트당 요청 수
- 3
- 평가 한도로 한 번 로드하는 데 걸리는 일수
- 1
호텔 목록 기준 추정치입니다. 코드 테이블과 이미지로 호출이 조금 더 늘어납니다. 평가 한도는 하루 50건이므로 먼저 목적지 한 곳으로 테스트하세요.
운영 전환 체크리스트
운영 환경으로 전환하기 전에 준비할 사항
Hotelbeds는 대시보드를 통해 평가에서 인증, 그리고 운영 키 단계로 안내합니다. Hotelbeds API 연동이 먼저 갖춰야 할 항목과 PHPTRAVELS의 처리 방식은 다음과 같습니다.
- 관리자 화면에 평가 키 추가, 테스트 호스트 선택
- Content API를 데이터베이스에 동기화하고 일일 업데이트 예약
- 호텔을 자체 목록에 매핑하고 애매한 매칭 검토
- RECHECK 요금은 결제 전에 요금 재확인 진행
- hotelMandatory가 true이면 sellingRate 준수
- 고객 결제 전에 요금 안내와 취소 수수료 표시
- 바우처에 Hotelbeds 예약 번호와 요금 안내 표시
- 취소를 먼저 시뮬레이션한 뒤 확정하고 수수료 기록
인증 절차와 운영 접근 권한은 계약과 시장에 따라 Hotelbeds가 정합니다.
비용
엔진은 1회 라이선스, Hotelbeds와는 직접 계약
PHPTRAVELS는 소스 코드가 포함된 1회성 라이선스입니다. Hotelbeds는 고객님과 Hotelbeds 사이의 별도 계약이므로 넷 요금과 키는 고객님 소유입니다.
Hotelbeds는 함께 운영할 수 있는 여러 호텔 공급원 중 하나입니다. 여행 API 개요에서 RateHawk와 함께 쓰는 방식을 보거나, XML 공급사 목록에서 공급사를 비교해 보세요.
두 부분입니다. 하나는 Content API로 호텔, 이미지, 시설, 식사 유형, 객실을 데이터베이스에 저장하는 백그라운드 동기화이고, 다른 하나는 Booking API로 객실 조회, 요금 재확인, 예약, 취소를 처리하는 실시간 흐름입니다. PHPTRAVELS는 호텔 모듈에서 둘 다 실행합니다.
여전히 Hotelbeds XML이라고 부르지만, 현재 Hotelbeds 문서에는 JSON 요청과 응답이 나와 있습니다. 어느 쪽이든 작업은 같으며, 형식 처리는 PHPTRAVELS가 대신합니다.
BOOKABLE 요금은 이미 최신이므로 바로 예약할 수 있습니다. RECHECK 요금은 먼저 요금 재확인을 호출해야 하며, 현재 가격과 조건이 반환됩니다. PHPTRAVELS는 결제 단계 전에 이 호출을 실행합니다.
느리고, Hotelbeds는 Content API를 실시간으로 사용하면 인증 정보가 차단될 수 있다고 경고합니다. 콘텐츠는 페이지 단위로 다운로드해 저장하고 lastUpdateTime으로 하루 한 번 업데이트해야 하며, PHPTRAVELS가 바로 그렇게 동작합니다.
네. Hotelbeds에 가입하고 계약을 체결한 뒤 자체 API 키와 시크릿을 받습니다. 새 키는 인증을 완료할 때까지 하루 50건 요청의 평가 환경에서 작동합니다.
네. 호텔 매핑이 여러 공급원의 같은 숙소를 연결하므로 고객은 최저 요금의 호텔 하나를 보고, 각 공급원은 자체 마크업과 규칙을 유지합니다.
PHPTRAVELS 요금제는 부터 시작하며, 소스 코드가 포함된 1회성 라이선스입니다. Hotelbeds 계약은 별도로 Hotelbeds와 직접 체결합니다. 가격 페이지를 확인하시거나 영업팀에 견적을 요청하세요.