Service & Support

Developer APIs · Integrate PMS, apps, and custom UIs

康汇开发者平台为集成商、PMS/CRS 厂商与行业 ISV 提供标准化 RESTful API 与开放 SDK，覆盖设备接入、客房状态、场景控制、能耗数据与事件订阅。通过云端或本地网关，快速将康汇客控能力嵌入您的酒店运营与楼宇管理系统。

下载 SDK 与文档 · 云管理平台 · 申请 API 密钥

平台能力

RESTful API

JSON 请求/响应，HTTPS 传输，版本化路径，便于前后端与第三方系统对接。
多语言 SDK

提供 Java / Python / Node.js 示例与签名工具，缩短联调与上线周期。
Webhook 事件

房态变更、告警、场景执行结果等事件主动推送，支持重试与签名校验。
沙箱环境

独立测试租户与模拟设备，上线前完成接口联调与压力验证（需申请开通）。

API 模块

按业务域划分接口，支持按需授权；具体字段与限流策略以正式文档为准。

设备与点位

查询 RCU、面板、传感器在线状态；读写点位数值、开关量与模拟量。
- 设备列表
- 点位读写
- 批量同步
客房与房态

同步入住/退房、勿扰、清理、SOS 等房态；与 PMS 房号映射。
- 房态同步
- 房号映射
- 入住联动
场景与联动

触发欢迎、离人断电、会议模式等场景；查询执行结果与失败原因。
- 场景触发
- 定时任务
- 逻辑查询
能耗与报表

按客房/楼层/公区汇总用电与空调运行数据，导出报表接口。
- 能耗查询
- 统计报表
- 数据导出
告警与运维

订阅设备离线、通讯异常、负载告警；对接运维工单系统。
- 告警列表
- Webhook
- 工单回调
项目与权限

多酒店/多项目租户隔离；AppKey、角色与接口范围管理。
- 租户管理
- OAuth2
- 审计日志

快速开始

注册开发者账号

通过商务或技术支持提交集成申请，获取 AppKey / AppSecret。
配置回调地址

在开发者控制台登记 Webhook URL，用于接收房态与告警事件。
沙箱联调

使用测试项目 ID 调用接口，验证签名、鉴权与业务字段。
生产上线

完成验收后切换生产环境密钥，按 SLA 监控调用量与错误率。

示例：查询客房设备状态

# GET 设备列表（节选）
GET /v1/projects/{projectId}/rooms/{roomNo}/devices
Authorization: Bearer <access_token>
Content-Type: application/json

# 响应 200
{
  "roomNo": "1208",
  "status": "occupied",
  "devices": [
    { "id": "rcu-01", "online": true },
    { "id": "panel-master", "online": true }
  ]
}

常用接口一览

以下为典型 REST 路径示例；完整 OpenAPI 规范请从下载中心获取。

方法	路径	说明
POST	/v1/oauth/token	获取访问令牌（Client Credentials）
GET	/v1/projects/{id}/rooms	分页查询客房列表及房态摘要
GET	/v1/projects/{id}/rooms/{roomNo}/devices	查询指定客房设备及在线状态
PUT	/v1/projects/{id}/rooms/{roomNo}/scene/{sceneId}	触发场景（如欢迎模式、离人断电）
POST	/v1/projects/{id}/rooms/{roomNo}/points	批量写入点位（开关、调光、空调设定等）
GET	/v1/projects/{id}/energy/summary	按时间范围查询能耗汇总
POST	/v1/webhooks/subscriptions	注册 Webhook 订阅（房态、告警等事件）

协议与生态

除 HTTP API 外，亦支持现场总线与第三方平台对接，满足酒店与楼宇多样化集成需求。

REST / HTTPS

云端与本地网关统一 API 风格，JSON 数据交换

BACnet / Modbus

楼宇自控、暖通、电表等子系统协议转换

MQTT

低带宽场景设备上报与指令下发

KNX / 生态插件

与 KNX、Home Assistant 等互联方案配合使用

接入流程

提交申请

说明集成场景、预计调用量与上线时间

开通密钥

分配沙箱与生产环境凭证

联调验收

技术支持协助完成接口与 Webhook 测试

正式上线

切换生产环境并纳入运维监控

常见问题

如何获取 API 密钥？

面向签约集成商与战略客户开放。请通过商务或技术支持提交集成方案说明，审核通过后在开发者控制台创建应用并获取 AppKey、AppSecret。

是否支持本地部署网关？

支持。大型酒店集团可选用本地边缘网关，在离线与低时延场景下提供与云端一致的 API 能力；具体架构由项目方案确定。

调用频率是否有限制？

默认按应用维度设置 QPS 与每日配额；批量项目可申请提升。超出限制将返回 429，建议实现指数退避重试。

Webhook 如何保证安全？

事件体附带 HMAC 签名与时间戳，接收方需校验签名并拒绝过期请求。建议使用 HTTPS 端点，IP 白名单可按需配置。

与云管理平台有何区别？

云管理平台面向运维人员的可视化操作；开发者 API 面向系统集成与自动化，适合 PMS、CRM、能源管理平台等二次开发场景。二者可配合使用。

需要现场培训或售后支持？

我们提供 API 联调培训、项目验收辅导与全生命周期技术支持。

专业培训服务售后服务政策

Service & Support

平台能力

RESTful API

多语言 SDK

Webhook 事件

沙箱环境

API 模块

设备与点位

客房与房态

场景与联动

能耗与报表

告警与运维

项目与权限