版本 2.4.7.20261116085428 · 最新
工单 tickets
管理端处理用户工单:列表、详情、回复、内部备注、关闭与重开。
点击任一接口,右侧显示对应的调用示例。
工单鉴权: 仅管理员8 个接口
鉴权
请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。
X-API-Key
鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。
约定
分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。
时间一律 RFC 3339(UTC);金额单位为分。
写操作成功回 200/201/204;重复提交按资源唯一键回 409。
GET
/api/v2/tickets列出工单
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
status | string | 标签页:open 待处理(用户端为处理中)、replied 待用户确认(用户端为待您确认)、closed 已关闭;不传 = 全部。 |
tenant_id | integer | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
q | string | 搜索:纯数字按编号精确,否则按标题子串。 |
urgent | boolean | 只看紧急(true)或只看一般(false)。 |
category | string | 按分类过滤:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他;逗号分隔可多选。 |
site_id | integer | 按关联网站或转发规则的 id 过滤。 |
created_from | string | 提交时间起(含)。 |
created_to | string | 提交时间止(不含)。 |
POST
/api/v2/tickets代用户提交工单
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
body必填 | string | 正文,最长 2000 字符。 |
category必填 | string | 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。 |
image_ids | integer[] | 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。 |
notify | boolean | 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。 |
rel_id | integer | 关联对象 id,0 = 无。 |
tenant_id必填 | integer | 提交用户(租户)id。 |
title必填 | string | 标题,最长 60 字符。 |
urgent | boolean | 是否紧急。 |
GET
/api/v2/tickets/{id}工单详情
鉴权: 仅管理员
PATCH
/api/v2/tickets/{id}改工单紧急程度或分类
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
category | string | 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。 |
urgent | boolean | 是否紧急。 |
POST
/api/v2/tickets/{id}/close关闭工单
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
note | string | 选填:作为最后一条客服回复,最长 2000 字符。 |
notify | boolean | 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。 |
POST
/api/v2/tickets/{id}/notes加内部备注
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
body必填 | string | 正文,最长 2000 字符。 |
POST
/api/v2/tickets/{id}/reopen重开工单
鉴权: 仅管理员
POST
/api/v2/tickets/{id}/replies客服回复
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
action | string | wait_user 回复并置等待用户确认、close 回复并关闭、none 只回复;缺省 wait_user。 |
body | string | 正文,最长 2000 字符。 |
image_ids | integer[] | 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。 |
工单对象
| 字段 | 类型 | 说明 |
|---|---|---|
action | string | wait_user 回复并置等待用户确认、close 回复并关闭、none 只回复;缺省 wait_user。 |
author_avatar_ver | integer | 作者头像版本,每次上传变大;没有头像或不给 author_id 时缺省。 |
author_id | integer | 作者的用户 id,供取头像用。管理端的 user / staff / note 消息都有;用户端只在用户自己的消息上带(客服与系统记录不给,不暴露管理员信息)。 |
author_name | string | 作者名。管理端:用户名或管理员名;用户端:客服与系统记录一律「客服」。 |
auto_close_at | string | 自动关闭的到期时间:仅「待用户确认」且开了自动关闭时有值(答复时间 + 设置天数,改设置后按新值);否则为空。列表药丸「N 天后自动关闭」据此算。 |
body必填 | string | 正文,最长 2000 字符。 |
can_rate | boolean | 仅用户端:已关闭或待确认、没评价过且评价开关开着(待确认单据此决定「已解决」弹框出不出评价区)。 |
can_reopen | boolean | 仅用户端:已关闭且还在重开期限内。 |
category | string | 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。 |
close_reason | string | 关闭原因:user 用户、staff 客服、timeout 超时自动关闭;未关闭为空。 |
closed_at | string | 关闭时间;未关闭为空。 |
created_at | string | 创建时间 |
created_by_admin | boolean | 是否管理员代用户提交;仅管理端有值。 |
event | string | 系统记录的事件:urgent 改紧急、category 改分类、closed 关闭、reopened 重开、timeout 超时关闭、reply 回复引起状态变化(from/to 为旧/新状态)、submitted 用户提交、submitted_for 管理员代用户提交(to 为用户名);其他消息为空。 |
from | string | 系统记录的原值。 |
id | integer | 工单编号。 |
image_ids | integer[] | 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。 |
images | TicketImage[] | 附图。 |
kind | string | user 用户、staff 客服、note 内部备注(只管理端)、system 系统记录。 |
last_at | string | 最后一次有消息或状态变化的时间。 |
last_kind | string | 最后一条消息的发送方:user 用户、staff 客服,空 = 没有消息。用户端列表据此给客服消息加「客服:」前缀。 |
last_snippet | string | 最后一条客服/用户消息的摘要(去换行折空白,最长 80 字符,超出以省略号结尾);内部备注与系统行不算;没有消息为空。 |
messages | TicketMessage[] | 消息串,按 id 升序;用户端没有 note。 |
msg_count | integer | 客服/用户消息条数(含提交时的首条描述,不含内部备注与系统行)。 |
new_count | integer | read_pos 之后对方新发的条数。 |
note | string | 选填:作为最后一条客服回复,最长 2000 字符。 |
notify | boolean | 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。 |
rating | string | 评价:good 满意、normal 一般、bad 不满意,空 = 未评。 |
rating_enabled | boolean | 仅用户端:工单设置里的评价开关(关着时已解决弹框不显示评价区)。 |
rating_note | string | 评价附言。 |
read_pos | integer | 本端打开前的已读位置(消息 id);新消息分隔线画在它之后。 |
rel_id | integer | 关联对象 id,0 = 无。 |
rel_name | string | 关联对象名称(提交时的快照)。 |
rel_type | string | 关联对象类型:site 网站、stream 转发规则,空 = 无。 |
reopen_until | string | 仅用户端:已关闭时,可重开的截止时间。 |
status | string | open 待客服处理、replied 等用户确认、closed 已关闭。 |
tenant_id | integer | 提交用户(租户)id。 |
title | string | 标题,最长 60 字符。 |
to | string | 系统记录的新值。 |
unread | integer | 对方新发、本端还没读的消息条数。 |
urgent | boolean | 是否紧急。 |
user | object | 提交用户信息;仅管理端有。 |
user_name | string | 提交用户名;只管理端有值。 |
返回与错误
成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。
成功
{
"id": 1,
"name": "example"
}列表
{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}失败
{
"code": "validation_failed",
"detail": "请求参数不合法",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name 必填"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}