通过过滤器查询工单列表（坐席视角）

按坐席已配置的过滤器分页查询工单列表。filterId 必须是该企业下有效的过滤器，staffId 对应坐席必须处于正常状态，否则直接返回错误。limit 超出上限 50 时自动截断为 50；typeStr=true 时会批量查询分类信息并填充 typeStr 字段。

请求参数

名称	类型	必填	描述
appKey	string	是	应用 AppKey
time	int64	是	请求时间戳（秒）
checksum	string	是	请求签名校验和
checksumAlgorithm	int32	否	签名算法：0 - 默认(SHA1)，1 - SHA256

请求体

名称	类型	必填	描述	示例值
filterId	int64	是	过滤器 ID	70001
staffId	int64	是	操作坐席 ID	10001
limit	int32	否	每页数量，最大 50，默认 20	20
offset	int64	否	偏移量，默认 0	0
sortBy	string	否	排序字段，默认 ct（创建时间）	ct
order	string	否	排序方向：asc / desc，默认 desc	desc
typeStr	boolean	否	是否返回分类名称路径字符串，默认 false	true

返回参数

名称	类型	描述	示例值
code	int32	状态码，200 表示成功	200
message	object	工单分页数据	{"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}]}
└total	int64	工单总数	2
└tickets	object[]	工单列表	[{"id":123456,"staffId":10001,"holderId":10002,"lastFinishProcessor":10002,"templateId":30001,"typeId":40001,"priority":8,"groupId":20001,"title":"售后咨询：订单取消后未退款","content":"用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。","status":10,"createTime":1720085400000}]
└id	int64	工单ID	123456
└staffId	int64	发起人（坐席）ID	10001
└holderId	int64	受理人（坐席）ID	10002
└lastFinishProcessor	int64	最后完结人ID	10002
└templateId	int64	工单模板ID	30001
└typeId	int64	工单分类ID	40001
└priority	int32	优先级：2-低，5-一般，8-紧急，10-非常紧急	8
└groupId	int64	受理组ID	20001
└title	string	工单标题	售后咨询：订单取消后未退款
└content	string	工单内容	用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。
└status	int32	工单状态：0-未知，1-已提交，5-未受理，10-受理中，20-完结，25-已驳回，50-已挂起，999-已删除	10
└createTime	int64	工单创建时间（毫秒时间戳）	1720085400000
└userName	string	用户姓名	张三
└userEmail	string	用户邮箱	zhangsan@example.com
└userMobile	string	用户手机号	13800138000
└properties	string	工单附加属性（JSON 字符串）	{"orderId":"SO202407010001","channel":"wechat"}
└typeStr	string	分类名称路径字符串（请求返回分类路径时返回）	售后服务/退款问题
└modifyLast	boolean	最后一次操作是否为修改	false
└attachments	object[]	创建工单时的附件列表	[{"name":"退款凭证.pdf","size":245760,"url":"https://nos.example.com/ticket/refund-proof.pdf"}]
└name	string	附件文件名	退款凭证.pdf
└size	int64	附件大小（字节）	245760
└url	string	附件下载地址	https://nos.example.com/ticket/refund-proof.pdf
└comments	object[]	工单流转评论列表	[{"staffId":10001,"comment":"已联系财务核实退款状态，请耐心等待。","timestamp":1720087200000,"attachments":[]}]
└staffId	int64	操作坐席ID	10001
└comment	string	回复/备注内容	已联系财务核实退款状态，请耐心等待。
└timestamp	int64	操作时间（毫秒时间戳）	1720087200000
└attachments	object[]	随此次操作上传的附件列表	[{"name":"退款凭证.pdf","size":245760,"url":"https://nos.example.com/ticket/refund-proof.pdf"}]
└name	string	附件文件名	退款凭证.pdf
└size	int64	附件大小（字节）	245760
└url	string	附件下载地址	https://nos.example.com/ticket/refund-proof.pdf
└custom	object[]	自定义字段值列表	[{"id":91001,"name":"订单号","value":"SO202407010001","fieldId":81001}]
└id	int64	自定义字段记录ID	91001
└name	string	自定义字段名称	订单号
└value	object	自定义字段值	SO202407010001
└fieldId	int64	自定义字段定义 ID	81001
└follower	string	关注人ID列表（JSON 字符串）	[10003,10004]
└crmUserName	string	CRM 用户姓名	张三
└crmUserEmail	string	CRM 用户邮箱	zhangsan@example.com
└crmUserPhone	string	CRM 用户手机号	13800138000
└crmId	string	CRM 用户ID	crm_78901
└userId	int64	访客用户ID	556677
└crmForeignId	string	CRM 外部ID（foreignId）	crm_ext_001
└connectionType	int32	关联会话连接类型	1
└connectionId	int64	关联会话连接ID	987654321
└holderPlatformId	int64	受理方平台ID	1
└mailReplyList	object[]	邮件回复列表（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}]
└ticketId	int64	关联工单ID	123456
└id	int64	邮件记录ID	88001
└sender	object	邮箱昵称与地址	[{"nickname":"财务","address":"finance@example.com"}]
└nickname	string	邮箱昵称	七鱼售后
└address	string	邮箱地址	support@example.com
└toMailList	object[]	收件人列表	[{"nickname":"张三","address":"zhangsan@example.com"}]
└nickname	string	邮箱昵称	七鱼售后
└address	string	邮箱地址	support@example.com
└ccMailList	object[]	抄送人列表	[{"nickname":"财务","address":"finance@example.com"}]
└nickname	string	邮箱昵称	七鱼售后
└address	string	邮箱地址	support@example.com
└subject	string	邮件主题	Re: 订单退款咨询
└sendTime	int64	发送时间（毫秒时间戳）	1720089000000
└monitorStatus	int32	监测状态	1
└replyStatus	int32	回复状态	2
└mailDir	int32	邮件方向：1-接收，2-发送	2
└lastOperatorId	int64	最后操作坐席ID（目前为修改监测状态的坐席）	10002
└replyStaffId	int64	回复坐席ID	10002
└lastUpdateTime	int64	最后修改时间（毫秒时间戳，目前为最后修改监测状态的时间）	1720089300000
└pluginUrl	string	工单插件 URL	https://openapi.qiyukf.com/plugin/ticket/123456
└groupName	string	受理组名称	售后组
└holderName	string	受理人名称	李四
└comment	string	最新回复内容	已联系财务核实退款状态，请耐心等待。
└commentStaffName	string	最新回复坐席姓名	李四
└modifyTime	int64	工单最后更新时间（毫秒时间戳）	1720089000000
└firstDispatchTime	int64	首次分配时间（毫秒时间戳）	1720086000000

错误码

状态码	描述
14004	filterId 或 staffId 为空；请求体 JSON 格式错误
14100	staffId 对应坐席不存在或已停用
14500	服务内部异常

postEndpoint

/openapi/v2/ticket/list

curl -X POST "https://qiyukf.com/openapi/v2/ticket/list?appKey=string&time=0&checksum=string" \  -H "Content-Type: application/json" \  -d '{    "filterId": 70001,    "staffId": 10001  }'

{
  "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": "filterId 或 staffId 为空；请求体 JSON 格式错误"
}

{
  "code": 14100,
  "message": "staffId 对应坐席不存在或已停用"
}

{
  "code": 14500,
  "message": "服务内部异常"
}