创建工单

根据访客 uid、联系方式、标题、内容、创建坐席和目标受理人/组创建工单。userMobile 与 userEmail 至少传一个，targetStaffId 与 targetGroupId 至少传一个。priority 参数校验允许 1-10，实际创建仅支持 2/5/8/10，不支持的值会按普通优先级 5 处理；level 缺失或越界时默认 0；uniqueId 不传时按关键字段生成 MD5 用于弱网幂等。

请求参数

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

请求体

名称	类型	必填	描述	示例值
title	string	是	工单标题，长度 1-30；实际上限以企业当前配置为准	售后咨询：订单取消后未退款
uid	string	是	访客外部 ID，长度 1-64；实际上限以企业当前配置为准	user_3f9a2c8d
content	string	是	工单内容，长度 1-3000；实际上限以企业当前配置为准	用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。
userName	string	否	用户姓名，传入时长度 1-128；实际上限以企业当前配置为准	张三
userMobile	string	否	用户手机号，与 userEmail 至少传一个；传入时长度 1-128，实际上限以企业当前配置为准	13800138000
userEmail	string	否	用户邮箱，与 userMobile 至少传一个；传入时长度 1-255，实际上限以企业当前配置为准	zhangsan@example.com
staffId	int64	是	创建人坐席 ID，必须是当前企业正常状态坐席	10001
typeId	int64	否	工单分类 ID；不传或小于等于 0 时按 0 处理，传入正数时必须存在且启用	40001
targetStaffId	int64	否	目标受理坐席 ID，与 targetGroupId 至少传一个；传入时必须是当前企业正常状态坐席且有工单权限	10002
targetGroupId	int64	否	目标受理客服组 ID，与 targetStaffId 至少传一个；传入时必须是当前企业启用状态客服组	20001
level	int32	否	VIP 等级：0-11；缺失、为空或越界时默认 0（JSON 字段名 level）	2
priority	int32	否	优先级。参数校验允许 1-10；实际只支持 2-低、5-一般、8-紧急、10-非常紧急，不在支持集合内时默认 5	5
properties	string	否	附加属性 JSON 字符串，传入时长度 1-1024；实际上限以企业当前配置为准	{"orderId":"SO202407010001","channel":"wechat"}
attachments	object[]	否	附件列表，默认最多 5 个；实际上限以企业当前配置为准	[{"fileName":"退款凭证.pdf","type":2,"payload":"https://example.com/refund-proof.pdf"}]
└fileName	string	是	附件文件名，长度 1-128；实际上限以企业当前配置为准	退款凭证.pdf
└type	int32	是	附件类型：1-图片 Base64，2-URL	2
└payload	string	是	附件内容。type=1 时为 Base64；type=2 时为 URL，URL 长度 1-255，实际上限以企业当前配置为准	https://example.com/refund-proof.pdf
followerIds	int64[]	否	关注人坐席 ID 列表；支持 JSON 数组或 JSON 数组字符串	[10003,10004]
uniqueId	string	否	幂等 ID，默认最长 32 字符；不传时按本次创建请求的关键字段生成幂等标识	oa202407010001

返回参数

名称	类型	描述	示例值
code	int32	状态码，200 表示成功	200
message	string	新建或已存在的工单 ID 字符串	123456

错误码

状态码	描述
14001	AppKey 不存在
14002	checksum 校验失败
14003	time 缺失，或请求时间戳与服务器时间误差超过 10 分钟
14004	请求体不是合法 JSON；必填字段缺失；长度、priority、附件字段或附件类型校验失败
14100	staffId 或 targetStaffId 不是当前企业正常状态坐席
14101	typeId 为正数但对应工单分类不存在或未启用
14102	targetGroupId 对应客服组不存在、未启用、类型不是客服组或不属于当前企业
14103	附件数量超过限制，默认最多 5 个
14104	图片 Base64 附件总大小超过限制，默认 20MB
14107	企业附件总容量超过限制
14108	uniqueId 幂等校验发现重复创建，但无法返回已创建工单 ID
14109	uniqueId 长度超过限制，默认 32
14500	服务内部异常；用户创建或工单创建失败
16001	企业不存在或工单服务不可用
19254	targetStaffId 坐席没有工单权限

postEndpoint

/openapi/worksheet/create

curl -X POST "https://qiyukf.com/openapi/worksheet/create?appKey=9f1d7c2b8a6e4d3c&time=1739347200&checksum=a1b2c3d4e5f607182930abcdefabcdef&checksumAlgorithm=0" \  -H "Content-Type: application/json" \  -d '{    "title": "售后咨询：订单取消后未退款",    "uid": "user_3f9a2c8d",    "content": "用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。",    "staffId": 10001  }'

{
  "code": 200,
  "message": "123456"
}

{
  "code": 14001,
  "message": "AppKey 不存在"
}

{
  "code": 14002,
  "message": "checksum 校验失败"
}

{
  "code": 14003,
  "message": "time 缺失，或请求时间戳与服务器时间误差超过 10 分钟"
}

{
  "code": 14004,
  "message": "请求体不是合法 JSON；必填字段缺失；长度、priority、附件字段或附件类型校验失败"
}

{
  "code": 14100,
  "message": "staffId 或 targetStaffId 不是当前企业正常状态坐席"
}

{
  "code": 14101,
  "message": "typeId 为正数但对应工单分类不存在或未启用"
}

{
  "code": 14102,
  "message": "targetGroupId 对应客服组不存在、未启用、类型不是客服组或不属于当前企业"
}

{
  "code": 14103,
  "message": "附件数量超过限制，默认最多 5 个"
}

{
  "code": 14104,
  "message": "图片 Base64 附件总大小超过限制，默认 20MB"
}

{
  "code": 14107,
  "message": "企业附件总容量超过限制"
}

{
  "code": 14108,
  "message": "uniqueId 幂等校验发现重复创建，但无法返回已创建工单 ID"
}

{
  "code": 14109,
  "message": "uniqueId 长度超过限制，默认 32"
}

{
  "code": 14500,
  "message": "服务内部异常；用户创建或工单创建失败"
}

{
  "code": 16001,
  "message": "企业不存在或工单服务不可用"
}

{
  "code": 19254,
  "message": "targetStaffId 坐席没有工单权限"
}