Loading
Bitvoya Edition
下一篇章
正在鋪陳下一段旅程
在頁面展開前，先把影像、目的地與細節整理成完整敘事。
靈感
視角
抵達
Bitvoya B2B API · v1
全球奢華酒店，一次呼叫即可接入。
在你自己的平台上搜尋我們甄選的酒店、即時報價並預付下單。每個房價只有一個價格：人民幣計價，已含稅費和服務費。
基礎地址https://app.bitvoya.com/api/b2b/v1
- 可直接產生各語言 SDK 的 API 規格
- OpenAPI 3.1
- 一個含稅總價，已含服務費
- CNY
- 酒店資料支援的語言
- 5
- 每個報價的鎖價時長
- 15 分鐘
快速開始
從 API Key 到酒店確認
六個呼叫走完一個訂單，每一步都附上請求和回應。
- 01GET/me
確認金鑰
每個請求都以 Bearer 方式帶上你的 API Key。GET /me 返回金鑰所屬的租戶、權限（scope）和每分鐘請求上限。
GET/mecurl https://app.bitvoya.com/api/b2b/v1/me \ -H "Authorization: Bearer $BITVOYA_API_KEY"回應200OKRateLimit-Policy: "tenant";q=120;w=60RateLimit: "tenant";r=118;t=41{ "data": { "tenant": { "code": "acme-travel", "name": "Acme Travel" }, "api_key": { "name": "Production server", "prefix": "bvk_live_AbCd1234", "scopes": [ "catalog:read", "rates:read", "bookings:read", "bookings:write" ], "expires_at": null }, "pricing": { "currency": "CNY", "price_basis": "tax_inclusive_total_with_service_fee" }, "rate_limit": { "requests_per_minute": 120 } } } - 02GET/hotels
同步酒店資料
按目的地或品牌，用游標翻頁拉取酒店。靜態資料帶 ETag，內容沒變時返回 304，不必重新下載。
GET/hotelscurl "https://app.bitvoya.com/api/b2b/v1/hotels?destination_id=5736&limit=1" \ -H "Authorization: Bearer $BITVOYA_API_KEY"回應200OKCache-Control: private, max-age=300ETag: W/"5c1-9f3a7e21"Content-Language: en{ "data": [ { "id": "644", "name": "Sofitel Hangzhou Westlake", "address": "333 Xihu Avenue, Shangcheng District", "destination": { "id": "5736", "name": "Hangzhou" }, "brand": { "id": "1862", "name": "Sofitel Hotels" }, "location": { "latitude": 30.2537, "longitude": 120.1652 }, "image_url": "https://images.example/hotels/644/cover.jpg" } ], "next_cursor": "eyJrIjoiaG90ZWwiLCJhIjoiNjQ0In0" } - 03GET/hotels/{hotel_id}/rates
查詢即時房價
給出入住日期和成人數（一間房 1–4 位）。每個房價只有一個價格，並附上餐食和按酒店當地時間給出的取消政策。
GET/hotels/{hotel_id}/ratescurl "https://app.bitvoya.com/api/b2b/v1/hotels/644/rates?checkin=2026-12-05&checkout=2026-12-07&adults=2" \ -H "Authorization: Bearer $BITVOYA_API_KEY"回應200OKCache-Control: no-store{ "data": { "hotel_id": "644", "checkin": "2026-12-05", "checkout": "2026-12-07", "nights": 2, "adults": 2, "rooms": [ { "room_id": "38211", "name": "Luxury Room, Lake View", "image_url": "https://images.example/hotels/644/rooms/38211.jpg", "rates": [ { "rate_key": "eyJoIjoiNjQ0IiwiZCI6IjkwMTc3NDAyIiwiY2kiOiIyMDI2LTEyLTA1IiwiY28iOiIyMDI2LTEyLTA3IiwiYSI6Mn0", "name": "Breakfast for two, free cancellation", "meal_plan": "breakfast", "executive_benefit": false, "price": { "amount": "1709.65", "currency": "CNY" }, "cancellation": { "type": "free_cancellation", "deadline": "2026-12-04T18:00:00+08:00", "confirmed": true }, "pay_at_hotel": null } ] } ] } } - 04POST/quotes
鎖定報價
提交選中的 rate_key。我們即時向供應商核價，並把價格保留 15 分鐘。
POST/quotescurl -X POST https://app.bitvoya.com/api/b2b/v1/quotes \ -H "Authorization: Bearer $BITVOYA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rate_key": "eyJoIjoiNjQ0IiwiZCI6IjkwMTc3NDAyIiwiY2kiOiIyMDI2LTEyLTA1IiwiY28iOiIyMDI2LTEyLTA3IiwiYSI6Mn0" }'回應201Created{ "data": { "quote_id": "qt_7Hk2Qx9PmW4rT8vN3bLc", "expires_at": "2026-11-20T09:15:00Z", "hotel_id": "644", "room": { "room_id": "38211", "name": "Luxury Room, Lake View" }, "rate": { "name": "Breakfast for two, free cancellation", "meal_plan": "breakfast", "executive_benefit": false }, "checkin": "2026-12-05", "checkout": "2026-12-07", "nights": 2, "adults": 2, "price": { "amount": "1709.65", "currency": "CNY" }, "cancellation": { "type": "free_cancellation", "deadline": "2026-12-04T18:00:00+08:00", "confirmed": true }, "pay_at_hotel": null } } - 05POST/bookings
下單並付款
用報價和客人姓名下單，並帶上 Idempotency-Key，重試也不會重複下單。回應裡有全額付款的 Stripe 頁面。
POST/bookingscurl -X POST https://app.bitvoya.com/api/b2b/v1/bookings \ -H "Authorization: Bearer $BITVOYA_API_KEY" \ -H "Idempotency-Key: 6f1c2a9e-4b7d-4c1e-9a53-2d8e0f7b1c44" \ -H "Content-Type: application/json" \ -d '{ "quote_id": "qt_7Hk2Qx9PmW4rT8vN3bLc", "client_reference": "ACME-10293", "guests": [ { "first_name": "Mei", "last_name": "Lin" }, { "first_name": "James", "last_name": "Lin" } ], "contact": { "email": "ops@acme.example", "phone": "+86 21 5555 0100" }, "arrival_time": "18:00", "special_requests": ["king_bed"], "success_url": "https://acme.example/trips/ACME-10293/paid", "cancel_url": "https://acme.example/trips/ACME-10293" }'回應201CreatedLocation: /api/b2b/v1/bookings/BV20261120090112{ "data": { "booking_id": "BV20261120090112", "client_reference": "ACME-10293", "status": "awaiting_payment", "hotel": { "hotel_id": "644", "name": "Sofitel Hangzhou Westlake" }, "room": { "room_id": "38211", "name": "Luxury Room, Lake View" }, "rate": { "name": "Breakfast for two, free cancellation", "meal_plan": "breakfast", "executive_benefit": false }, "checkin": "2026-12-05", "checkout": "2026-12-07", "nights": 2, "adults": 2, "guests": [ { "first_name": "Mei", "last_name": "Lin" }, { "first_name": "James", "last_name": "Lin" } ], "price": { "amount": "1709.65", "currency": "CNY" }, "cancellation": { "type": "free_cancellation", "deadline": "2026-12-04T18:00:00+08:00", "confirmed": true }, "pay_at_hotel": null, "payment": { "status": "pending", "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8", "expires_at": "2026-11-20T09:31:12Z", "paid_at": null }, "hotel_confirmation_number": null, "created_at": "2026-11-20T09:01:12Z", "updated_at": "2026-11-20T09:01:12Z" } } - 06GET/bookings/{booking_id}
追蹤到確認
付款後我們向酒店確認，可能需要幾個小時。輪詢訂單，直到狀態變為 confirmed 並帶上酒店確認號。
GET/bookings/{booking_id}curl https://app.bitvoya.com/api/b2b/v1/bookings/BV20261120090112 \ -H "Authorization: Bearer $BITVOYA_API_KEY"回應200OK{ "data": { "booking_id": "BV20261120090112", "client_reference": "ACME-10293", "status": "confirmed", "hotel": { "hotel_id": "644", "name": "Sofitel Hangzhou Westlake" }, "room": { "room_id": "38211", "name": "Luxury Room, Lake View" }, "rate": { "name": "Breakfast for two, free cancellation", "meal_plan": "breakfast", "executive_benefit": false }, "checkin": "2026-12-05", "checkout": "2026-12-07", "nights": 2, "adults": 2, "guests": [ { "first_name": "Mei", "last_name": "Lin" }, { "first_name": "James", "last_name": "Lin" } ], "price": { "amount": "1709.65", "currency": "CNY" }, "cancellation": { "type": "free_cancellation", "deadline": "2026-12-04T18:00:00+08:00", "confirmed": true }, "pay_at_hotel": null, "payment": { "status": "paid", "url": null, "expires_at": null, "paid_at": "2026-11-20T09:04:51Z" }, "hotel_confirmation_number": "48213977", "created_at": "2026-11-20T09:01:12Z", "updated_at": "2026-11-20T11:42:05Z" } }
價格
只有一個數，就是你預付的數。
每個房價只給一個價格：整段入住的含稅總價，已含你的 Bitvoya 服務費。沒有供應商價、佣金或服務費需要你自己相加。
- 金額是字串形式的十進位數，不會有浮點誤差。
- 服務費條件按租戶在我們的後台設定。
- 只提供可以全額預付的房價。
- 付款之後，價格不再變動。
範例房價 · 2 晚 · 2 位成人
rate.price- 兩晚房費已含
- 稅費已含
- 你的 Bitvoya 服務費已含
price
透過 Stripe 預付的金額
¥1,709.65
"price": { "amount": "1709.65", "currency": "CNY" }城市稅EUR 18.48 約 ¥137.38
pay_at_hotel · 到店支付，不計入 price
訂單狀態
六個狀態，一目瞭然
訂單沿一條主線推進。其他狀態會告訴你發生了什麼、下一步該做什麼。
主線
- awaiting_payment
等待在 payment.url 付款，付款頁面 30 分鐘內有效。
- pending_confirmation
已付款，我們正在向酒店確認，可能需要幾個小時。
- confirmed
酒店已確認，返回 hotel_confirmation_number。
其他結果
- payment_failed
付款頁面已過期或付款失敗，請重新下單。
來自
awaiting_payment - cancelled
已取消，退款進度見 payment.status。
來自
awaiting_paymentpending_confirmationconfirmed - under_review
付款異常，我們正在人工核對。
API 參考
全部端點
路徑都相對於基礎地址。展開端點即可檢視參數和範例。
基礎地址https://app.bitvoya.com/api/b2b/v1
帳戶
GET/me本次請求所用的租戶、金鑰與權限，以及請求上限。
任一有效金鑰
本次請求所用的租戶、金鑰與權限，以及請求上限。
任一有效金鑰
參數
無參數。
範例
靜態資料
GET/destinations有酒店的城市。可按任意語言的名稱或城市代碼搜尋，也可翻頁列出全部。
catalog:read
有酒店的城市。可按任意語言的名稱或城市代碼搜尋，也可翻頁列出全部。
catalog:read
參數
queryquerystring · 1–100
cursorquerystring · next_cursor
limitqueryinteger · 1–100 · 預設
50
範例
GET/hotels按 ID 排序的酒店，可按目的地或品牌過濾；不帶過濾即全量同步。
catalog:read
按 ID 排序的酒店，可按目的地或品牌過濾；不帶過濾即全量同步。
catalog:read
參數
destination_idquerystring · digits
brand_idquerystring · digits
cursorquerystring · next_cursor
limitqueryinteger · 1–100 · 預設
50
範例
GET/hotels/{hotel_id}單個酒店：地址、座標、星級、入住與退房時間、描述、設施和圖片。
catalog:read
單個酒店：地址、座標、星級、入住與退房時間、描述、設施和圖片。
catalog:read
參數
hotel_idpath必填string · digits
範例
GET/brands酒店品牌，以及每個品牌下的酒店數量。
catalog:read
酒店品牌，以及每個品牌下的酒店數量。
catalog:read
參數
無參數。
範例
房價與報價
GET/hotels/{hotel_id}/rates一次入住的房型和可訂房價，價格從低到高。
rates:read
一次入住的房型和可訂房價，價格從低到高。
rates:read
參數
hotel_idpath必填string · digits
checkinquery必填date · YYYY-MM-DD
checkoutquery必填date · YYYY-MM-DD
adultsqueryinteger · 1–4 · 預設
2
範例
POST/quotes即時核對一個房價，並把價格保留 15 分鐘。
rates:read
即時核對一個房價，並把價格保留 15 分鐘。
rates:read
參數
rate_keybody必填string
範例
訂單
POST/bookings用報價下單，返回訂單和 Stripe 付款頁面。
bookings:write
用報價下單，返回訂單和 Stripe 付款頁面。
bookings:write
參數
Idempotency-Keyheader必填string · ≤255
quote_idbody必填string · qt_…
guests[]body必填1–2 × { first_name, last_name }
contact.emailbody必填email
contact.phonebodystring · +86 …
client_referencebodystring · ≤64
arrival_timebodyHH:MM
special_requests[]bodyking_bed | twin_beds | baby_cot | extra_bed | birthday
remarksbodystring · ≤200
success_urlbodyhttps URL
cancel_urlbodyhttps URL
範例
GET/bookings你的訂單，新的在前，可按 client_reference 查詢。
bookings:read
你的訂單，新的在前，可按 client_reference 查詢。
bookings:read
參數
client_referencequerystring · ≤64
cursorquerystring · next_cursor
limitqueryinteger · 1–100 · 預設
50
範例
GET/bookings/{booking_id}單個訂單：狀態、付款情況和酒店確認號。
bookings:read
單個訂單：狀態、付款情況和酒店確認號。
bookings:read
參數
booking_idpath必填string · BV + 14 digits
範例
POST/bookings/{booking_id}/cancel取消訂單。免費取消截止前，已付款的訂單全額退款。
bookings:write
取消訂單。免費取消截止前，已付款的訂單全額退款。
bookings:write
參數
booking_idpath必填string · BV + 14 digits
reasonbodystring · ≤200
範例
公開
GET/payments/return未傳 success_url 時，付款完成後返回的預設頁面。
無需金鑰
未傳 success_url 時，付款完成後返回的預設頁面。
無需金鑰
參數
無參數。
範例
GET/openapi.json本 API 的 OpenAPI 3.1 規格。
無需金鑰
本 API 的 OpenAPI 3.1 規格。
無需金鑰
參數
無參數。
範例
統一約定
建立在開放標準之上
處處是你熟悉的 HTTP 約定，不需要專門的 SDK。
身分驗證
在 Authorization: Bearer 中傳送金鑰。金鑰按權限授權，可以輪換，每個租戶最多 10 個有效金鑰。我們只儲存雜湊，明文只顯示一次。
Authorization: Bearer bvk_live_…錯誤
錯誤採用 RFC 9457 problem details。程式按穩定的 code 欄位判斷；detail 是給人看的說明，聯絡我們時請提供 request_id。
Content-Type: application/problem+json限流
每個租戶有每分鐘請求額度，名下所有金鑰共用。IETF RateLimit 回應標頭顯示剩餘額度，429 會帶上 Retry-After。
RateLimit: "tenant";r=118;t=41冪等
POST /bookings 必須帶 Idempotency-Key。同一個 key 加同樣的請求體，返回原訂單；同一個 key 加不同的請求體，會被拒絕。
Idempotency-Key: 6f1c2a9e-4b7d…分頁
列表用游標，不用頁碼。把 next_cursor 作為 cursor 傳回，直到它為 null。limit 最大 100。
?limit=100&cursor=eyJrIjoiaG90ZWwi…語言
用 Accept-Language 指定 en、zh-CN、zh-TW、ja 或 ko。缺少譯文時合理回退，Content-Language 會告訴你實際返回的語言。
Accept-Language: ja快取
靜態資料可快取 5 分鐘，並帶弱 ETag。房價、報價和訂單從不快取。
If-None-Match: W/"5c1-9f3a7e21"版本
主版本寫在路徑裡。v1 內只做新增；破壞性改動會放進 v2，並提前用 Deprecation 和 Sunset 回應標頭告知。
/api/b2b/v1
錯誤碼
可以按程式判斷的錯誤碼
每個錯誤都有 HTTP 狀態和一個穩定的 code。
application/problem+json
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"code": "quote_changed",
"detail": "The price or the cancellation terms changed. Check current_quote and book with its quote_id.",
"request_id": "req-3k9x1",
"current_quote": {
"quote_id": "qt_Vb8nR2kL5tY7wQ3mZ9xP",
"price": { "amount": "1788.40", "currency": "CNY" }
}
}| HTTP | code | 含義 |
|---|---|---|
| 400 | invalid_request參數或欄位無效，見 errors。 | 參數或欄位無效，見 errors。 |
| 400 | invalid_cursor游標無效，或不屬於這個列表。 | 游標無效，或不屬於這個列表。 |
| 400 | invalid_rate_key無法解析 rate_key，請重新查詢房價。 | 無法解析 rate_key，請重新查詢房價。 |
| 400 | idempotency_key_requiredPOST /bookings 需要 Idempotency-Key 請求標頭。 | POST /bookings 需要 Idempotency-Key 請求標頭。 |
| 401 | missing_api_key沒有帶 API Key。 | 沒有帶 API Key。 |
| 401 | invalid_api_key無法識別這個金鑰。 | 無法識別這個金鑰。 |
| 401 | api_key_revoked金鑰已撤銷，請換用其他金鑰。 | 金鑰已撤銷，請換用其他金鑰。 |
| 401 | api_key_expired金鑰已過期。 | 金鑰已過期。 |
| 403 | tenant_suspended租戶已暫停，請聯絡我們。 | 租戶已暫停，請聯絡我們。 |
| 403 | insufficient_scope金鑰缺少權限，見 required_scopes。 | 金鑰缺少權限，見 required_scopes。 |
| 404 | hotel_not_found沒有這家酒店，或已不再提供。 | 沒有這家酒店，或已不再提供。 |
| 404 | quote_not_found你的租戶下沒有這個報價。 | 你的租戶下沒有這個報價。 |
| 404 | booking_not_found你的租戶下沒有這個訂單。 | 你的租戶下沒有這個訂單。 |
| 409 | rate_unavailable這個房價已無法預訂。 | 這個房價已無法預訂。 |
| 409 | quote_expired報價已超過 15 分鐘，請重新報價。 | 報價已超過 15 分鐘，請重新報價。 |
| 409 | quote_changed價格或取消政策變了，請改用 current_quote 下單。 | 價格或取消政策變了，請改用 current_quote 下單。 |
| 409 | already_cancelled訂單已經取消。 | 訂單已經取消。 |
| 409 | not_cancellable已過免費取消截止時間、房價不可退，或訂單正在核對。 | 已過免費取消截止時間、房價不可退，或訂單正在核對。 |
| 409 | conflict訂單同時被另一個請求修改，請重新取得後重試。 | 訂單同時被另一個請求修改，請重新取得後重試。 |
| 422 | idempotency_key_reused這個 Idempotency-Key 已用於不同的請求體。 | 這個 Idempotency-Key 已用於不同的請求體。 |
| 429 | rate_limited超過每分鐘上限，按 Retry-After 等待後重試。 | 超過每分鐘上限，按 Retry-After 等待後重試。 |
| 500 | internal_error我們這邊出錯了。聯絡我們時請提供 request_id。 | 我們這邊出錯了。聯絡我們時請提供 request_id。 |
| 502 | payment_unavailable訂單已建立，但付款頁面開啟失敗。用同一個 Idempotency-Key 重試。 | 訂單已建立，但付款頁面開啟失敗。用同一個 Idempotency-Key 重試。 |
| 502 | supplier_error供應商返回了錯誤。 | 供應商返回了錯誤。 |
| 503 | supplier_unavailable供應商沒有回應，請稍後重試。 | 供應商沒有回應，請稍後重試。 |
開始接入
準備好接入你的平台了嗎？
介紹一下你的業務。我們會為你開通租戶、商定服務費，並從後台為你發放 API Key。