版本 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列出工单

鉴权: 仅管理员

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
statusstring 标签页:open 待处理(用户端为处理中)、replied 待用户确认(用户端为待您确认)、closed 已关闭;不传 = 全部。
可选值 ["open","replied","closed"]
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
qstring 搜索:纯数字按编号精确,否则按标题子串。
urgentboolean 只看紧急(true)或只看一般(false)。
categorystring 按分类过滤:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他;逗号分隔可多选。
site_idinteger 按关联网站或转发规则的 id 过滤。
created_fromstring 提交时间起(含)。
created_tostring 提交时间止(不含)。
POST/api/v2/tickets代用户提交工单

鉴权: 仅管理员

请求体 application/json

字段类型说明
body必填string 正文,最长 2000 字符。
category必填string 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。
可选值 ["site","cert","security","l4","billing","other"]
image_idsinteger[] 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。
notifyboolean 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。
rel_idinteger 关联对象 id,0 = 无。
tenant_id必填integer 提交用户(租户)id。
title必填string 标题,最长 60 字符。
urgentboolean 是否紧急。
PATCH/api/v2/tickets/{id}改工单紧急程度或分类

鉴权: 仅管理员

请求体 application/json

字段类型说明
categorystring 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。
可选值 ["site","cert","security","l4","billing","other"]
urgentboolean 是否紧急。
POST/api/v2/tickets/{id}/close关闭工单

鉴权: 仅管理员

请求体 application/json

字段类型说明
notestring 选填:作为最后一条客服回复,最长 2000 字符。
notifyboolean 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 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

字段类型说明
actionstring wait_user 回复并置等待用户确认、close 回复并关闭、none 只回复;缺省 wait_user。
可选值 ["wait_user","close","none"]
bodystring 正文,最长 2000 字符。
image_idsinteger[] 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。

工单对象

字段类型说明
actionstring wait_user 回复并置等待用户确认、close 回复并关闭、none 只回复;缺省 wait_user。
可选值 ["wait_user","close","none"]
author_avatar_verinteger 作者头像版本,每次上传变大;没有头像或不给 author_id 时缺省。
author_idinteger 作者的用户 id,供取头像用。管理端的 user / staff / note 消息都有;用户端只在用户自己的消息上带(客服与系统记录不给,不暴露管理员信息)。
author_namestring 作者名。管理端:用户名或管理员名;用户端:客服与系统记录一律「客服」。
auto_close_atstring 自动关闭的到期时间:仅「待用户确认」且开了自动关闭时有值(答复时间 + 设置天数,改设置后按新值);否则为空。列表药丸「N 天后自动关闭」据此算。
body必填string 正文,最长 2000 字符。
can_rateboolean 仅用户端:已关闭或待确认、没评价过且评价开关开着(待确认单据此决定「已解决」弹框出不出评价区)。
can_reopenboolean 仅用户端:已关闭且还在重开期限内。
categorystring 分类:site 网站、cert 证书、security 安全防护、l4 四层转发、billing 套餐与账单、other 其他。
可选值 ["site","cert","security","l4","billing","other"]
close_reasonstring 关闭原因:user 用户、staff 客服、timeout 超时自动关闭;未关闭为空。
可选值 ["","user","staff","timeout"]
closed_atstring 关闭时间;未关闭为空。
created_atstring 创建时间
created_by_adminboolean 是否管理员代用户提交;仅管理端有值。
eventstring 系统记录的事件:urgent 改紧急、category 改分类、closed 关闭、reopened 重开、timeout 超时关闭、reply 回复引起状态变化(from/to 为旧/新状态)、submitted 用户提交、submitted_for 管理员代用户提交(to 为用户名);其他消息为空。
可选值 ["","urgent","category","closed","reopened","timeout","reply","submitted","submitted_for"]
fromstring 系统记录的原值。
idinteger 工单编号。
image_idsinteger[] 先经 POST /ticket-images 上传的图片 id,至多 5 个,须是本人上传且还没被用过的。
imagesTicketImage[] 附图。
kindstring user 用户、staff 客服、note 内部备注(只管理端)、system 系统记录。
可选值 ["user","staff","note","system"]
last_atstring 最后一次有消息或状态变化的时间。
last_kindstring 最后一条消息的发送方:user 用户、staff 客服,空 = 没有消息。用户端列表据此给客服消息加「客服:」前缀。
可选值 ["","user","staff"]
last_snippetstring 最后一条客服/用户消息的摘要(去换行折空白,最长 80 字符,超出以省略号结尾);内部备注与系统行不算;没有消息为空。
messagesTicketMessage[] 消息串,按 id 升序;用户端没有 note。
msg_countinteger 客服/用户消息条数(含提交时的首条描述,不含内部备注与系统行)。
new_countinteger read_pos 之后对方新发的条数。
notestring 选填:作为最后一条客服回复,最长 2000 字符。
notifyboolean 是否通知用户(站内消息 + 按提醒设置的订阅);缺省 true,false 则只建单不通知。
ratingstring 评价:good 满意、normal 一般、bad 不满意,空 = 未评。
可选值 ["","good","normal","bad"]
rating_enabledboolean 仅用户端:工单设置里的评价开关(关着时已解决弹框不显示评价区)。
rating_notestring 评价附言。
read_posinteger 本端打开前的已读位置(消息 id);新消息分隔线画在它之后。
rel_idinteger 关联对象 id,0 = 无。
rel_namestring 关联对象名称(提交时的快照)。
rel_typestring 关联对象类型:site 网站、stream 转发规则,空 = 无。
可选值 ["","site","stream"]
reopen_untilstring 仅用户端:已关闭时,可重开的截止时间。
statusstring open 待客服处理、replied 等用户确认、closed 已关闭。
可选值 ["open","replied","closed"]
tenant_idinteger 提交用户(租户)id。
titlestring 标题,最长 60 字符。
tostring 系统记录的新值。
unreadinteger 对方新发、本端还没读的消息条数。
urgentboolean 是否紧急。
userobject 提交用户信息;仅管理端有。
user_namestring 提交用户名;只管理端有值。

返回与错误

成功直接回资源 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"
}
开始使用

123

123