你的客人打開訂房頁面。表單載入。他們選擇日期，你的程式碼查詢 Cloudbeds API，回應卻是空白的——儘管你知道房間有空。現在是凌晨2點。你已經整合飯店 PMS API 三年了，你可以肯定地說：每個平台都至少有一個未記錄的行為會讓你耗盡整個週末。Cloudbeds 在特定日期範圍條件下會返回虛擬庫存。Mews 在高入住率時段會無預警地限流 webhook。SiteMinder 的認證令牌會在伺服器時鐘偏差 90 秒時在交易中途過期。本指南涵蓋當你在這三個平台上構建自訂訂房介面時實際發生的事——認證怪癖、即時可用性陷阱，以及因為有人在你的程式碼執行時在 PMS 儀表板中更改設定而消失的房價方案。

如果你是被指派構建繞過這些平台附帶的通用 iFrame 小工具的本機訂房 UI 的開發人員，或者是厭倦了千篇一律訂房體驗的飯店運營者，這篇文章適合你。我們將涵蓋 API 架構、認證模式、即時可用性、房價管理，以及實際轉化客人的前端模式。

目錄

飯店訂房引擎整合：Cloudbeds、Mews 與 SiteMinder API 指南

為什麼要構建自訂訂房引擎？

Cloudbeds、Mews 和 SiteMinder 的預設訂房小工具可以運作。它們會接受預訂並將其推送到 PMS。但它們伴隨著嚴重的權衡：

  • 品牌稀釋：基於 iFrame 的小工具在精心設計的飯店網站上看起來陌生。它們打破視覺流程，客人會注意到。
  • 自訂選項有限：想要顯示房間比較表？內聯推銷水療套餐？顯示與當地活動相關的動態定價？在小工具內做這些事幾乎不可能。
  • 效能損失：iFrame 小工具載入自己的 CSS、JS 和追蹤程式。在行動裝置上——2026 年 65% 以上的飯店搜尋在行動裝置上進行——那額外的重量會扼殺轉化。
  • SEO 盲點：iFrame 內的內容不會被索引。你的房間描述、設施和定價資料對 Google 是隱形的。
  • 分析差距：你的網站和小工具域名之間的跨域追蹤很脆弱。你不斷失去歸因資料。

基於這些平台 API 構建的自訂本機訂房 UI 給你完全的控制。你擁有設計、資料流程和使用者體驗。PMS 仍然處理操作後端——預訂、客房清潔、頻道管理——但客人對應的層面是你的。

這正是我們在 Social Animal 透過無頭 CMS 開發實踐所做的工作類型。飯店的行銷網站存在於現代前端框架中，訂房引擎是一級公民，而不是透過 iFrame 倉促組裝的事後想法。

理解飯店科技堆棧

在深入探討特定 API 之前，讓我們建立景觀。飯店技術有幾個關鍵層：

PMS（物業管理系統）

操作大腦。管理預訂、房間指派、客人檔案、客房清潔和計費。Cloudbeds 和 Mews 都是 PMS 平台。

頻道經理

將庫存和房價分發到 OTA（Booking.com、Expedia 等）並保持一切同步。SiteMinder 主要是頻道經理，儘管他們已擴展到直接訂房。

訂房引擎

客人對應的介面，直接預訂發生的地方。這是我們要用自訂構建取代的。

CRS（中央預訂系統）

對於多物業集團，CRS 在各個地點聚合可用性。某些 PMS 平台包含此功能；其他則需要單獨的系統。

整合挑戰在於這些層重疊。Cloudbeds 捆綁 PMS + 頻道經理 + 訂房引擎。Mews 是以 PMS 為先的開放 API 哲學。SiteMinder 作為中介軟體連接一切。你的自訂 UI 需要理解每個平台的責任在哪裡開始和結束。

Cloudbeds API 整合

Cloudbeds 截至 2026 年在 150 多個國家服務超過 20,000 個物業。他們的 API 已經成熟了很多，但它仍然有一些怪癖。

認證

Cloudbeds 使用 OAuth 2.0 與授權代碼流程。你將在 Cloudbeds Marketplace 中註冊你的應用程式以獲取用戶端認證。

// OAuth 令牌交換
const tokenResponse = await fetch('https://hotels.cloudbeds.com/api/v1.2/access_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: process.env.CLOUDBEDS_CLIENT_ID,
    client_secret: process.env.CLOUDBEDS_CLIENT_SECRET,
    redirect_uri: process.env.CLOUDBEDS_REDIRECT_URI,
    code: authorizationCode,
  }),
});

一個陷阱：Cloudbeds 存取令牌在 300 秒（5 分鐘）後過期。是的，五分鐘。你絕對需要一個令牌重新整理策略，優雅地處理這種情況。我將令牌存儲在伺服器端快取（Redis 運作良好）中，並在 4 分鐘標記時主動重新整理。

訂房的關鍵端點

  • GET /getAvailableRoomTypes — 為日期範圍傳回具有可用性的房間類型。這是搜尋結果頁面的主要端點。
  • GET /getRates — 取得房價方案。注意：房價可以是房間類型特定的，並且某些房價除非物業已啟用它們，否則不會出現。
  • POST /postReservation — 建立預訂。需要客人詳細資訊、房間類型、日期和房價方案。
  • GET /getHotelDetails — 物業資訊、設施、政策。積極快取此項。

Cloudbeds 陷阱

可用性端點在高流量時期不總是返回即時資料。我在物業處理大量 OTA 更新時看到延遲 15-30 秒。構建你的 UI 以優雅地處理「可用性可能已更改」的情景——顯示一個確認步驟，在收集支付前重新驗證。

另外，他們的房價結構可以深度嵌套。單個房間類型可能有 8 個以上的房價方案，具有不同的取消政策、膳食包含和最短停留要求。你需要預先決定在 UI 中要公開該複雜性中的多少。

飯店訂房引擎整合：Cloudbeds、Mews 與 SiteMinder API 指南 - 架構

Mews API 整合

Mews 採取根本不同的方法。他們的 Connector API 是事件驅動的，設計用於深度整合。我會稱其為飯店業中最對開發人員友善的 PMS API。

認證

Mews 使用更簡單的模型：一個 ClientToken（識別你的整合）和一個 AccessToken（識別物業）。伺服器對伺服器通訊無需 OAuth 舞蹈。

// Mews API 請求
const response = await fetch('https://api.mews.com/api/connector/v1/services/getAvailability', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ClientToken: process.env.MEWS_CLIENT_TOKEN,
    AccessToken: process.env.MEWS_ACCESS_TOKEN,
    Client: 'YourApp',
    ServiceId: serviceId,
    StartUtc: '2026-08-01T00:00:00Z',
    EndUtc: '2026-08-07T00:00:00Z',
  }),
});

訂房的關鍵端點

  • services/getAvailability — 按資源類別的即時可用性（Mews 術語中的房間類型）。
  • rates/getPricing — 為特定房價方案和日期範圍傳回定價。
  • reservations/add — 以原子方式建立一個或多個預訂。
  • customers/add — 單獨從預訂建立客人檔案。Mews 將這些分離，這對於返回客人偵測實際上很好。

Mews WebSocket

Mews 真正閃耀的地方。他們提供 WebSocket 連接以進行即時更新：

// 訂閱預訂變更
const ws = new WebSocket('wss://ws.mews.com/ws/connector');
ws.onopen = () => {
  ws.send(JSON.stringify({
    ClientToken: process.env.MEWS_CLIENT_TOKEN,
    AccessToken: process.env.MEWS_ACCESS_TOKEN,
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // 處理即時可用性變更
  if (data.Type === 'Reservation') {
    invalidateAvailabilityCache(data.ServiceId);
  }
};

這意味著你的訂房 UI 可以即時反映可用性變更——無需輪詢。當另一位客人預訂最後一間豪華房間時，你的其他訪客在實時中看到它消失。

Mews 陷阱

Mews 為所有內容使用 UUID，他們的資料模型高度規範化。一個簡單的「給我可用的房間及價格」需要點擊 3-4 個端點並自己連結資料。API 很強大但冗長。在伺服器上構建堅實的資料聚合層。

另外，Mews 的沙盒環境不會完美鏡像支付相關流程的生產行為。在上線前在暫存物業中徹底測試。

SiteMinder API 整合

SiteMinder 處於不同的位置——它主要是頻道經理和分發平台。他們的 API（平台 API 和較舊的頻道經理 API）專注於房價和可用性分發。

認證

SiteMinder 使用 API 金鑰與 OAuth 2.0 用戶端認證流程：

const tokenResponse = await fetch('https://api.siteminder.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: process.env.SITEMINDER_CLIENT_ID,
    client_secret: process.env.SITEMINDER_CLIENT_SECRET,
    scope: 'availability:read reservations:write',
  }),
});

關鍵考量

SiteMinder 的直接訂房 API 比 Cloudbeds 或 Mews 更受限制。你基本上是在他們的 TheBookingButton 產品的後端上構建。該 API 允許：

  • 按物業和日期範圍的可用性查詢
  • 具有限制的房價檢索（最短停留、到達關閉等）
  • 使用客人詳細資訊的預訂建立
  • 修改和取消工作流程

SiteMinder 的優勢是它連接到 400 多個 PMS 系統。如果你的飯店用戶端使用一個不起眼的 PMS，SiteMinder 可能是用於自訂訂房 UI 的唯一可行的 API 整合路徑。

SiteMinder 陷阱

透過 SiteMinder 的房價更新可能會比源 PMS 滯後 1-3 分鐘。對於高需求物業，這會造成超額預訂風險。始終實施支付前可用性檢查，透過最現實時的路徑進行。

他們的 API 文件是……實用的。預期會依賴他們的合作夥伴支援團隊以了解邊界情況。開發人員查詢的回應在 2026 年已有改善，但要為整合預留額外時間。

平台比較

功能 Cloudbeds Mews SiteMinder
API 風格 REST (v1.2) REST + WebSocket REST
認證方法 OAuth 2.0（授權代碼） 令牌型 OAuth 2.0（用戶端認證）
即時更新 僅輪詢 WebSocket Webhook
速率限制 120 req/min 1000 req/min 60 req/min
沙盒環境 有 有 有（有限）
多物業支援 透過單獨的令牌 原生 原生
訂房 API 成熟度 良好 優異 中等
文件品質 良好 優異 一般
典型整合時間 3-4 週 2-3 週 4-6 週
2026 年月 API 成本 包含在 PMS 方案中 包含在 PMS 方案中 根據級別而異

構建本機訂房 UI

現在是有趣的部分——實際構建它。我將專注於模式而不是特定框架，儘管我們通常根據專案要求使用 Next.js 或 Astro 構建這些。

訂房流程架構

飯店訂房流程有 5 個不同的步驟：

  1. 搜尋 — 日期、客人、房間
  2. 結果 — 具有房價的可用房間類型
  3. 選擇 — 房間和房價方案選擇、附加項
  4. 客人詳細資訊 — 聯絡資訊、特殊要求
  5. 支付與確認 — 安全支付、訂房確認

每個步驟應該是自己的路線（不是一頁上的多步驟表單）。這為你提供：

  • 可深度連結的 URL（適合行銷活動）
  • 每步更好的分析
  • 更輕鬆的錯誤恢復
  • 瀏覽器返回按鈕支援，不會破壞一切

搜尋元件

// Next.js 伺服器動作以進行可用性搜尋
'use server'

import { getAvailability, getRates } from '@/lib/pms-client';

export async function searchAvailability(formData: FormData) {
  const checkIn = formData.get('checkIn') as string;
  const checkOut = formData.get('checkOut') as string;
  const adults = parseInt(formData.get('adults') as string);
  const children = parseInt(formData.get('children') as string);

  const [availability, rates] = await Promise.all([
    getAvailability({ checkIn, checkOut }),
    getRates({ checkIn, checkOut }),
  ]);

  // 將可用性與定價合併
  const rooms = mergeAvailabilityWithRates(availability, rates, { adults, children });
  
  // 篩選出無法容納客人人數的房間
  return rooms.filter(room => 
    room.maxOccupancy >= adults + children
  );
}

轉化率高的房間顯示模式

經過多個飯店網站的 A/B 測試，以下是運作的方法：

  • 首先展示房間照片，而不是價格。飯店銷售體驗，而不是交易。
  • 顯示停留的總價格，每晚價格為次要。客人按照行程預算思考。
  • 提前顯示取消政策。直接訂房人的第 1 焦慮是「如果我的計劃改變怎麼辦？」將「免費取消至 [日期]」放在價格附近會使轉化率提高 12-18%（我們的測試）。
  • 限制房價方案選擇為每房間類型 3 個。超過那會造成決策麻痺。
  • 誠實地使用緊迫性。「2 間房間剩餘」很好，如果是真的。不要偽造稀缺性。

附加項和上銷整合

這是自訂 UI 真正勝過小工具的地方。房間選擇後，呈現相關的附加項：

// 取得與訂房環境相關的附加項
async function getContextualAddOns(booking: BookingContext) {
  const addOns = await pmsClient.getServices();
  
  return addOns
    .filter(addOn => {
      // 停留 > 2 晚才顯示水療套餐
      if (addOn.category === 'spa' && booking.nights < 3) return false;
      // 顯示機場轉移，如果在入住日期抵達
      if (addOn.category === 'transfer') return true;
      // 顯示早餐，如果不包含在房價中
      if (addOn.category === 'breakfast' && !booking.ratePlan.includesBreakfast) return true;
      return addOn.category === 'general';
    })
    .sort((a, b) => b.conversionRate - a.conversionRate)
    .slice(0, 4); // 最多顯示 4 個附加項
}

當從通用小工具遷移到環境感知的自訂 UI 時，我們看到附加項收入增加 35-50%。單獨這一點通常就能證明開發投資的合理性。

即時可用性和房價同步

最大的技術挑戰不是訂房流程——它在於保持你的 UI 和 PMS 之間的可用性準確。

快取策略

你需要快取（PMS API 對於直接調用每次頁面載入來說太慢且速率有限），但陳舊的可用性會導致超額預訂。以下是我使用的模式：

// 具有積極失效的多層快取
const CACHE_TTL = {
  availability: 60,      // 1 分鐘
  rates: 300,            // 5 分鐘
  hotelDetails: 86400,   // 24 小時
  roomTypes: 3600,       // 1 小時
};

async function getCachedAvailability(params: SearchParams) {
  const cacheKey = `avail:${params.propertyId}:${params.checkIn}:${params.checkOut}`;
  
  // 檢查快取
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);
  
  // 取得新數據
  const fresh = await pmsClient.getAvailability(params);
  await redis.setex(cacheKey, CACHE_TTL.availability, JSON.stringify(fresh));
  
  return fresh;
}

對於 Mews，使用 WebSocket 連接以主動使快取項失效。對於 Cloudbeds 和 SiteMinder，設定 webhook 監聽器（如果可用），或針對高流量物業回到 30 秒間隔的輪詢。

雙重檢查模式

始終在支付步驟重新驗證可用性。流程看起來像：

  1. 客人搜尋 → 快取可用性（快速，可能略微陳舊）
  2. 客人選擇房間 → 新鮮可用性檢查（確認房間仍然可用）
  3. 客人輸入詳細資訊 → 無需額外檢查
  4. 客人點擊「預訂」→ 原子可用性檢查 + 預訂建立

第 4 步至關重要。Mews 和 Cloudbeds 都在他們的預訂建立端點中以原子方式處理此問題——如果房間不可用，API 會傳回錯誤而不是建立訂房。不要嘗試以兩個單獨的呼叫進行檢查-然後-訂房；你會建立競賽條件。

支付處理和 PCI 合規

飯店支付因預授權和延遲擷取模式而獨特複雜。客人今天預訂，你授權他們的卡片，但直到入住或退住時才擷取費用。

Stripe 整合模式

Stripe 是我們為飯店用戶端整合最常見的支付處理器。流程是這樣的：

// 建立手動擷取的支付意圖
const paymentIntent = await stripe.paymentIntents.create({
  amount: totalInCents,
  currency: property.currency,
  capture_method: 'manual', // 現在授權，稍後擷取
  metadata: {
    pms_reservation_id: reservation.id,
    property_id: property.id,
    check_in: booking.checkIn,
    check_out: booking.checkOut,
  },
});

重要：你必須在 Stripe 的 7 天內擷取（以前大多數卡類型是 7 天，現在有些支援最多 31 天）。對於超過一週的預訂，你需要立即收費並提供退款政策，或實施到達前擷取工作流程。

PCI 合規

如果你使用 Stripe Elements 或類似的符牌化支付表單，你在 SAQ-A 級別處理 PCI 合規，這是可管理的。絕對永遠不要透過你的伺服器傳送原始卡號。接受卡詳細資訊的 PMS API（Mews 有此功能）應該只接收符牌化或加密的卡資料。

效能和轉化最佳化

直接頻道的飯店訂房轉化率在全球範圍內徘徊在 2-3%。構建良好的自訂 UI 可以將其推到 4-6%。以下是移動指針的內容：

  • 子 2 秒搜尋結果：預取熱門日期範圍的可用性。為物業頁面使用 ISR（增量靜態重新生成）。
  • 行動友善日期選擇器：預設 HTML 日期輸入在行動裝置上很糟糕。使用特製元件。我喜歡 react-day-picker 加上自訂觸控友善樣式。
  • 漸進式披露：不要預先顯示所有房價詳細資訊。讓客人展開他們關心的內容。
  • 信任信號：突出顯示「最佳房價保證」。包含 TripAdvisor/Google 評論分數。在結帳按鈕附近顯示安全支付徽章。
  • 粘性訂房摘要：在桌面上，當客人滾動瀏覽詳細資訊和支付時，保持選定的房間和總額可見。在行動裝置上，使用可摺疊的底部欄。

部署架構

對於生產飯店訂房引擎，以下是服務我們良好的架構：

[CDN (Vercel/Cloudflare)] 
    → [Next.js 前端 + API 路由]
        → [Redis 快取層]
            → [PMS API (Cloudbeds/Mews/SiteMinder)]
        → [Stripe 支付 API]
        → [電子郵件服務 (Resend/SendGrid)]

我們在大多數專案中部署在 Vercel 上。邊緣函式處理搜尋 API 路由，以便可用性查詢從最近的區域解決。PMS API 呼叫透過具有 Redis 快取層的集中式 Node.js 無伺服器函式進行。

對於多物業飯店集團，我們添加物業解析器，將傳入的域或 URL 路徑對應到正確的 PMS 認證和組態。這讓一個程式碼庫服務數十個物業。

如果你評估這種架構，查看我們的定價頁面以了解我們如何確定無頭飯店專案的範圍，或直接聯絡我們討論細節。

常見問題

構建自訂飯店訂房引擎要花多少錢？ 對於單一物業整合與一個 PMS（Cloudbeds、Mews 或 SiteMinder），根據複雜性預期初始構建 $15,000-$40,000 USD。多物業部署與共享基礎設施通常運行 $40,000-$80,000。正在進行的維護和 PMS API 變更增加 $500-$2,000/月。ROI 計算應考慮直接訂房轉化率的 2-4% 提升和相較於 OTA 訂房的佣金節省（典型每次預訂 15-25%）。

我可以在沒有他們訂房引擎小工具的情況下使用 Cloudbeds API 嗎？ 是的。Cloudbeds API 與他們的訂房引擎小工具分開。你可以構建一個完全自訂的前端，使用他們的 API 進行可用性、房價和預訂建立。你需要是一個獲批的 Cloudbeds Marketplace 合作夥伴，這涉及一個需要 2-4 週的應用程式和審查流程。

Mews 或 Cloudbeds 對於自訂訂房引擎整合更好嗎？ Mews 有更好的開發人員體驗——更高的速率限制、WebSocket 支援、更清晰的文件和更規範化的資料模型。Cloudbeds 在獨立物業中具有更廣泛的市場採用，所以你的用戶端可能已經在使用它。如果從頭開始，且用戶端沒有 PMS 偏好，我會建議 Mews 適用於想要深度自訂整合的物業。

我如何用自訂訂房 UI 處理超額預訂？ 當快取可用性變得陳舊時，就會發生超額預訂。實施雙重檢查模式：搜尋結果顯示快取，但始終在建立預訂之前用新 API 呼叫重新驗證。Mews 和 Cloudbeds 在預訂建立期間都處理原子可用性檢查，所以如果你讓 PMS 在訂房時成為真相的來源，超額預訂實際上被消除了。

我需要為自訂飯店訂房引擎的 PCI 合規嗎？ 是的，但級別取決於你的實現。使用符牌化支付解決方案（如 Stripe Elements、Adyen Drop-in 或類似的），意味著你永遠不會處理原始卡資料，將你限定在 SAQ-A（最簡單的 PCI 合規級別）。如果你將卡資料透過你的伺服器傳遞到 PMS，你需要 SAQ-D，這顯著更複雜和昂貴以維持。始終使用符牌化支付。

自訂訂房 UI 如何影響我飯店的 SEO？ 積極地。房間類型、描述、設施和以原生 HTML 呈現的定價（不困在 iFrame 中）完全可由搜尋引擎索引。你可以實施結構化資料（schema.org/Hotel、schema.org/LodgingReservation）以出現在豐富結果中。具有自訂構建訂房頁面的物業與 iFrame 小工具設定相比，通常看到到房間特定頁面的有機流量增加 20-40%。

我可以在一個訂房 UI 中整合多個 PMS 平台嗎？ 是的，這對飯店集團很常見，不同物業使用不同的系統。構建一個規範化 API 回應為通用模式的抽象層。你的前端與你的抽象層交談，它根據物業路由到正確的 PMS API。我們為運行在城市物業中使用 Mews、在度假村物業使用 Cloudbeds 的集團構建了這種模式，都在一個品牌下。

如果 PMS API 關閉會發生什麼？ 構建優雅降級。快取最後已知的可用性並以「價格可能不同」免責聲明顯示。突出顯示電話號碼和電子郵件，以便客人仍然可以聯絡前台。實施監測 API 回應時間和錯誤速率的健康檢查，在客人注意到之前提醒你的團隊。對於關鍵訂房時期（假期、活動），考慮重新導向到 PMS 的本機訂房小工具作為最後手段的回退。