工单

管理接口 /api/tickets 的用户工单契约——创建、列表、详情、回复与附件上传。

工单接口属于管理接口：鉴权方式为登录会话（或用户 access token）+ Jimu-Api-User 请求头， 不接受 sk- API 令牌本身，详见 鉴权与令牌。 错误响应为管理接口形态（success/message），业务失败返回 HTTP 200，见 错误处理与请求追踪。

枚举

分类

值含义
1账号
2计费
3接口问题
4技术
5其他

优先级

值含义
1低
2中
3高
4紧急

状态

值含义
1待处理
2处理中
3已解决
4已关闭

端点总览

方法路径说明
GET/api/tickets/当前用户工单列表（分页）
POST/api/tickets/创建工单
GET/api/tickets/{id}工单详情与消息
POST/api/tickets/{id}/reply追加回复
POST/api/tickets/{id}/upload上传附件
路径末尾的斜杠是 Gin 路由注册的规范形式；不带斜杠访问会收到 301 重定向到带斜杠的路径。

端点契约

获取工单列表

GET/api/tickets/
pint

页码，从 1 开始

page_sizeint

每页条数，默认 10

响应200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1001,
      "category": 3,
      "priority": 2,
      "status": 1,
      "subject": "API 调用报 500",
      "description": "调用 /v1/chat/completions 时偶发 500",
      "attachments": "",
      "created_at": 1756400000,
      "updated_at": 1756400000,
      "first_response_at": 0,
      "resolved_at": 0
    }
  ],
  "total": 1
}

创建工单

POST/api/tickets/
subjectstring必填

工单标题，不能为空

descriptionstring

详细描述

categoryint

分类，缺省或传 0 时置为 5（其他）

priorityint

优先级，缺省或传 0 时置为 2（中）

curl https://api.jimu.chat/api/tickets/ \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Jimu-Api-User: <USER_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "API 调用报 500",
    "description": "调用 /v1/chat/completions 时偶发 500",
    "category": 3,
    "priority": 2
  }'
响应200
{
  "success": true,
  "message": "工单创建成功",
  "data": {
    "id": 1,
    "user_id": 1001,
    "category": 3,
    "priority": 2,
    "status": 1,
    "subject": "API 调用报 500",
    "description": "调用 /v1/chat/completions 时偶发 500",
    "attachments": "",
    "created_at": 1756400000,
    "updated_at": 1756400000,
    "first_response_at": 0,
    "resolved_at": 0
  }
}

工单详情

GET/api/tickets/{id}

响应 data 包含 ticket 与 messages：

响应200
{
  "success": true,
  "data": {
    "ticket": {
      "id": 1,
      "user_id": 1001,
      "category": 3,
      "priority": 2,
      "status": 1,
      "subject": "API 调用报 500",
      "description": "调用 /v1/chat/completions 时偶发 500",
      "attachments": "",
      "created_at": 1756400000,
      "updated_at": 1756400000,
      "first_response_at": 1756400500,
      "resolved_at": 0
    },
    "messages": [
      {
        "id": 1,
        "ticket_id": 1,
        "is_admin": true,
        "content": "已收到您的反馈，我们正在排查。",
        "created_at": 1756400500
      }
    ]
  }
}

非本人工单返回 success: false、message: "无权访问此工单"；工单不存在返回 message: "工单不存在"。

追加回复

POST/api/tickets/{id}/reply
contentstring必填

回复内容，不能为空

curl https://api.jimu.chat/api/tickets/1/reply \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Jimu-Api-User: <USER_ID>" \
  -H "Content-Type: application/json" \
  -d '{"content": "补充一下，500 只在高峰时段出现"}'

工单状态为 4（已关闭）时不可回复，返回 message: "工单已关闭，无法回复"。

上传附件

POST/api/tickets/{id}/upload

Content-Type: multipart/form-data，字段名 file。

  • 上限 20 MB
  • 允许扩展名：.jpg .jpeg .png .gif .webp .pdf .txt .log .zip
  • 已关闭工单不可上传
curl https://api.jimu.chat/api/tickets/1/upload \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Jimu-Api-User: <USER_ID>" \
  -F "file=@screenshot.png"
响应200
{
  "success": true,
  "message": "附件上传成功",
  "data": {
    "url": "/uploads/1756400000123456789_abc12345.png",
    "filename": "screenshot.png",
    "size": 245760
  }
}

工单对象

idint

工单 ID

user_idint

所属用户 ID

categoryint

分类（枚举见上文）

priorityint

优先级（枚举见上文）

statusint

状态（枚举见上文）

subjectstring

标题

descriptionstring

详细描述

attachmentsstring

附件 URL 列表（逗号分隔）

created_atint

创建时间（Unix 秒）

updated_atint

更新时间（Unix 秒）

first_response_atint

首次回复时间（Unix 秒），0 表示暂无回复

resolved_atint

解决时间（Unix 秒），0 表示未解决

消息对象

字段类型说明
idint消息 ID
ticket_idint所属工单 ID
is_adminbool是否管理员回复
contentstring消息内容
created_atint创建时间（Unix 秒）

令牌管理

管理接口 /api/token 的令牌 CRUD 契约，以及用 Bearer 令牌自助查询额度与模型限制的 /api/usage/token。