Loading
Bitvoya Edition
下一篇章
正在铺陈下一段旅程
在页面展开前，先把影像、目的地与细节整理成完整叙事。
灵感
视角
抵达
Bitvoya B2B API · v1
全球奢华酒店，一次调用即可接入。
在你自己的平台上搜索我们甄选的酒店、实时报价并预付下单。每个房价只有一个价格：人民币计价，已含税费和服务费。
基础地址https://app.bitvoya.com/api/b2b/v1
- 可直接生成各语言 SDK 的接口合同
- 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
付款异常，我们正在人工核对。
接口参考
全部接口
路径都相对于基础地址。展开接口即可查看参数和示例。
基础地址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。