七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入
工单系统

搜索工单列表（管理员视角）

管理员视角按多维度条件全量搜索工单。创建时间默认取近 30 天，最大跨度 90 天；opTime/updateTime 同样限制 90 天；offset 最大 50000，超出直接报错。statusList 优先于 status 生效；withCustomField=true 时为每张工单单独查询自定义字段值，查询量大时注意性能。withMailReplyList=true 时批量查询邮件回复记录并挂载到各工单 mailReplyList 字段。

请求参数

名称类型必填描述示例值
appKeystring是应用 AppKey
timeint64是请求时间戳（秒）
checksumstring是请求签名校验和
checksumAlgorithmint32否签名算法：0 - 默认(SHA1)，1 - SHA256

请求体

名称类型必填描述示例值
ticketIdint64否工单 ID 精确匹配123456
mobilestring否用户手机号13800138000
templateIdint64否工单模板 ID30001
limitint32否每页数量，最大 500，默认 500500
offsetint64否偏移量，最大 50000，默认 00
statusint32否单一状态过滤：0-未知，1-已提交，5-未受理，10-受理中，20-完结，25-已驳回，50-已挂起，999-已删除10
statusListstring否多状态过滤，逗号分隔，取值同 status；传入时优先于 status 生效5,10,20
sortBystring否排序字段，默认 ctct
orderstring否排序方向：asc / desc，默认 descdesc
startint64否创建时间起始（毫秒时间戳），默认近 30 天，最大跨度 90 天1719763200000
endint64否创建时间结束（毫秒时间戳）1722441599000
opStartint64否操作时间起始（毫秒时间戳），最大跨度 90 天1719849600000
opEndint64否操作时间结束（毫秒时间戳）1722441599000
updateStartint64否更新时间起始（毫秒时间戳），最大跨度 90 天1719849600000
updateEndint64否更新时间结束（毫秒时间戳）1722441599000
uidstring否访客外部 ID（uid）user_3f9a2c8d
queryCrmInfostring否是否查询 CRM 信息true
typeint32否CRM 类型1
solveStatusint32否评价解决状态1
withMailReplyListboolean否是否返回邮件回复列表true
withCustomFieldboolean否是否返回自定义字段true
customFieldsobject[]否工单自定义字段过滤条件。推荐传 JSON 数组；兼容传入包含同一数组的 JSON 字符串。字段标识兼容 id 别名，多个条件按 AND 组合[{"fieldId":81001,"value":"SO202407010001"}]
└fieldIdint64否工单自定义字段定义 ID；兼容使用 id 别名81001
└valuestring否搜索值，必须以字符串传递；接口不会移除首尾空格SO202407010001

返回参数

名称类型描述示例值
codeint32状态码，200 表示成功200
messageobject工单分页数据{"total":2,"tickets":[{"id":123456,"staffId":10001,"holderId":10002,"lastFinishProcessor":10002,"templateId":30001,"typeId":40001,"priority":8,"groupId":20001,"title":"售后咨询：订单取消后未退款","content":"用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。","status":10,"createTime":1720085400000}]}
└totalint64工单总数2
└ticketsobject[]工单列表[{"id":123456,"staffId":10001,"holderId":10002,"lastFinishProcessor":10002,"templateId":30001,"typeId":40001,"priority":8,"groupId":20001,"title":"售后咨询：订单取消后未退款","content":"用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。","status":10,"createTime":1720085400000}]
└idint64工单ID123456
└staffIdint64发起人（坐席）ID10001
└holderIdint64受理人（坐席）ID10002
└lastFinishProcessorint64最后完结人ID10002
└templateIdint64工单模板ID30001
└typeIdint64工单分类ID40001
└priorityint32优先级：2-低，5-一般，8-紧急，10-非常紧急8
└groupIdint64受理组ID20001
└titlestring工单标题售后咨询：订单取消后未退款
└contentstring工单内容用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。
└statusint32工单状态：0-未知，1-已提交，5-未受理，10-受理中，20-完结，25-已驳回，50-已挂起，999-已删除10
└createTimeint64工单创建时间（毫秒时间戳）1720085400000
└userNamestring用户姓名张三
└userEmailstring用户邮箱zhangsan@example.com
└userMobilestring用户手机号13800138000
└propertiesstring工单附加属性（JSON 字符串）{"orderId":"SO202407010001","channel":"wechat"}
└typeStrstring分类名称路径字符串（请求返回分类路径时返回）售后服务/退款问题
└modifyLastboolean最后一次操作是否为修改false
└attachmentsobject[]创建工单时的附件列表[{"name":"退款凭证.pdf","size":245760,"url":"https://nos.example.com/ticket/refund-proof.pdf"}]
└namestring附件文件名退款凭证.pdf
└sizeint64附件大小（字节）245760
└urlstring附件下载地址https://nos.example.com/ticket/refund-proof.pdf
└commentsobject[]工单流转评论列表[{"staffId":10001,"comment":"已联系财务核实退款状态，请耐心等待。","timestamp":1720087200000,"attachments":[]}]
└staffIdint64操作坐席ID10001
└commentstring回复/备注内容已联系财务核实退款状态，请耐心等待。
└timestampint64操作时间（毫秒时间戳）1720087200000
└attachmentsobject[]随此次操作上传的附件列表[{"name":"退款凭证.pdf","size":245760,"url":"https://nos.example.com/ticket/refund-proof.pdf"}]
└namestring附件文件名退款凭证.pdf
└sizeint64附件大小（字节）245760
└urlstring附件下载地址https://nos.example.com/ticket/refund-proof.pdf
└customobject[]自定义字段值列表[{"id":91001,"name":"订单号","value":"SO202407010001","fieldId":81001}]
└idint64自定义字段记录ID91001
└namestring自定义字段名称订单号
└valueobject自定义字段值SO202407010001
└fieldIdint64自定义字段定义 ID81001
└followerstring关注人ID列表（JSON 字符串）[10003,10004]
└crmUserNamestringCRM 用户姓名张三
└crmUserEmailstringCRM 用户邮箱zhangsan@example.com
└crmUserPhonestringCRM 用户手机号13800138000
└crmIdstringCRM 用户IDcrm_78901
└userIdint64访客用户ID556677
└crmForeignIdstringCRM 外部ID（foreignId）crm_ext_001
└connectionTypeint32关联会话连接类型1
└connectionIdint64关联会话连接ID987654321
└holderPlatformIdint64受理方平台ID1
└mailReplyListobject[]邮件回复列表（withMailReplyList=true 时返回）[{"ticketId":123456,"id":88001,"sender":{"nickname":"七鱼售后","address":"support@example.com"},"toMailList":[{"nickname":"张三","address":"zhangsan@example.com"}],"ccMailList":[{"nickname":"财务","address":"finance@example.com"}],"subject":"Re: 订单退款咨询","sendTime":1720089000000,"monitorStatus":1,"replyStatus":2,"mailDir":2,"lastOperatorId":10002,"replyStaffId":10002,"lastUpdateTime":1720089300000}]
└ticketIdint64关联工单ID123456
└idint64邮件记录ID88001
└senderobject邮箱昵称与地址[{"nickname":"财务","address":"finance@example.com"}]
└nicknamestring邮箱昵称七鱼售后
└addressstring邮箱地址support@example.com
└toMailListobject[]收件人列表[{"nickname":"张三","address":"zhangsan@example.com"}]
└nicknamestring邮箱昵称七鱼售后
└addressstring邮箱地址support@example.com
└ccMailListobject[]抄送人列表[{"nickname":"财务","address":"finance@example.com"}]
└nicknamestring邮箱昵称七鱼售后
└addressstring邮箱地址support@example.com
└subjectstring邮件主题Re: 订单退款咨询
└sendTimeint64发送时间（毫秒时间戳）1720089000000
└monitorStatusint32监测状态1
└replyStatusint32回复状态2
└mailDirint32邮件方向：1-接收，2-发送2
└lastOperatorIdint64最后操作坐席ID（目前为修改监测状态的坐席）10002
└replyStaffIdint64回复坐席ID10002
└lastUpdateTimeint64最后修改时间（毫秒时间戳，目前为最后修改监测状态的时间）1720089300000
└pluginUrlstring工单插件 URLhttps://openapi.qiyukf.com/plugin/ticket/123456
└groupNamestring受理组名称售后组
└holderNamestring受理人名称李四
└commentstring最新回复内容已联系财务核实退款状态，请耐心等待。
└commentStaffNamestring最新回复坐席姓名李四
└modifyTimeint64工单最后更新时间（毫秒时间戳）1720089000000
└firstDispatchTimeint64首次分配时间（毫秒时间戳）1720086000000

错误码

状态码描述
14004时间范围超过 90 天；offset 超过 50000；请求体 JSON 格式错误
14500服务内部异常
postEndpoint
/openapi/v2/ticket/search
POST
/openapi/v2/ticket/search
curl -X POST "https://qiyukf.com/openapi/v2/ticket/search?appKey=string&time=0&checksum=string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "code": 200,
  "message": {
    "total": 2,
    "tickets": [
      {
        "id": 123456,
        "staffId": 10001,
        "holderId": 10002,
        "lastFinishProcessor": 10002,
        "templateId": 30001,
        "typeId": 40001,
        "priority": 8,
        "groupId": 20001,
        "title": "售后咨询：订单取消后未退款",
        "content": "用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。",
        "status": 10,
        "createTime": 1720085400000
      }
    ]
  }
}
{
  "code": 14004,
  "message": "时间范围超过 90 天；offset 超过 50000；请求体 JSON 格式错误"
}
{
  "code": 14500,
  "message": "服务内部异常"
}

这篇文档有帮助吗？

创建工单

代访客创建工单，支持普通工单（OpenAPI 来源）和邮件工单（fromType=4）。 **参数与工单类型** - uid 与 userMobile 二选一。 - 普通工单的 staffId 必填：-1 代表访客自助提交，正数代表发起坐席，且该坐席必须有效并属于本企业。 - 邮件工单的 uid 和 userEmail 必填，不使用 staffId 和受理目标规则。 **受理目标规则** 1. 未使用自动流转模板时，优先使用接口传入的 targetStaffId、targetGroupId，未传的字段可由模板预设补充。 2. 若最终没有有效受理目标，staffId 为正数时会自动成为受理人，staffId=-1 时则创建失败。 3. 未指定模板（templateId=0）时，staffId=-1 必须传 targetStaffId、targetGroupId 中的至少一个；staffId 为真实坐席时两者可不传，默认由 staffId 受理。 4. 使用自动流转模板时，接口传入的 targetStaffId、targetGroupId 仍会先进行有效性校验，但在实际分配时会被模板流程覆盖。 5. 部分企业若将非自动流转模板的受理组和受理人同时配置为必填，则两者最终都必须有值；同时指定受理组和受理人时，受理人必须属于该组。 **幂等与附件** - uniqueId 最长 32 字符，重复提交时返回已创建的工单 ID。 - 附件最多 5 个、总大小不超过 50 MB；type=1 为 Base64 图片上传后生成 URL，type=2 为 URL 直接使用。

搜索已删除工单

搜索已逻辑删除的工单，适用于数据同步场景。删除时间（dbUpdateTime）默认取近 30 天，最大跨度 90 天，超出直接报错。limit 最大 500；withMailReplyList=true 时批量查询邮件回复记录并挂载到各工单 mailReplyList 字段。