Loading
Bitvoya Edition
次の章へ
次の滞在を整えています
ページが開く前に、写真、行き先、ディテールを静かに編集中です。
選定
視点
到着
Bitvoya B2B API · v1
世界の名門ホテルを、API ひとつで。
厳選ホテルの検索、リアルタイムの見積もり、事前決済の予約を、貴社のプラットフォームから。料金プランごとに価格はひとつ。人民元建てで、税とサービス料を含みます。
ベース URLhttps://app.bitvoya.com/api/b2b/v1
- 各言語の SDK を生成できる API 仕様
- OpenAPI 3.1
- 税・サービス料込みの総額ひとつ
- CNY
- ホテル情報の対応言語
- 5
- 見積もりが料金を確保する時間
- 15分
クイックスタート
API キーからホテル確定まで
6 回の呼び出しで予約が完了します。各ステップにリクエストとレスポンスを添えています。
- 01GET/me
キーを確認
すべてのリクエストで API キーを Bearer トークンとして送ります。GET /me は、キーが属するテナント、スコープ、毎分のリクエスト上限を返します。
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 室 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- 2 泊分の客室料金込み
- 税金・諸費用込み
- Bitvoya サービス料込み
price
Stripe で事前に支払う金額
¥1,709.65
"price": { "amount": "1709.65", "currency": "CNY" }宿泊税EUR 18.48 約 ¥137.38
pay_at_hotel · ホテルで現地払い。price には含まれません
予約ステータス
6 つのステータスで、状況は明確に
予約は 1 本の主な流れに沿って進みます。それ以外のステータスは、何が起きて次に何をすべきかを示します。
主な流れ
- awaiting_payment
payment.url での支払い待ち。決済ページの有効期限は 30 分です。
- pending_confirmation
支払い済み。ホテルに確認中で、数時間かかることがあります。
- confirmed
ホテルが確定しました。hotel_confirmation_number が入ります。
その他の結果
- payment_failed
決済ページの期限切れ、または支払いの失敗。もう一度予約してください。
遷移元
awaiting_payment - cancelled
キャンセル済み。返金の状況は payment.status で確認できます。
遷移元
awaiting_paymentpending_confirmationconfirmed - under_review
支払いに問題があり、当社で確認しています。
API リファレンス
すべてのエンドポイント
パスはベース URL からの相対パスです。各エンドポイントを開くと、パラメータと例が表示されます。
ベース URLhttps://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/hotelsID 順のホテル一覧。目的地やブランドで絞り込めます。条件なしなら全件同期に。
catalog:read
ID 順のホテル一覧。目的地やブランドで絞り込めます。条件なしなら全件同期に。
catalog:read
パラメータ
destination_idquerystring · digits
brand_idquerystring · digits
cursorquerystring · next_cursor
limitqueryinteger · 1–100 · 既定値
50
例
GET/hotels/{hotel_id}ホテル 1 軒の詳細：住所、位置、星評価、チェックイン・アウト時刻、説明、設備、画像。
catalog:read
ホテル 1 軒の詳細：住所、位置、星評価、チェックイン・アウト時刻、説明、設備、画像。
catalog:read
パラメータ
hotel_idpath必須string · digits
例
GET/brandsホテルブランドと、それぞれのホテル数。
catalog:read
ホテルブランドと、それぞれのホテル数。
catalog:read
パラメータ
パラメータはありません。
例
料金と見積もり
GET/hotels/{hotel_id}/rates1 回の宿泊に対する客室タイプと予約可能な料金。安い順。
rates:read
1 回の宿泊に対する客室タイプと予約可能な料金。安い順。
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}予約 1 件：ステータス、支払い状況、ホテルの確認番号。
bookings:read
予約 1 件：ステータス、支払い状況、ホテルの確認番号。
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/returnsuccess_url を指定しない場合に、支払い後に戻る既定のページ。
キー不要
success_url を指定しない場合に、支払い後に戻る既定のページ。
キー不要
パラメータ
パラメータはありません。
例
GET/openapi.jsonこの API の OpenAPI 3.1 仕様。
キー不要
この API の OpenAPI 3.1 仕様。
キー不要
パラメータ
パラメータはありません。
例
共通仕様
オープンな標準に基づいて
おなじみの HTTP の慣習どおり。専用 SDK は必要ありません。
認証
キーは Authorization: Bearer で送ります。キーごとにスコープを設定でき、1 テナントあたり最大 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 が必須です。同じキーと同じ本文なら元の予約を返し、同じキーで本文が異なれば拒否します。
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_keyrate_key を読み取れません。料金を取得し直してください。 | rate_key を読み取れません。料金を取得し直してください。 |
| 400 | idempotency_key_requiredPOST /bookings には Idempotency-Key ヘッダーが必要です。 | POST /bookings には Idempotency-Key ヘッダーが必要です。 |
| 401 | missing_api_keyAPI キーが送られていません。 | API キーが送られていません。 |
| 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 キーを発行します。