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 风格	form-urlencoded
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/ 下都有一个文件）。生成客户端时请固定到某个 commit。

身份验证——通过三种方式使用同一个 Authorization: Bearer ...

Cloudbeds 更推荐使用 API 密钥（长期有效，前缀为 cbat_），而非 OAuth 2.0。两者都可以通过 Authorization: Bearer <token> 或 x-api-key: <token> 传递。

方式	适用场景	详情
API 密钥（自动交付）	Marketplace / Technology Partner 应用	类似 OAuth 的 authorize → 重定向返回 code → 使用 grant_type=urn:ietf:params:oauth:grant-type:api-key 交换为 cbat_ 密钥
API 密钥（电子邮件交付）	更简单的合作伙伴集成，仅限 Flow A	用户点击 Connect，密钥会通过电子邮件发送到合作伙伴收件箱，然后粘贴到你的系统中
OAuth 2.0 Authorization Code	旧版 / 替代方案	访问令牌（expires_in: 28800 = 8h）+ 刷新令牌（365d 滑动过期）

• authorize 重定向返回的 code 有效期为 10 分钟，且只能使用一次。
• API 密钥在连续 30 天未使用之前不会过期。
• 刷新令牌迁移到 API 密钥：grant_type=refresh_token_exchange（仅限一次）。

有关完整的 OAuth 流程、所有 scope 字符串、多物业处理以及 /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"}。

一个 API 密钥可以限定为单个物业，也可以限定为整个组织（association）。OAuth 令牌响应包含一个 resources 数组，其中列出 {type: "property"|"association", id} 条目。

请求格式注意事项

• Classic PMS v1.3 的 POST/PUT 正文使用 form-urlencoded，而非 JSON。 这是每个新集成开发者都会遇到的问题。请使用 application/x-www-form-urlencoded，并为多值字段重复数组键（rooms[]=...&rooms[]=...）。
• PMS v2 和所有较新的模块都使用 application/json。
• 响应正文为 JSON，Content-Type: application/json；PMS v2 错误使用 application/problem+json（RFC 7807）。

错误响应 — 两种格式

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）。
• 建议：优先使用 Webhook，而非轮询；将每个用例的调用次数控制在约 8 次以内。

Webhook

通过 PMS 端点订阅：postWebhook（创建）、getWebhooks（列出）、deleteWebhook?subscriptionID=...（移除）。事件采用 object/action 命名方式（例如 reservation/created）。订阅所需的作用域应与读取实体所需的作用域相同（例如，所有 reservation/* 事件都需要 read:reservation）。

投递保证：

• 端点必须返回 2xx 确认。
• 最多重试 5 次，间隔 1 分钟。
• 处理程序在 2 秒后返回的响应会被视为超时，并触发重新投递，即使状态码为 2xx 也是如此。
• 不保证顺序。
• 可能会收到重复事件（一次用户操作可能触发多个 Webhook；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
Webhook	postWebhook、getWebhooks、deleteWebhook

数据模型陷阱（影响重大）

• 所有 ID 都是字符串。 PMS v1.2 迁移将许多整数 ID 转换成了字符串。Webhook 负载通常同时包含 propertyID（整数）和 propertyID_str（字符串）——请使用 _str 变体。
• reservationID 在每个 property 内唯一，而非全局唯一。
• subReservationID 的格式为 {reservationID}-{n}；主房间的 subReservationID 等于 reservationID。
• 日期字段（startDate、endDate）是 property 本地日历日期，格式为 YYYY-MM-DD，不含时区。
• 日期时间字段成对出现：dateCreated / dateCreatedUTC、dateModified / dateModifiedUTC。跨 property 同步和比较差异时，请使用 *UTC 变体。
• Webhook timestamp 是带微秒小数的 UNIX 秒数（例如 1611758157.431234）——这是数值，不是字符串。
• 经典 PMS 中的金额是 JSON 数字（十进制）；精度损失是真实风险。请从 getHotelDetails 获取 propertyCurrency，用于显示格式化。
• 事件负载的大小写不一致（propertyID 与 propertyId）——请忽略大小写进行解析。
• 分页方式各不相同：经典 PMS 使用 pageNumber / pageSize 或 resultsFrom / resultsTo 日期边界；PMS v2 使用 limit（最大 500）/ offset。

请参阅 references/data-model.md，了解各 API 的 ID 格式、日期／时区规则和分页方式。

API 无法执行的操作（只读／缺失）

• 创建新的费率计划（只能通过 patchRate / putRate 读取／更新现有计划）。
• 处理退款——只能在 Cloudbeds UI 中手动操作。
• 对通过 API 创建的预订自动收取定金（通过 postReservation 发送 cardToken 时，定金规则会被忽略）。
• 从 getTransactions 返回待处理交易。
• 真正的 SSO / OpenID Connect——userinfo 会返回身份信息，但应用登录凭据由你的应用签发。

集成模式

端到端预订创建、支付流程（4 种可行选项：SDK Web 组件、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。建议通过 https://webhook.site 测试 Webhook 端点。

Agent 资源

Cloudbeds 提供面向大模型的文档页面：

• 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 添加。

请参阅 references/resources.md，获取 SDK、Postman 集合和 MCP 设置的完整列表。

SDK

• Python（官方，自动生成）：https://github.com/cloudbeds/cloudbeds-api-python — 跟踪 PMS v2，需要 Python ≥ 3.9。
• Payment Element Web 组件（浏览器）：GitHub Packages 上的 @cloudbeds/payment-element-webcomponent — 符合 PCI 安全要求的银行卡信息采集 UI。
• 没有官方的 JavaScript/TypeScript、PHP、Ruby、Java 或 Go REST SDK。请使用 openapi-generator-cli 从 OpenAPI 规范生成客户端。

支持

• 邮箱：[email protected]（唯一官方渠道）。
• 报告 API Bug 时，请提供响应头中的 X-Request-ID。
• Stack Overflow 标签：cloudbeds。