超全LoonFlow工单系统API实战指南：从认证到高级操作
项目地址: https://gitcode.com/gh_mirrors/lo/loonflow 一、API调用前的准备工作
你是否还在为工单系统对接效率低而烦恼？是否因API文档不清晰而反复调试？本文将系统讲解LoonFlow工单系统的API使用方法，涵盖认证机制、核心接口调用、错误处理等关键知识点，帮助你快速实现系统集成。读完本文你将掌握：
- 3种API认证方式的实现代码
- 12个核心工单接口的调用技巧
- 5类常见错误的排查方法
- 2个企业级集成案例的完整流程
1.1 环境准备
# 克隆仓库
git clone https://gitcode.com/gh_mirrors/lo/loonflow
cd loonflow
# 安装依赖
pip install -r requirements/common.txt
1.2 认证机制详解
LoonFlow采用基于Token的API认证机制，在调用任何接口前需完成签名生成。签名算法如下：
import time
import hashlib
def generate_signature(token):
timestamp = str(int(time.time()))[:10]
ori_str = timestamp + token
signature = hashlib.md5(ori_str.encode(encoding='utf-8')).hexdigest()
return {
"signature": signature,
"timestamp": timestamp,
"appname": "your_app_name",
"username": "your_username"
}
获取Token流程：
- 登录LoonFlow管理后台
- 进入"账户-调用token"页面
- 点击"新增"，填写应用名称
- 保存后获取系统生成的Token
二、核心API接口详解
2.1 工单管理接口
2.1.1 获取工单列表
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| category | varchar | 是 | 工单类型(all/owner/duty/relation/worked) |
| workflow_ids | varchar | 否 | 工作流IDs，逗号分隔 |
| state_ids | varchar | 否 | 状态IDs，逗号分隔 |
| page | int | 否 | 页码，默认1 |
| per_page | int | 否 | 每页条数，默认10 |
请求示例：
import requests
headers = generate_signature("your_token") # 使用1.2节的签名函数
params = {
"category": "duty",
"per_page": 20,
"workflow_ids": "1,2"
}
response = requests.get("http://your_domain/api/v1.0/tickets",
headers=headers, params=params)
print(response.json())
返回结果：
{
"msg": "",
"code": 0,
"data": {
"value": [{
"id": 17,
"sn": "loonflow_201805150001",
"title": "网络访问申请",
"state": {
"state_name": "发起人-确认中",
"state_id": 10
},
"workflow": {
"workflow_name": "网络访问申请",
"workflow_id": 2
}
}],
"total": 1,
"page": 1,
"per_page": 10
}
}
2.1.2 新建工单
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | workflow_id | int | 是 | 工作流ID | | transition_id | int | 是 | 流转ID | | title | varchar | 是 | 工单标题 | | parent_ticket_id | int | 否 | 父工单ID |
请求示例：
data = {
"workflow_id": 2,
"transition_id": 1,
"title": "测试API创建工单",
"leave_days": 3,
"leave_type": 1
}
response = requests.post("http://your_domain/api/v1.0/tickets",
headers=headers, json=data)
2.2 工作流管理接口
2.2.1 获取工作流列表
response = requests.get("http://your_domain/api/v1.0/workflows", headers=headers)
返回结果：
{
"code": 0,
"data": {
"total": 2,
"value": [
{"name": "请假申请", "id": 1},
{"name": "网络访问申请", "id": 2}
]
}
}
2.2.2 获取工作流初始状态
workflow_id = 1
response = requests.get(f"http://your_domain/api/v1.0/workflows/{workflow_id}/init_state",
headers=headers)
三、高级操作指南
3.1 工单处理完整流程
3.2 加签操作实现
# 加签操作
ticket_id = 1
data = {
"target_username": "lisi",
"suggestion": "请协助审核"
}
response = requests.post(f"http://your_domain/api/v1.0/tickets/{ticket_id}/add_node",
headers=headers, json=data)
# 完成加签
data = {"suggestion": "已审核通过"}
response = requests.post(f"http://your_domain/api/v1.0/tickets/{ticket_id}/add_node_end",
headers=headers, json=data)
四、错误处理与最佳实践
4.1 常见响应码说明
| 响应码 | 含义 | 处理建议 |
|---|---|---|
| 0 | 成功 | 正常处理返回数据 |
| -1 | 参数错误 | 检查请求参数格式 |
| -2 | 权限不足 | 确认Token有效性 |
| -3 | 资源不存在 | 验证ID是否正确 |
4.2 性能优化建议
- 批量操作优先：使用批量接口减少请求次数
- 合理缓存：缓存工作流结构等静态数据
- 异步处理：非关键操作采用异步调用
五、企业级集成案例
5.1 内部OA系统集成
# OA系统调用LoonFlow创建请假工单
def create_leave_ticket(employee_id, days, leave_type):
# 1. 获取员工信息
user = get_employee_info(employee_id)
# 2. 生成签名
headers = generate_signature(OA_APP_TOKEN)
# 3. 创建工单
data = {
"workflow_id": LEAVE_WORKFLOW_ID,
"transition_id": 1,
"title": f"{user['name']}请假申请",
"leave_days": days,
"leave_type": leave_type,
"creator": user["username"]
}
response = requests.post(LOONFLOW_API_URL + "/tickets",
headers=headers, json=data)
return response.json()
5.2 运维自动化集成
通过API实现故障自动报修流程，当监控系统发现异常时：
- 自动调用LoonFlow API创建工单
- 工单处理完成后回调监控系统
- 自动关闭告警
六、总结与展望
本文详细介绍了LoonFlow工单系统API的认证机制、核心接口调用方法和高级操作技巧，通过实际代码示例和流程图展示了完整的集成流程。掌握这些知识后，你可以快速实现与各种业务系统的对接，提升工单处理效率。
未来LoonFlow API将支持更多高级功能，包括WebHook机制、自定义表单等，敬请期待。如有任何问题，欢迎在项目仓库提交Issue交流反馈。
收藏本文，随时查阅API调用细节，关注项目更新获取最新功能预告！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
