cloudbeds-api

Cloudbeds API

Cloudbeds は、ホスピタリティ向けプラットフォーム（PMS、予約エンジン、チャネルマネージャー、決済、BI）です。公開 API は複数の REST 製品にわたり、共通の認証システムを使用しますが、パス形式、リクエスト形式、エラー形式は製品ごとに異なります。

API 製品一覧

API	ベース URL	パス形式	リクエストボディ
PMS Classic v1.3（現行）	https://api.cloudbeds.com/api/v1.3/	RPC 形式（/postReservation）	application/x-www-form-urlencoded
PMS Classic v1.2	https://api.cloudbeds.com/api/v1.2/	RPC 形式	フォーム URL エンコード
PMS v2（モジュール式）	https://api.cloudbeds.com/	REST（/addons/v1/addons）	application/json
Accounting v1.0	https://api.cloudbeds.com/accounting/v1.0/	REST	JSON
Data Insights v1.1	https://api.cloudbeds.com/datainsights/v1.1/	REST	JSON
Group Profile v1.0	https://api.cloudbeds.com/group-profile/v1/	REST	JSON
Fiscal Documents v1	https://api.cloudbeds.com/fiscal-document/v1/	REST	JSON
Pay-By-Link v2	https://api.cloudbeds.com/payments/v2/pay-by-link	REST	JSON
Payments Vault v1	https://api.payments.cloudbeds.com/vault/v1/	REST	JSON
OTA Build-To-Us v5.3	パートナーがホスト（https://api.your-ota.com/cloudbeds）	RPC 形式	JSON

PMS v1.1 は 2025-03-31 に廃止されました。すべての呼び出しで HTTPS が必須です。すべてのレスポンスには、サポートやデバッグ用の X-Request-ID が含まれます。

すべての API の OpenAPI 仕様は https://github.com/cloudbeds/openapi-specs にあります（src/ の下に製品ごとに 1 ファイル）。クライアントを生成する際は、コミットを固定してください。

認証 — 1 つの Authorization: Bearer ... に至る 3 つの方法

Cloudbeds は OAuth 2.0 よりも、長期間有効な API キー（cbat_ で始まる）を推奨しています。どちらも Authorization: Bearer <token> または x-api-key: <token> として送信できます。

方法	適した用途	詳細
API キー（自動配信）	マーケットプレイス／テクノロジーパートナーのアプリ	OAuth のように認可 → リダイレクトで code を受け取り → grant_type=urn:ietf:params:oauth:grant-type:api-key を指定して cbat_ キーと交換
API キー（メール配信）	よりシンプルなパートナー連携、Flow A のみ	ユーザーが Connect をクリックすると、キーがパートナーの受信箱にメールで送信され、システムに貼り付けられます
OAuth 2.0 Authorization Code	レガシー／代替手段	アクセストークン（expires_in: 28800 = 8 時間）+ リフレッシュトークン（スライド方式の有効期限 365 日）

• 認可リダイレクトから取得した code は、10 分間有効で、1 回のみ使用できます。
• API キーは、30 日連続で使用されない場合を除き、有効期限がありません。
• リフレッシュトークンから API キーへの移行には grant_type=refresh_token_exchange を使用します（1 回限り）。

OAuth フロー全体、すべてのスコープ文字列、複数プロパティの処理、および /userinfo エンドポイントについては、references/authentication.md を参照してください。

複数プロパティの処理

各プロパティには数値の propertyID があります（ペイロードでは文字列化されています）。Classic PMS では、propertyID をクエリ／フォームパラメーターとして指定します（カンマ区切りのリストに対応）。PMS v2 と新しい API ではヘッダーとして指定します。ほとんどの仕様では x-property-id、Fiscal Documents の仕様では X-Property-ID と表記されます（HTTP ヘッダーでは大文字と小文字が区別されないため、x-property-id を送信してください）。

複数プロパティに対応するキーで propertyID を指定しない場合、次のエラーが返されます：{"success": false, "message": "Please specify \"propertyID\" parameter for this call"}。

1 つの API キーを、1 つのプロパティまたは組織全体（関連付け）にスコープできます。OAuth トークンのレスポンスには、{type: "property"|"association", id} エントリーを列挙する resources 配列が含まれます。

リクエスト形式に関する注意点

• Classic PMS v1.3 の POST／PUT ボディは JSON ではなく、フォーム URL エンコード形式です。 新しい連携では、必ずここでつまずきます。複数値フィールドでは application/x-www-form-urlencoded を使用し、配列のキーを繰り返してください（rooms[]=...&rooms[]=...）。
• PMS v2 と、それ以降のすべてのモジュールでは application/json を使用します。
• レスポンスボディは Content-Type: application/json の JSON です。PMS v2 のエラーでは application/problem+json（RFC 7807）を使用します。

エラーエンベロープ — 2つの形式

Classic PMS は業務エラーでも HTTP 200 を返すため、success を確認してください：

{ "success": true,  "data": {...} }
{ "success": false, "message": "Descriptive error" }

PMS v2／新しい API は RFC 7807 に準拠しています：

{ "type": "unauthorized", "title": "Unauthorized", "status": 401, "detail": "401 UNAUTHORIZED" }

OAuth エラー は OAuth 標準の形式を使用します：

{ "error": "server_error", "error_description": "The authorization code is invalid or has expired." }

ステータスコード表と再試行の指針については、references/errors-and-limits.md を参照してください。

レート制限

• 施設／グループ施設のユーザー：5 req/s。
• テクノロジーパートナー：10 req/s。
• 適用は帯域外で行われます。Cloudbeds はパートナーにメールで通知し、認証情報を一時停止したり、送信元 IP をブロックしたりする場合があります。HTTP 429／Retry-After／X-RateLimit-* ヘッダーについては、ドキュメントに記載されていません。
• POST では Idempotency-Key をサポートしていません。業務キー（例：postReservation の thirdPartyIdentifier）を使って重複を排除してください。
• 指針：ポーリングよりウェブフックを優先し、ユースケースごとの呼び出し回数を約8回未満に抑えてください。

ウェブフック

PMS エンドポイント経由で登録します：postWebhook（作成）、getWebhooks（一覧取得）、deleteWebhook?subscriptionID=...（削除）。イベント名は object/action 形式です（例：reservation/created）。登録するスコープは、エンティティを読み取るスコープと同じにします（例：すべての reservation/* イベントには read:reservation）。

配信の保証：

• エンドポイントからの 2xx ACK が必要です。
• 再試行：最大5回、1分間隔です。
• 2秒を過ぎてから返されたハンドラーの応答はタイムアウトとして扱われ、ステータスが 2xx でも再配信が行われます。
• 順序は保証されません。
• 重複は想定されます（1回のユーザー操作で複数のウェブフックが発生する場合や、2秒のタイムアウト後に再試行される場合があります）。
• 公開されている HMAC 署名ヘッダーはありません。真正性は、（a）HTTPS エンドポイント URL の秘匿、（b）後続の API 呼び出しでイベントペイロード内の ID を照合することに依存します。

ペイロードの形式とスコープを含むイベントカタログ全体については、references/webhooks.md を参照してください。

コアドメインのエンドポイント（PMS Classic v1.3）

完全なカタログは references/endpoints.md を参照してください。よく使われるもの：

ドメイン	主なエンドポイント
予約	postReservation、getReservation、getReservations、putReservation、postRoomCheckIn、postRoomCheckOut
空室状況	getAvailableRoomTypes、getRoomTypes、getRoomsUnassigned
料金	getRate、getRatePlans、patchRate / putRate（非同期。jobReferenceID を返します）
ゲスト	getGuest、getGuestList、postGuest、putGuest、postGuestsToRoom
支払い	getPaymentMethods、getPaymentsCapabilities、postCharge、postPayment、postCreditCard、postVoidPayment
施設	getHotels、getHotelDetails（propertyTimezone、propertyCurrency を含みます）
ハウスキーピング	getHousekeepingStatus、postHousekeepingStatus、postHousekeepingAssignment
ウェブフック	postWebhook、getWebhooks、deleteWebhook

データモデルの落とし穴（影響大）

• すべての ID は文字列です。 PMS v1.2 への移行により、多くの整数 ID が文字列に変換されました。Webhook ペイロードには propertyID（整数）と propertyID_str（文字列）の両方が含まれることがよくあります。_str 形式を使用してください。
• reservationID は施設ごとに一意であり、全体で一意ではありません。
• subReservationID の形式は {reservationID}-{n} です。主室の subReservationID は reservationID と同じです。
• 日付フィールド（startDate、endDate）は、施設のローカルな暦日で、形式は YYYY-MM-DD、タイムゾーンはありません。
• 日時フィールドはペアで提供されます。dateCreated / dateCreatedUTC、dateModified / dateModifiedUTC です。施設をまたいだ同期や差分比較には、*UTC 形式を使用してください。
• Webhook の timestamp はマイクロ秒の小数部を含む UNIX 秒（例：1611758157.431234）で、文字列ではなく数値です。
• 金額は classic PMS では JSON の数値（小数）です。精度が失われるリスクがあります。表示形式を整えるには、getHotelDetails から propertyCurrency を取得してください。
• イベントペイロードでは大文字・小文字の使い方に一貫性がありません（propertyID と propertyId）。大文字・小文字を区別せずに解析してください。
• ページネーションの方式はさまざまです。classic PMS は pageNumber / pageSize または日付範囲の resultsFrom / resultsTo を使用し、PMS v2 は limit（最大 500）/ offset を使用します。

API ごとの ID 形式、日付とタイムゾーンのルール、ページネーションの方式については、references/data-model.md を参照してください。

API でできないこと（読み取り専用／未対応）

• 新しい料金プランの作成（既存の料金プランの読み取り／更新は patchRate / putRate のみ）。
• 返金処理 — Cloudbeds UI で手動操作する必要があります。
• API で作成した予約に対するデポジットの自動請求（postReservation で cardToken を送信すると、デポジットルールは無視されます）。
• getTransactions からの保留中トランザクションの取得。
• 真の SSO / OpenID Connect — userinfo は ID を返しますが、アプリのログイン認証情報はアプリ側で発行します。

統合パターン

エンドツーエンドの予約作成、決済フロー（有効な 4 つの選択肢：SDK ウェブコンポーネント、Vault トークン化、Pay-By-Link、Stripe パススルー）、非同期ジョブ追跡を伴う料金の一括更新、複数施設での運用や v1.2 移行に関する注意点については、references/integration-patterns.md を参照してください。

サンドボックスとテスト

セルフサービスのサンドボックスはありません。利用するにはパートナーシップの承認が必要です。

1. https://www.cloudbeds.com/partner-with-cloudbeds/ の「Partner with Us」フォームを送信します。
2. 会社名、ウェブサイト、統合カテゴリを記載して、[email protected] にメールを送信します。

公開されている Postman コレクションへのリンクは、https://developers.cloudbeds.com/docs/postman-api-collection.md にあります。Webhook エンドポイントのテストには、https://webhook.site の利用を推奨します。

エージェント向けリソース

Cloudbeds は LLM を優先したドキュメントを公開しています。

• https://developers.cloudbeds.com/llms.txt — .md ドキュメントのサイトマップ全体。
• 任意の /docs/<slug> または /reference/<slug> URL の末尾に .md を追加すると、Markdown を取得できます。
• 公式 MCP サーバー：https://developers.cloudbeds.com/mcp（HTTP トランスポート）。claude mcp add --transport http cloudbeds-developers https://developers.cloudbeds.com/mcp を使って追加します。

SDK、Postman コレクション、MCP のセットアップの一覧については、references/resources.md を参照してください。

SDK

• Python（公式、自動生成）：https://github.com/cloudbeds/cloudbeds-api-python — PMS v2 に対応し、Python ≥ 3.9 が必要です。
• Payment Element ウェブコンポーネント（ブラウザー）：GitHub Packages の @cloudbeds/payment-element-webcomponent — PCI に準拠したカード情報入力 UI です。
• 公式の JavaScript/TypeScript、PHP、Ruby、Java、Go 向け REST SDK はありません。openapi-generator-cli を使って OpenAPI 仕様からクライアントを生成してください。

サポート

• メール：[email protected]（唯一の公式窓口）。
• API のバグを報告する際は、レスポンスヘッダーの X-Request-ID を含めてください。
• Stack Overflow タグ：cloudbeds。