REST API 参考文档
润吧云平台完整的REST API接口文档，包含认证、核心业务、数据分析等所有模块
更新于 2024-01-25
润吧云API团队
阅读时间 30分钟
API文档
REST API
接口参考
开发指南
API概述
润吧云REST API采用标准的HTTP协议，支持JSON格式的数据交换。 所有API接口都需要通过认证才能访问，确保数据安全。
基础信息
Base URL:
https://api.runbayun.com/v1协议: HTTPS
格式: JSON
认证方式
类型: Bearer Token
有效期: 24小时
刷新: 自动续期
限流规则
频率: 1000次/小时
并发: 10个/秒
重试: 指数退避
认证
获取访问令牌
使用企业账号和密码获取API访问令牌，令牌有效期为24小时。
POST /auth/token
curl -X POST https://api.runbayun.com/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"username": "your-username",
"password": "your-password",
"grant_type": "password"
}'响应示例
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"scope": "read write"
}使用令牌
在所有API请求的Header中包含Authorization字段：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
核心API
用户管理
用户信息的增删改查操作
GET
/users获取企业内所有用户的基本信息，支持分页和筛选。
查询参数
page - 页码（默认1）limit - 每页数量（默认20）department - 部门筛选status - 状态筛选（active/inactive）POST
/users创建新的用户账号，需要提供基本信息和角色权限。
请求体
{
"username": "zhangsan",
"name": "张三",
"email": "zhangsan@company.com",
"phone": "13800138000",
"department_id": 1,
"role": "operator"
}双重预防
风险管控和隐患排查相关接口
GET
/risks获取企业风险分级管控清单，包含风险等级、管控措施等信息。
查询参数
level - 风险等级（重大/较大/一般/低）area - 风险区域status - 管控状态POST
/hazards上报发现的安全隐患，系统将自动分配处理责任人。
请求体
{
"title": "设备漏油隐患",
"description": "生产车间A区压缩机存在漏油现象",
"level": "一般",
"location": "生产车间A区",
"reporter_id": 123,
"images": ["image1.jpg", "image2.jpg"]
}人员定位
实时人员位置和轨迹查询
GET
/locations/realtime获取所有在线人员的实时位置信息，支持区域筛选。
响应示例
{
"data": [
{
"user_id": 123,
"name": "张三",
"position": {
"x": 100.5,
"y": 200.3,
"floor": 1
},
"area": "生产车间A区",
"timestamp": "2024-01-25T10:30:00Z"
}
]
}错误处理
API使用标准的HTTP状态码来表示请求结果，错误响应包含详细的错误信息。
HTTP状态码
200请求成功201创建成功400请求参数错误401认证失败403权限不足404资源不存在500服务器错误错误响应格式
{
"error": {
"code": "INVALID_PARAMETER",
"message": "参数验证失败",
"details": [
{
"field": "username",
"message": "用户名不能为空"
}
]
}
}SDK和工具
为了简化开发过程，我们提供了多种编程语言的SDK和开发工具。
官方SDK
JavaScript/Node.js
Python
Java
PHP
开发工具
Postman Collection
OpenAPI 3.0
API调试工具
代码生成器