用途：面向需要对接 Cloudbeds 酒店平台（PMS、预订引擎、渠道管理、支付、BI）的开发者，整理其公开 API 的调用要点，用于构建物业管理、预订、支付、会计与渠道集成。
主要能力与接口面：API 分为多个产品，共享认证但路径风格、请求格式与错误结构不同。PMS Classic v1.3（当前）与 v1.2 为 RPC 风格，基址 https://api.cloudbeds.com/api/v1.3/，请求体为 application/x-www-form-urlencoded；PMS v2 为 REST，基址 https://api.cloudbeds.com/，请求体 JSON；另有 Accounting v1.0、Data Insights v1.1、Group Profile v1.0、Fiscal Documents v1、Pay-By-Link v2、Payments Vault v1、OTA Build-To-Us v5.3。PMS v1.1 已于 2025-03-31 退役，所有调用必须使用 HTTPS，响应带 X-Request-ID。OpenAPI 规范见 https://github.com/cloudbeds/openapi-specs。
认证：优先使用 API Key（前缀 cbat_），也可用 OAuth 2.0 授权码。令牌以 Authorization: Bearer <token> 或 x-api-key 发送。API Key 可通过授权重定向换取（grant_type=urn:ietf:params:oauth:grant-type:api-key）或邮件交付；OAuth 访问令牌 8 小时过期，刷新令牌 365 天滑动过期。授权码 10 分钟内有效且单次使用。API Key 连续 30 天未使用则失效。
多物业：每个物业有数字 propertyID。Classic PMS 以查询/表单参数传入（支持逗号分隔）；PMS v2 及更新 API 以请求头 x-property-id 传入。多物业密钥缺少 propertyID 会返回错误。
请求与错误：Classic PMS 的 POST/PUT 为表单编码而非 JSON，多值字段需重复数组键。Classic PMS 业务错误仍返回 HTTP 200，需检查 success 字段；PMS v2 及更新 API 使用 RFC 7807 的 application/problem+json；OAuth 错误使用标准结构。
限流与 Webhook：物业用户 5 req/s，技术伙伴 10 req/s，超限通过邮件通知并可能暂停凭证或封 IP，未文档化 429/Retry-After 头。POST 不支持 Idempotency-Key，需用业务键去重。Webhook 通过 postWebhook/getWebhooks/deleteWebhook 管理，需 2xx 确认，最多重试 5 次、间隔 1 分钟，处理超过 2 秒视为超时并重发，顺序不保证、可能重复，无 HMAC 签名头。
数据模型要点：所有 ID 为字符串；reservationID 仅物业内唯一；日期为物业本地 YYYY-MM-DD；时间字段有 *UTC 变体；金额为 JSON 数字，注意精度；事件负载大小写不一致，需不区分大小写解析；分页方式因 API 而异。
限制：无法创建新房价计划、无法处理退款、API 创建预订不自动扣定金、getTransactions 不返回待处理交易、无真正 SSO。无自助沙箱，需通过合作伙伴审批获取访问。官方 Python SDK 见 https://github.com/cloudbeds/cloudbeds-api-python（需 Python ≥ 3.9），另有支付 Web 组件；无官方 JS/TS、PHP、Ruby、Java、Go SDK。支持邮箱 integrations@cloudbeds.com。