PMS 및 채널의 HUIDUN 객실 재고 허브 연동

이 규격은 PMS 벤더와 기술 담당자를 위한 문서입니다. PMS 측에서는 OpenTravel 2003/05 표준 메시지 4종만 구현하면 되며, 주문, 홀드, 오버부킹 방지, 정산은 허브가 처리합니다. 예시는 모두 샌드박스의 실제 요청과 응답입니다.

1. 개요

HUIDUN은 두 가지 연동 모드를 제공합니다. 대부분의 PMS는 모드 A를 사용하며 셀프 서비스로 완료할 수 있습니다. 모드 B는 실시간 조회만 제공할 수 있고 전송 기능이 없는 시스템을 위한 것으로, 건별로 개통합니다.

2. 인증

• 모든 요청에 Authorization: Basic base64(사용자명:비밀번호)를 포함하며 전 구간 HTTPS를 사용합니다. HUIDUN은 비밀번호의 해시값만 저장하므로 분실 시 재설정만 가능합니다.
• HotelCode(예약 조회 시에는 hotel_id)는 호텔이 HUIDUN 관리 화면의 「채널 연동」에서 귀사의 PMS를 선택할 때 설정하는 코드입니다. 호텔이 귀사의 PMS를 선택하지 않았다면 이 코드는 귀사 계정에 존재하지 않는 것으로 처리됩니다(392 반환).
• 객실 유형 코드 InvTypeCode／RoomTypeCode와 요금 플랜 코드 RatePlanCode는 객실 유형 조회 응답에 포함된 값을 기준으로 하며, 매핑 표는 PMS 측에서 관리합니다.
• 계정당 분당 최대 1,200건의 요청을 허용하며 초과 시 366을 반환합니다. 단일 요청 본문의 최대 크기는 1 MB입니다.

3. 객실 유형·요금 플랜 조회　OTA_HotelProduct

이 호텔이 HUIDUN에 등록한 객실 유형과 요금 플랜 조합을 가져옵니다. 「객실 유형 × 요금 플랜」 조합마다 HotelProduct 하나가 반환됩니다. PaymentCollection은 HotelCollect(현장 결제) 또는 OTACollect(온라인 선결제)입니다.

POST https://huidun-demo.luma-e61.workers.dev/ota/cm/OTA_HotelProduct
Authorization: Basic base64(사용자명:비밀번호)
Content-Type: application/xml
<OTA_HotelProductRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0">
<HotelProducts>
<HotelProduct HotelCode="SBX-LUVQ9U"/>
</HotelProducts>
</OTA_HotelProductRQ>

<OTA_HotelProductRS Version="1.0" TimeStamp="2026-10-25T06:01:40Z" xmlns="http://www.opentravel.org/OTA/2003/05">
<Success />
<HotelProducts HotelCode="SBX-LUVQ9U">
<HotelProduct>
<RoomTypes><RoomType RoomTypeCode="STD" RoomTypeName="標準雙人房" MaxOccupancy="2" /></RoomTypes>
<RatePlans><RatePlan RatePlanCode="RO" RatePlanName="純住宿" PaymentCollection="HotelCollect" /></RatePlans>
</HotelProduct>
<HotelProduct>
<RoomTypes><RoomType RoomTypeCode="STD" RoomTypeName="標準雙人房" MaxOccupancy="2" /></RoomTypes>
<RatePlans><RatePlan RatePlanCode="BB" RatePlanName="含早餐" PaymentCollection="OTACollect" /></RatePlans>
</HotelProduct>
<!-- 「객실 유형 × 요금 플랜」 조합마다 HotelProduct 하나 -->
</HotelProducts>
<TPA_Extensions><Pricing Type="Standard" /></TPA_Extensions>
</OTA_HotelProductRS>

4. 일별 요금 전송　OTA_HotelRateAmountNotif

• Start／End는 체크인 날짜(시작일과 종료일 포함)이며 형식은 YYYY-MM-DD입니다. 한 구간은 최대 365일입니다.
• AmountAfterTax는 객실당 1박 세금 포함 가격입니다. NumberOfGuests가 없는 항목은 기본 요금이며, 포함된 경우 해당 인원수의 요금입니다.
• CurrencyCode는 호텔에 설정된 통화와 일치해야 하며(현재 TWD), 일치하지 않으면 61을 반환합니다.
• 하나의 요청에 여러 RateAmountMessage를 담을 수 있습니다. 한 건이라도 오류가 있으면 요청 전체가 저장되지 않으며, Errors에 각 건의 오류가 나열됩니다(최대 20건).

POST https://huidun-demo.luma-e61.workers.dev/ota/cm/OTA_HotelRateAmountNotif
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0">
<RateAmountMessages HotelCode="SBX-LUVQ9U">
<RateAmountMessage>
<StatusApplicationControl InvTypeCode="STD" RatePlanCode="BB"/>
<Rates>
<Rate CurrencyCode="TWD" Start="2026-11-04" End="2026-11-05">
<BaseByGuestAmts>
<BaseByGuestAmt AmountAfterTax="3500"/>
<BaseByGuestAmt NumberOfGuests="1" AmountAfterTax="3200"/>
</BaseByGuestAmts>
</Rate>
</Rates>
</RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>

<OTA_HotelRateAmountNotifRS Version="1.0" TimeStamp="2026-10-25T06:01:40Z" xmlns="http://www.opentravel.org/OTA/2003/05">
<Success />
<UniqueID ID="1792908100105976" Type="506" />
</OTA_HotelRateAmountNotifRS>

5. 재고 및 제한 전송　OTA_HotelAvailNotif

• BookingLimit: 해당 기간 매일 밤 판매 가능한 객실 수(0~9999)입니다. 허브는 예약을 성립시킬 때 이 숫자에서 박별로 차감합니다.
• RestrictionStatus：Status="Close"／"Open". Restriction을 생략하면 판매 중지이며, Arrival은 해당 날짜 체크인 불가, Departure는 해당 날짜 체크아웃 불가를 의미합니다.
• LengthsOfStay：SetMinLOS, SetMaxLOS(체크인 날짜 기준), SetMinLOS_Through, SetMaxLOS_Through(숙박 기간의 모든 박 기준).
• 제한 유형에서 RatePlanCode를 생략하면 해당 객실 유형에 현재 적용 가능한 모든 요금 플랜에 적용됩니다.

POST https://huidun-demo.luma-e61.workers.dev/ota/cm/OTA_HotelAvailNotif
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0">
<AvailStatusMessages HotelCode="SBX-LUVQ9U">
<!-- 재고: BookingLimit = 해당 기간 매일 밤 판매 가능한 객실 수 -->
<AvailStatusMessage BookingLimit="3">
<StatusApplicationControl Start="2026-11-04" End="2026-11-05" InvTypeCode="STD"/>
</AvailStatusMessage>
<!-- 판매 중지 / 체크인 불가 / 최소 숙박 박수 (RatePlanCode를 생략하면 해당 객실 유형의 모든 요금 플랜에 적용) -->
<AvailStatusMessage>
<StatusApplicationControl Start="2026-12-31" End="2026-12-31" InvTypeCode="DLX" RatePlanCode="RO"/>
<RestrictionStatus Status="Close" Restriction="Arrival"/>
<LengthsOfStay><LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/></LengthsOfStay>
</AvailStatusMessage>
</AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

<OTA_HotelAvailNotifRS Version="1.0" TimeStamp="2026-10-25T06:01:40Z" xmlns="http://www.opentravel.org/OTA/2003/05">
<Success />
<UniqueID ID="1792908100106824" Type="505" />
</OTA_HotelAvailNotifRS>

6. 예약 조회　OTA_HotelResNotif

「최종 변경 시각」 구간을 기준으로 예약을 가져오거나 id로 단일 예약을 조회합니다. 1~5분마다 한 번 조회하되 구간의 시작과 끝을 조금씩 겹치게 하고, 예약 번호로 중복을 제거하시기 바랍니다.

• ResStatus：Book 성립(홀드 중 포함, 7절 참조), Modify 변경됨, Cancel 취소됨.
• 예약 번호는 HotelReservationID ResID_Value에 있으며 같은 예약의 번호는 바뀌지 않습니다. 변경과 취소도 같은 번호로 한 번 더 나타납니다.
• PrepaidIndicator="true"는 여행객이 온라인으로 결제를 마쳤으며 호텔이 객실 요금을 별도로 수령할 필요가 없음을 의미합니다.

GET https://huidun-demo.luma-e61.workers.dev/ota/cm/OTA_HotelResNotif?hotel_id=SBX-LUVQ9U&from=2026-10-25T06:00:00Z&to=2026-10-25T07:00:00Z&limit=50
Authorization: Basic base64(사용자명:비밀번호)
# 단일 예약만 조회:
GET .../ota/cm/OTA_HotelResNotif?hotel_id=SBX-LUVQ9U&id=6193082730

<OTA_HotelResNotifRS Version="1.0" TimeStamp="2026-10-25T06:01:40Z" xmlns="http://www.opentravel.org/OTA/2017/05">
<HotelReservations>
<HotelReservation CreateDateTime="2026-10-25T06:01:40+00:00" LastModifyDateTime="2026-10-25T06:01:40+00:00" ResStatus="Book">
<RoomStays><RoomStay>
<RoomTypes><RoomType RoomTypeCode="STD" NonSmoking="true"><RoomDescription Name="標準雙人房" /></RoomType></RoomTypes>
<RatePlans><RatePlan RatePlanCode="BB" PrepaidIndicator="true"><RatePlanDescription Name="含早餐" /><MealsIncluded MealPlanCodes="19" /></RatePlan></RatePlans>
<RoomRates><RoomRate RoomTypeCode="STD" RatePlanCode="BB" NumberOfUnits="1"><Rates>
<Rate UnitMultiplier="1" RateTimeUnit="Day" EffectiveDate="2026-11-04" ExpireDate="2026-11-05"><Total AmountAfterTax="3500.00" CurrencyCode="TWD" /></Rate>
<Rate UnitMultiplier="1" RateTimeUnit="Day" EffectiveDate="2026-11-05" ExpireDate="2026-11-06"><Total AmountAfterTax="3500.00" CurrencyCode="TWD" /></Rate>
</Rates></RoomRate></RoomRates>
<BasicPropertyInfo HotelCode="SBX-LUVQ9U" HotelName="沙盒飯店 LUVQ9U" />
</RoomStay></RoomStays>
<ResGuests><ResGuest><Profiles><ProfileInfo><Profile><Customer>
<PersonName><GivenName>旅客</GivenName><Surname>測</Surname></PersonName>
<ContactPerson><PersonName><GivenName>旅客</GivenName><Surname>測</Surname></PersonName><Telephone PhoneNumber="0900000000" /><Email /></ContactPerson>
</Customer></Profile></ProfileInfo></Profiles></ResGuest></ResGuests>
<ResGlobalInfo>
<GuestCounts><GuestCount AgeQualifyingCode="10" Count="2" /></GuestCounts>
<TimeSpan Start="2026-11-04" End="2026-11-06" />
<Total AmountAfterTax="7000.00" CurrencyCode="TWD" />
<HotelReservationIDs><HotelReservationID ResID_Type="14" ResID_Value="6193082730" /></HotelReservationIDs>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResNotifRS>

7. 홀드, 확정, 오버부킹 방지

채널 주문은 항상 3단계로 진행되며, 홀드하는 시점에 수량이 바로 확보됩니다. 두 채널이 동시에 마지막 한 객실을 요청하면 밀린 쪽은 결제 전에 「매진」 응답을 받으므로, 여행객이 결제했는데 객실이 없는 상황은 발생하지 않습니다.

• 호텔별로 보류 객실 수(기본 1개)를 설정할 수 있습니다. PMS가 전송한 재고 중 해당 수만큼은 판매하지 않고 남겨 두어 양측 동기화 사이의 시간차를 흡수합니다.
• 연동 후 재고의 주인은 PMS입니다. HUIDUN 관리 화면에서의 수동 요금·재고 변경은 차단되므로 PMS에서 수정한 뒤 전송해 주세요.
• PMS가 예약을 조회한 뒤 재고를 다시 전송하면 허브가 이미 조회된 예약을 식별하여 중복 차감하지 않습니다.

8. 채널 API (판매 측 사용, 샌드박스에서는 예약 시뮬레이션용)

판매 채널은 /api/mp를 통해 객실 조회, 견적, 주문을 수행합니다. PMS는 이 절을 구현할 필요가 없습니다. 샌드박스에서는 테스트용 채널 키를 제공하므로 실제 예약을 기다리지 않고도 예약이 조회 결과에 어떻게 나타나는지 확인할 수 있습니다.

POST /api/mp/quote
X-API-Key: 샌드박스 채널 키
{"channel":"sbx_luvq9u","source":"huidun","merchant":"PROP-SBX-LUVQ9U",
"unit":"STD","plan":"BB","day":"2026-11-04","nights":2,"guests":2}
200 {"ok":true,"quote":{"ok":true,"sellMinor":7000,"currency":"TWD",
"detail":{"roomTypeName":"標準雙人房","ratePlanName":"含早餐","cancelPolicy":"不可取消",
"nightly":[{"date":"2026-11-04","sell":3500},{"date":"2026-11-05","sell":3500}]}}}
POST /api/mp/bookings
{ ...위와 동일, "hold":true, "holdMinutes":10, "idemKey":"order-10086",
"guest":{"name":"王小明","phone":"0900000000"} }
201 {"ok":true,"booking":{"bookingKey":"mpb-2cf63b70-…","status":"held",
"holdUntil":"2026-10-25T06:11:40.112Z","grossMinor":7000,"currency":"TWD","reused":false}}
409 {"ok":false,"error":"quote_failed","problems":["已客滿"]}
POST /api/mp/bookings/{bookingKey}/confirm   → 200 {"ok":true,"status":"confirmed","already":false}
POST /api/mp/bookings/{bookingKey}/cancel    → 200 {"ok":true,"status":"cancelled"}

• 금액 단위는 최소 통화 단위입니다(TWD는 위안 단위).
• idemKey는 전역에서 고유합니다. 같은 idemKey로 다시 전송하면 동일한 건이 반환되며(reused:true) 두 건으로 늘어나지 않습니다.
• 투숙객 정보에는 이름과 함께 전화번호 또는 Email 중 하나 이상이 있어야 합니다.
• 객실명이나 problems 등의 문자열은 호텔이 설정한 언어로 반환됩니다.

9. 실시간 커넥터와 머신 서명 (모드 B)

PMS가 실시간 조회만 제공할 수 있는 경우, HUIDUN이 PMS의 엔드포인트를 호출합니다. PMS는 판매 가능 수량 조회, 견적, 홀드, 주문, 취소, 예약 조회와 함께 지원 기능 선언(홀드, 취소, 즉시 확정 지원 여부)을 제공해야 합니다. 이 모드는 건별로 개통하므로 신청서에서 「당사가 실시간 조회 및 주문 API를 제공」을 선택해 주세요.

HUIDUN이 보내는 모든 요청에는 Authorization: Bearer 토큰과 두 개의 서명 헤더가 포함되며, PMS는 이를 검증한 뒤에 처리해야 합니다.

x-hd-timestamp: 1792908100105     (Unix 밀리초)
x-hd-signature: hex( HMAC-SHA256( 공유 비밀키, timestamp + "." + 원본 요청 본문 ) )
검증 규칙:
1. |현재 시각 − timestamp| ≤ 5분이며, 초과하면 거부합니다(재전송 공격 방지)
2. 원본 바이트로 계산하며, JSON을 파싱한 뒤 다시 직렬화하지 마십시오
3. 서명 문자열은 상수 시간(constant-time)으로 비교합니다

// Node.js 검증 예시
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, ts, body, sig) {
if (Math.abs(Date.now() - Number(ts)) > 300000) return false;
const want = createHmac("sha256", secret).update(ts + "." + body).digest("hex");
return want.length === sig.length && timingSafeEqual(Buffer.from(want), Buffer.from(sig));
}

엔드포인트

HUIDUN은 개통 시 등록한 API 기본 URL을 기준으로 위의 서명을 붙여 아래 엔드포인트를 호출합니다. 요청과 응답 본문은 JSON입니다. 금액은 최소 단위 정수로, 대만 달러·엔·원은 1단위, 그 외 통화는 센트 단위입니다. 날짜는 호텔 현지 날짜 YYYY-MM-DD이며 to는 당일을 포함하지 않고 한 번에 최대 31박까지 조회합니다.

/quote 본문: { unit, plan, day, nights, guests }. /bookings 본문에는 quoteId, guest { name, phone, email }, idemKey, hold(불리언), 가예약 유지 분 holdMinutes를 추가합니다. 취소 본문에는 idemKey를 담습니다.

같은 idemKey로 재전송되면 같은 예약을 반환해야 하며 객실을 다시 차감하면 안 됩니다. 기한 내 확정되지 않은 가예약은 자동으로 해제하고, 이후 확정 요청에는 409와 hold_expired를 반환하세요. 가예약과 취소 지원 여부는 개통 시 등록합니다.

실패 시 2xx가 아닌 상태와 { "error": "코드", "message": "설명" }를 반환하세요. 다음 업무 오류(상태 404, 409, 422)는 코드 그대로 판매 채널에 전달됩니다: sold_out, stay_restricted, price_changed, quote_expired, hold_expired, invalid_guests, not_cancellable, booking_not_found. 그 밖의 코드, 401, 429, 5xx, 시간 초과(8초)는 일시적 장애로 처리해 채널에 잠시 후 재시도하도록 안내하며 메시지 원문은 전달하지 않습니다.

공유 비밀키는 개통 시 별도로 전달되며, 어떤 페이지나 이메일 본문에도 표시되지 않습니다.

10. 오류 코드

파싱 전 오류: HTTP 505 + JSON

HTTP/1.1 505
Content-Type: application/json
{"error":{"code":"497","message":"Authentication error","timestamp":"2026-10-25T14:01:40+08:00"}}

업무 오류: HTTP 200 + Errors

HTTP/1.1 200
<OTA_HotelRateAmountNotifRS Version="1.0" TimeStamp="2026-10-25T06:01:40Z" xmlns="http://www.opentravel.org/OTA/2003/05">
<Errors>
<Error Type="3" ShortText="Invalid room type" Code="402">Room type SUITE is not defined for this hotel.</Error>
</Errors>
<UniqueID ID="1792908100109112" Type="506" />
</OTA_HotelRateAmountNotifRS>

채널 API (JSON)

11. 인증 검증 7개 항목

샌드박스의 검증 현황표는 샌드박스 데이터베이스의 실제 기록을 기준으로 자동 판정되며, 7개 항목을 모두 완료하면 정식 인증을 신청할 수 있습니다.

1. 객실 유형·요금 플랜 조회(OTA_HotelProduct) 성공
2. 요금 전송(OTA_HotelRateAmountNotif) 성공
3. 재고 전송(OTA_HotelAvailNotif) 성공
4. 채널 홀드로 예약 1건 성립
5. 홀드 확정 성립
6. 예약 1건 취소 또는 홀드 시간 초과로 해제
7. 예약이 생긴 뒤 예약 조회(OTA_HotelResNotif) 성공

샌드박스 원클릭 실행 페이지에서 실행할 때마다 이 점검표를 보여 줍니다. JSON으로도 조회할 수 있습니다: https://huidun-demo.luma-e61.workers.dev/sandbox/pms/progress?ref=호텔코드&format=json (완료 여부와 시각만 반환하며 계정 정보나 개인정보는 포함하지 않습니다).

12. 샌드박스 제한 사항

• 개통할 때마다 샌드박스 호텔 1곳이 생성됩니다. 객실 유형 2개(STD, DLX) × 요금 플랜 2개(RO 숙박만·현장 결제, BB 조식 포함·온라인 선결제)이며, 향후 30일간의 요금과 재고가 미리 입력되고 보류 객실 수는 1개입니다.
• 샌드박스는 30일 후 비활성화되며, 동일 네트워크에서 1시간당 최대 3개까지 개통할 수 있습니다.
• 샌드박스 채널의 서비스 수수료는 0이며 운영 환경의 실제 요율을 의미하지 않습니다.
• 샌드박스는 독립된 테스트 데이터베이스로 운영 환경과 어떠한 데이터도 오가지 않으므로, 실제 여행객 데이터는 입력하지 마십시오.