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調試工具
代碼生成器