OPEN PLATFORM

小界设备开放平台
接口文档

通过简单的 HTTP API 对接，让您的系统快速接入智能设备控制能力，实现无人化、智能化运营

文档版本 v1.0.0  |  更新日期 2026-03-30
快速直达：

三方接入优势

在您现有的系统中，只需在关键业务节点调用一个接口，即可驱动门店全套智能设备

🚀

极速对接

仅需 2 个 HTTP 接口，无 SDK 依赖，任何语言 / 平台均可接入，最快 1 天完成联调

🏠

零硬件改造

小界负责设备安装与调试，三方无需关心硬件协议，只需调用云端 API

🔒

安全可靠

Token 鉴权 + 请求幂等（reqId 去重），防止重复执行，保障业务安全

⚙️

场景丰富

开大门、开包间门、开始消费、结束消费、续费提醒等场景一键触发，设备自动联动

📊

低成本智能化

三方只需在现有系统中增加事件通知，无需重建业务流程，即可实现无人值守

🔧

持续扩展

新增设备类型与场景时自动适配，三方无需修改代码，平台统一升级

业务对接流程

从申请到上线，仅需四步

1
申请凭证
三方公司向小界申请 appId + appKey
→
2
提供映射表
三方提供门店授权ID 及包间/空间ID对应表
→
3
设备安装
小界进行设备安装 完成门店与设备关联
→
4
接口调用
三方调用控制接口 驱动场景设备联动

ID 规范说明

  • 门店唯一ID（shopId）：32 位字符串，由三方分配，需全局唯一
  • 包间/空间唯一ID（roomId）：32 位字符串，由三方分配，同一门店内唯一
  • 小界将根据上述映射表，在后台完成门店授权绑定和设备与空间的关联配置

接口调用流程

先获取令牌，再携带令牌调用业务接口

1
获取 Token
GET /token 传入 appId + appKey
→
2
携带 Token
后续请求 Header 中添加 xj-open-token
→
3
场景控制
POST /scene 传入场景参数

Token 说明

  • Token 有效期 30 天，过期后需重新获取
  • 多个服务节点可独立获取 Token，互不冲突，均可使用
  • 建议在过期前主动刷新，避免业务中断
  • 接口基础地址：https://wx.52tuili.com/api/open/device

鉴权接口 - 获取 Token

GET/token

根据 appId 和 appKey 获取访问令牌

请求参数（Query）

参数类型必填说明
appIdString必填小界分配的应用ID
appKeyString必填小界分配的应用密钥

请求示例

GET https://wx.52tuili.com/api/open/device/token?appId=your_app_id&appKey=your_app_key

成功响应

{
  "code": 0,
  "msg": "success",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."  // Token 字符串，有效期 30 天
}

失败响应

{
  "code": -1,
  "msg": "appId或appKey无效",
  "data": null
}

场景控制接口

POST/scene

触发指定门店包间的场景联动控制（如开门、开始消费、结束消费等）

请求头

Header说明
xj-open-token通过鉴权接口获取的 Token
Content-Typeapplication/x-www-form-urlencoded

请求参数（Form）

参数类型必填说明
shopIdString(32)必填门店唯一ID（三方分配，需与映射表一致）
roomIdString(32)必填包间/空间唯一ID（三方分配，需与映射表一致）
reqIdString必填请求唯一ID，用于幂等去重，防止重复执行
sceneTypeString必填场景类型，见下方场景定义表
sceneValueString按需场景值，部分场景需要传入（如续费提醒的剩余分钟数）

请求示例（cURL）

curl -X POST https://wx.52tuili.com/api/open/device/scene \
  -H "xj-open-token: eyJhbGciOiJIUzI1Ni..." \
  -d "shopId=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -d "roomId=r1s2t3u4v5w6x7y8z9a0b1c2d3e4f5g6" \
  -d "reqId=req_20260330_001" \
  -d "sceneType=START" \
  -d "sceneValue="

成功响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

失败响应

{
  "code": -1,
  "msg": "门店未授权或不存在",
  "data": null
}

场景类型定义

sceneType 枚举值及说明

sceneType场景名称sceneValue说明
OPEN_MAIN_DOOR开大门-开启门店大门，通常用于顾客到店时
OPEN_ROOM_DOOR开包间门-开启指定包间/空间的门锁
START开始消费-触发消费开始场景：开灯、开空调、开设备、开包间/空间门等联动
END结束消费-触发消费结束场景：关灯、关空调、结束播报、开包间/空间门等联动
RENEW_REMIND续费提醒15 / 10 / 5续费倒计时提醒，值为剩余分钟数。需设备支持语音/屏幕提醒
DEVICE_ON设备通电用于保洁、维护、老板、店员等一键开电、开包间/空间门
DEVICE_OFF设备关电用于保洁、维护、老板、店员等一键关电

💡 典型调用时序

以 KTV 包间消费为例，展示完整的接口调用链路：

OPEN_MAIN_DOOR
顾客到店
→
OPEN_ROOM_DOOR
进入包间
→
START
开始消费
→
RENEW_REMIND
续费提醒
→
END
结束消费

响应状态码

code说明处理建议
0成功-
-1业务失败（详见 msg 描述）根据 msg 排查原因
401Token 无效或已过期重新调用 /token 获取新令牌
403无权限访问该门店检查门店授权关系是否已建立
429请求频率过高降低调用频率，建议单门店 QPS ≤ 10
500服务器内部错误稍后重试，若持续异常请联系小界技术支持

常见问题

1Token 过期了会怎样？

接口会返回 code: 401，此时需重新调用 /token 获取新令牌。建议在应用层设置定时刷新（如每 25 天自动刷新）。

2reqId 有什么作用？

用于保证接口幂等性。同一个 reqId 的请求只会被执行一次，即使因网络重试导致多次调用也不会重复控制设备。建议使用 UUID 或业务订单号 + 时间戳生成。

3设备没有反应怎么办？

请确认：1）门店与三方的授权关系已建立；2）包间 ID 与设备已正确关联；3）设备在线且电源正常。如仍有问题请联系小界技术支持。

4支持哪些行业？

小界设备开放平台适用于 KTV、电竞酒店、棋牌室、密室逃脱、自习室、民宿、影咖等任何需要空间智能化管理的场景。

小界设备开放平台

© 2025 XiaoJie Technology

技术支持请联系小界商务人员15308021176获取对接群