简介

SmartBoard 开放接口提供完整的 RESTful 接口，用于与第三方系统进行集成。支持通讯录同步、会议管理、审批流程、信息发布、空间管理、智能通行、设备控制等核心能力。

接口地址http(s)://{server}/api/v1/open

快速开始

1. 获取 AppID 与 Secret

在管理后台「系统设置 > 组织信息 > API配置」获取凭证。

2. 生成签名

使用 HMAC-SHA256 对请求生成签名，设置 X-App-ID / X-Timestamp / X-Signature 请求头。

3. 发送请求

所有接口使用 JSON 格式交换数据，支持 GET / POST / PUT / DELETE 方法。

4. 处理响应

统一响应格式：code / message / data。分页接口返回 list + total + page + pageSize。

所有 API 请求必须通过 HTTPS 协议发送。AppSecret 必须严格保密，切勿暴露在客户端代码中。

认证机制

OpenAPI 使用 AppID/AppSecret 进行认证，通过 HMAC-SHA256 签名验证请求合法性。这与内部 API 的 JWT 认证方式不同。

请求头

X-App-ID:{AppID}

X-Timestamp:{UnixTimestamp}

X-Signature:{HMAC-SHA256 Signature}

Content-类型:application/json

签名算法

sign_string = HTTP_METHOD + "\n" + URI + "\n" + TIMESTAMP + "\n" + REQUEST_BODY
signature = HMAC-SHA256(sign_string, AppSecret).hex()

组成部分	说明
HTTP_METHOD	请求方法大写：GET、POST、PUT、DELETE
URI	完整请求路径含查询参数，如 /api/v1/open/users?page=1
TIMESTAMP	Unix 时间戳（秒），与服务器时间差不得超过 5 分钟
REQUEST_BODY	POST/PUT 请求的 JSON 字符串；GET/DELETE 为空字符串

认证流程

1

客户端使用 AppID + AppSecret 生成签名，设置请求头

2

服务端从 X-App-ID 查询对应 AppSecret

3

服务端用相同算法计算期望签名

4

比对签名 + 验证时间戳（5 分钟有效期）

AppSecret 仅在重新生成时显示一次。如怀疑泄露请立即重新生成，旧凭证即刻失效。认证失败错误码：MISSING_AUTH_HEADERS / INVALID_TIMESTAMP / REQUEST_EXPIRED / INVALID_APP_ID / INVALID_SIGNATURE

通讯录

管理组织架构中的部门和用户，支持增删改查和按部门查询用户。

部门管理

GET/departments获取部门列表

参数名	类型	必填	说明
includeMemberCount	boolean	选填	是否包含成员数量，默认 false

响应

200

GET/departments/{id}获取部门详情

参数名	类型	必填	说明
id	number	必填	部门 ID（路径参数）

响应

200

POST/departments创建部门

参数名	类型	必填	说明
name	string	必填	部门名称
parentId	number	选填	父部门 ID，不传或传 0 表示根部门
code	string	选填	部门编码，不传则自动生成
sort	number	选填	排序号，默认 0
description	string	选填	部门描述
phone	string	选填	部门电话
email	string	选填	部门邮箱

响应

200

PUT/departments/{id}更新部门

参数名	类型	必填	说明
id	number	必填	部门 ID（路径参数）
name	string	选填	部门名称
parentId	number	选填	父部门 ID
code	string	选填	部门编码
sort	number	选填	排序号
description	string	选填	部门描述
phone	string	选填	部门电话
email	string	选填	部门邮箱

响应

200

DELETE/departments/{id}删除部门

若部门下有子部门或成员，将返回错误。

参数名	类型	必填	说明
id	number	必填	部门 ID

响应

200

用户管理

GET/users获取用户列表

参数名	类型	必填	说明
page	number	选填	页码，默认 1
pageSize	number	选填	每页条数，默认 10
name	string	选填	用户姓名（模糊搜索）
departmentId	string	选填	部门 ID（支持多个，逗号分隔）

响应

200分页列表，含 loginName / name / employeeId / mobile / departmentName / roles 等

GET/users/{id}获取用户详情

参数名	类型	必填	说明
id	number	必填	用户 ID

响应

200

GET/users/departments/{id}按部门获取用户

参数名	类型	必填	说明
id	number	必填	部门 ID

响应

200

POST/users创建用户

参数名	类型	必填	说明
loginName	string	必填	登录名，必须唯一
name	string	必填	用户姓名
departmentId	number	必填	部门 ID
password	string	选填	密码，不传则默认 "123456"
employeeId	string	选填	员工工号
mobile	string	选填	手机号
email	string	选填	邮箱
isLeaderInDept	number	选填	是否部门负责人（0/1）
directLeader	number	选填	直属上级用户 ID
avatar	string	选填	头像 URL
gender	number	选填	性别（1 男，2 女）
roles	array	选填	角色 ID 数组

响应

200

PUT/users/{id}更新用户

参数名	类型	必填	说明
id	number	必填	用户 ID（路径参数）
name / departmentId / mobile / email / employeeId / status / roles ...	mixed	选填	所有字段均可选更新。status 可选值：on_work / leave

响应

200

DELETE/users/{id}删除用户

参数名	类型	必填	说明
id	number	必填	用户 ID

响应

200

会议中心

会议核心 CRUD 操作，支持创建、查询、更新和取消会议。

GET/meetings获取会议列表

参数名	类型	必填	说明
page	number	选填	页码，默认 1
pageSize	number	选填	每页条数，默认 10
roomId	number	选填	会议室 ID
userId	number	选填	用户 ID
status	string	选填	状态：pending / approved / rejected / canceled / completed
startDate	string	选填	开始日期 YYYY-MM-DD
endDate	string	选填	结束日期 YYYY-MM-DD
keyword	string	选填	关键词搜索（会议标题）

响应

200

GET/meetings/{id}获取会议详情

参数名	类型	必填	说明
id	number	必填	会议 ID

响应

200含 participants + checkInStats

POST/meetings创建会议

参数名	类型	必填	说明
title	string	必填	会议标题
roomId	number	必填	会议室 ID
startTime	string	必填	开始时间（ISO 8601）
endTime	string	必填	结束时间（ISO 8601）
description	string	选填	会议描述
participants	array	选填	参会人 ID 列表
notifyAttendees	boolean	选填	是否通知参会人，默认 true
requireApproval	boolean	选填	是否需要审批，默认 false

响应

200

POST/meetings/{id}更新会议

参数名	类型	必填	说明
id	number	必填	会议 ID
title / startTime / endTime / description / participants / notifyAttendees	mixed	选填	所有字段可选更新

响应

200

POST/meetings/{id}/cancel取消会议

参数名	类型	必填	说明
id	number	必填	会议 ID
reason	string	选填	取消原因

响应

200

审批中心

审批流程管理，包括查询审批列表、审批详情、处理审批和取消审批。

GET/approval获取审批列表

参数名	类型	必填	说明
page	number	选填	页码，默认 1
pageSize	number	选填	每页条数，默认 20
status	string	选填	状态：pending / approved / rejected / cancelled
type	string	选填	业务类型：meeting / leave / expense 等

响应

200

GET/approval/{id}获取审批详情

参数名	类型	必填	说明
id	number	必填	审批 ID

响应

200含 approvalSteps + businessData

GET/approval/my-approvals我的待审批

参数名	类型	必填	说明
page / pageSize / type	mixed	选填	分页和类型过滤

响应

200

GET/approval/my-applications我的申请

参数名	类型	必填	说明
page / pageSize / status / type	mixed	选填	分页和状态/类型过滤

响应

200

PUT/approval/{id}/process处理审批

参数名	类型	必填	说明
id	number	必填	审批 ID
action	string	必填	操作类型：approve / reject
comment	string	选填	审批意见（拒绝时必填）

响应

200

POST/approval/{id}/cancel取消审批

参数名	类型	必填	说明
id	number	必填	审批 ID

响应

200

信息发布

信息发布模块，包括节目管理和发布管理。节目定义内容，发布将节目推送到指定智能板。

节目管理

GET/etv/programs获取节目列表

参数名	类型	必填	说明
page / pageSize	number	选填	分页参数
status	string	选填	状态：draft / pending / approved / rejected / published / archived
keyword	string	选填	关键词搜索

响应

200

GET/etv/programs/{id}获取节目详情

参数名	类型	必填	说明
id	number	必填	节目 ID

响应

200含 content.components 内容编辑数据

发布管理

POST/etv/publish创建发布

参数名	类型	必填	说明
name	string	必填	发布名称
programId	number	必填	节目 ID
target	object	必填	发布目标配置
target.type	string	必填	目标类型：all / space / terminal
target.smartboardIds	array	选填	智能板 ID 列表（type=terminal 时必填）
target.spaceIds	array	选填	空间 ID 列表（type=space 时必填）
startTime	string	必填	开始时间（ISO 8601）
endTime	string	选填	结束时间
priority	number	选填	优先级（数字越大越高），默认 0
playMode	string	选填	播放模式：replace / append，默认 replace
startImmediately	boolean	选填	是否立即开始，默认 false

响应

200

GET/etv/publish获取发布列表

参数名	类型	必填	说明
page / pageSize / status	mixed	选填	分页参数，status：pending / publishing / success / failed / cancelled

响应

200

GET/etv/publish/{id}获取发布详情

参数名	类型	必填	说明
id	number	必填	发布 ID

响应

200含 tasks 子任务列表

POST/etv/publish/{id}/start开始发布

参数名	类型	必填	说明
id	number	必填	发布 ID

响应

200

POST/etv/publish/{id}/cancel取消发布

参数名	类型	必填	说明
id	number	必填	发布 ID

响应

200

空间管理

管理物理空间（会议室、工位等）和区域层级（城市/园区/楼栋/楼层/区域）。

空间管理

GET/space/spaces获取空间列表

参数名	类型	必填	说明
page / pageSize	number	选填	分页参数
keyword	string	选填	关键词搜索（空间名称、编码）
areaId	number	选填	区域 ID
status	string	选填	状态：active / inactive / maintenance / reserved
isBookable	boolean	选填	是否可预订
capabilityIds	array	选填	能力 ID 列表

响应

200

GET/space/spaces/tree获取空间树

按区域层级返回树形结构，包含每个区域下的空间设备数。

响应

200

POST/space/spaces创建空间

参数名	类型	必填	说明
name	string	必填	空间名称
capabilityIDs	array	必填	能力 ID 列表（至少一个）
spaceCode / areaId / areaSize / capacity / status / isBookable / description / tags / meetingRoom	mixed	选填	其他可选字段

响应

200

PUT/space/spaces/{id}更新空间

参数名	类型	必填	说明
id	number	必填	空间 ID
name / areaSize / capacity / status / isBookable / capabilityIDs / description / tags	mixed	选填	可更新字段

响应

200

DELETE/space/spaces/{id}删除空间

参数名	类型	必填	说明
id	number	必填	空间 ID

响应

200

区域管理

GET/space/areas获取区域列表

返回所有区域的扁平列表。

响应

200

GET/space/areas/tree获取区域树

按层级返回树形结构：城市 > 园区 > 楼栋 > 楼层 > 区域。

响应

200

POST/space/areas创建区域

参数名	类型	必填	说明
name	string	必填	区域名称
type	string	必填	类型：city / campus / building / floor / zone
parentId	number	选填	父区域 ID
code / status / sort / description	mixed	选填	编码、状态、排序、描述

响应

200

设备与通行

设备管理、远程控制和智能通行记录查询。

设备管理

GET/devices获取设备列表

参数名	类型	必填	说明
page / pageSize	number	选填	分页参数
type	string	选填	设备类型：smartboard / projector / sensor
spaceId	number	选填	空间 ID
status	string	选填	在线状态：online / offline
keyword	string	选填	关键词搜索（设备名称、IP）

响应

200

GET/devices/{id}获取设备详情

参数名	类型	必填	说明
id	number	必填	设备 ID

响应

200含 cpuUsage / memoryUsage / storage / networkStatus

POST/devices/{id}/control远程控制设备

参数名	类型	必填	说明
id	number	必填	设备 ID
action	string	必填	操作类型：restart / shutdown / wake / volume / brightness
params	object	选填	操作参数（音量值、亮度值等）

响应

200返回控制指令发送状态

智能通行

GET/smart-access/records获取通行记录

参数名	类型	必填	说明
page / pageSize	number	选填	分页参数
spaceId	number	选填	空间 ID
access类型	string	选填	通行方式：face / qr_code / password / card
status	string	选填	状态：success / failed
startDate / endDate	string	选填	日期范围 YYYY-MM-DD

响应

200

GET/smart-access/rooms/{spaceId}/detail获取门禁配置

参数名	类型	必填	说明
spaceId	number	必填	空间 ID

响应

200含 passwordEnabled / faceEnabled / qrCodeEnabled / whitelistCount

GET/smart-access/rooms/{spaceId}/whitelist获取房间白名单

参数名	类型	必填	说明
spaceId	number	必填	空间 ID

响应

200白名单用户列表含 validFrom / validTo

错误处理

统一错误响应格式和业务错误码。

响应格式

{
  "code": 400,
  "message": "错误描述",
  "data": null
}

HTTP 状态码

状态码	含义
200	成功
400	请求参数错误
401	未授权或 Token 无效
403	权限不足
404	资源不存在
500	服务器内部错误

业务错误码

错误码	含义
1001	用户名或密码错误
1002	账户已禁用
2001	会议不存在
2002	会议已被预订
3001	用户不存在
3002	部门不存在
4001	审批不存在
4002	审批状态错误
5001	节目不存在
5002	发布失败