能力边界：哪些事能用接口做完
开放平台把门锁的全生命周期抽象成资源，凡是业务系统会关心的事，都有对应接口：
| 资源 | 典型操作 |
|---|---|
| 设备 | 设备列表、绑定 / 解绑房间、在线状态、电量、固件版本、远程升级 |
| 权限 | 下发 / 撤销密码、卡片、人脸；设置有效期与可用时段 |
| 人员 | 创建人员、关联权限、离职或退租时批量注销 |
| 记录 | 按房间、人员、时间查询开锁流水与异常事件 |
| 场景 | 批量下发、分组授权、按楼栋 / 楼层检索 |
接入三步走
第一步：获取访问凭据
在开放平台申请 access_key，通过 OAuth 接口换取短周期 access_token：
| 请求 | GET https://t1.coslock.com/oauth/access_token?access_key=YOUR_KEY&grant_type=authorization_token |
|---|---|
| 响应 | {"errno":0,"statusCode":200,"data":{"accessToken":{"accessToken":"…","expire":3331}}} |
token 有时效，需在过期前刷新；不要把 access_key 写进前端代码。
第二步：建立业务对象映射
把你系统里的"房间 / 宿舍 / 工位"映射到门锁设备 ID。这一步做对了，后面所有权限操作都是简单的增删改。
第三步：事件驱动权限
不要在业务代码里到处写"开锁"，而是把权限当作业务事件的副产物：
- 办理入住 → 下发租期密码
- 换房 → 撤销旧房权限 + 下发新房权限
- 退房或离职 → 批量注销
- 工单完成 → 回收临时权限
幂等很重要。网络重试、消息重投在真实系统里天天发生。下发权限接口建议带业务侧幂等键（如订单号 + 版本号），避免重复下发产生多条冗余权限。
PMS 与企业系统对接
已对接的酒店与公寓管理系统包括：订单来了、云掌柜、番茄来了、住哲、百居易、去呼呼、客栈通、青芒果、麦田云等。使用这些系统时通常只需配置凭据，无需开发；自有系统则按上方三步自行集成。
私有化部署与源码交付
对数据落地、信创环境、集团统一管控有要求的客户，可选择：
- 私有化部署：整套服务部署在客户自有服务器，数据不出内网
- 源码级交付：核心系统源码交付，客户可自主二次开发与长期维护
- 混合架构：边缘侧本地部署保障可用性，云端负责集中运维
交付范围、许可方式与技术支持周期在商务阶段以合同约定。
技术支持
- 接口文档与在线调试环境
- 接入期联调支持（沙箱环境 + 技术对接人）
- 生产期 7×24 故障响应
申请凭据或技术对接：contact@coslock.com · 19157809376 · 微信 hzcoslock
常见问题
接口文档和调试环境怎么获取？
联系 contact@coslock.com 或微信 hzcoslock 申请接入凭据，通过后开通接口文档与在线调试环境（沙箱）。
access_key 和 token 有什么区别？
access_key 是长期凭据，用于换取短周期 access_token；实际业务请求携带 token，过期需刷新。access_key 严禁写入前端代码。
支持哪些语言接入？
标准 REST + JSON + HTTPS，任何能发 HTTP 请求的语言都可以接入，与具体框架无关。
能私有化部署吗？
可以。支持整套系统部署在客户自有服务器，核心系统可源码级交付，具体范围以合同约定。
接口有调用频率限制吗？
有，按接入方案配置不同配额；批量下发建议按批处理而非逐条请求，既快也不容易触发限流。