创建工单

代访客创建工单，支持普通工单（OpenAPI 来源）和邮件工单（fromType=4）。

参数与工单类型

uid 与 userMobile 二选一。
普通工单的 staffId 必填：-1 代表访客自助提交，正数代表发起坐席，且该坐席必须有效并属于本企业。
邮件工单的 uid 和 userEmail 必填，不使用 staffId 和受理目标规则。

受理目标规则

未使用自动流转模板时，优先使用接口传入的 targetStaffId、targetGroupId，未传的字段可由模板预设补充。
若最终没有有效受理目标，staffId 为正数时会自动成为受理人，staffId=-1 时则创建失败。
未指定模板（templateId=0）时，staffId=-1 必须传 targetStaffId、targetGroupId 中的至少一个；staffId 为真实坐席时两者可不传，默认由 staffId 受理。
使用自动流转模板时，接口传入的 targetStaffId、targetGroupId 仍会先进行有效性校验，但在实际分配时会被模板流程覆盖。
部分企业若将非自动流转模板的受理组和受理人同时配置为必填，则两者最终都必须有值；同时指定受理组和受理人时，受理人必须属于该组。

幂等与附件

uniqueId 最长 32 字符，重复提交时返回已创建的工单 ID。
附件最多 5 个、总大小不超过 50 MB；type=1 为 Base64 图片上传后生成 URL，type=2 为 URL 直接使用。

请求参数

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

请求体

名称	类型	必填	描述	示例值
uid	string	否	访客外部 ID，与 userMobile 二选一	user_3f9a2c8d
userMobile	string	否	用户手机号，与 uid 二选一（邮件工单必须使用 uid）	13800138000
staffId	int64	否	发起坐席 ID。普通工单必填：-1 代表访客自助提交；正数必须是当前企业有效坐席，且在非自动流转、未解析出其他受理目标时会默认成为受理人。邮件工单无需传	10001
templateId	int64	否	工单模板 ID。不传或传 0 时使用默认模板；非自动流转模板可补充未传的受理目标；自动流转模板下，接口传入的受理目标会先校验有效性，再由模板流程覆盖	30001
title	string	否	工单标题	售后咨询：订单取消后未退款
content	string	否	工单内容	用户反馈订单取消后 3 个工作日仍未收到退款，请协助核实。
userName	string	否	访客姓名	张三
priority	int32	否	优先级：2-低，5-一般，8-紧急，10-非常紧急	8
typeId	int64	否	工单分类 ID	40001
targetStaffId	int64	否	指定受理坐席 ID。未使用自动流转模板时优先采用；传入时必须是当前企业正常状态且有工单权限的坐席。staffId=-1 且模板未提供受理目标时，与 targetGroupId 至少传一个；使用自动流转模板时，本字段仍会先校验有效性，再由模板流程覆盖	10002
targetGroupId	int64	否	指定受理客服组 ID。未使用自动流转模板时优先采用；传入时必须是当前企业有效客服组。staffId=-1 且模板未提供受理目标时，与 targetStaffId 至少传一个；使用自动流转模板时，本字段仍会先校验有效性，再由模板流程覆盖	20001
userEmail	string	否	发件人邮箱（邮件工单）	zhangsan@example.com
toEmail	string	否	收件人邮箱（邮件工单）	support@example.com
uniqueId	string	否	幂等 ID，最长 32 字符，用于防止重复提单	oa202407010001
fromType	int32	否	来源类型，默认为 OpenAPI	2
properties	string	否	附加属性（JSON 字符串）	{"orderId":"SO202407010001","channel":"wechat"}
customFields	string	否	自定义字段列表，JSON 字符串，每项：{id 或 fieldId, name, value}	[{"fieldId":81001,"name":"订单号","value":"SO202407010001"}]
attachments	object[]	否	附件列表，JSON 数组，每项：{type, payload, fileName}	[{"type":2,"payload":"openapi/attachments/2024/07/refund-proof.pdf","fileName":"退款凭证.pdf"}]
└type	int32	否	附件类型：1-图片，2-文件，3-音频，4-视频	2
└payload	string	否	附件内容（Base64 编码或文件对象名）	openapi/attachments/2024/07/refund-proof.pdf
└fileName	string	否	附件文件名	退款凭证.pdf
level	int32	否	VIP 等级：0-11，默认 0（JSON 字段名：level）	2
connectionId	int64	否	关联会话连接 ID	987654321
followerIds	string	否	关注人坐席 ID 列表，JSON 数组字符串（JSON 字段名：followerIds）	[10003,10004]
crmId	string	否	CRM 用户 ID	crm_78901
crmForeignId	string	否	CRM 外部 ID	crm_ext_001

返回参数

名称	类型	描述	示例值
code	int32	状态码，200 表示成功	200
message	string	新建工单 ID（字符串格式）	123456

错误码

状态码	描述
8002	uid 和 userMobile 均为空
8803	crmId 与 crmForeignId 不匹配
14004	普通工单 staffId 为空；非自动流转且 staffId=-1 时未解析出有效受理目标；uniqueId 超过 32 字符；附件数量/大小超限；JSON 格式错误
14100	staffId/targetStaffId 不存在或已停用
14101	typeId 无效或不存在
14102	targetGroupId 无效
14103	附件数量超限
14104	单个附件超限
14107	附件总大小超限
14108	uniqueId 重复，返回已有工单 ID
14109	uniqueId 超长
14500	服务内部异常
16001	企业工单服务不可用
19254	坐席无工单权限

postEndpoint

/openapi/v2/ticket/create

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

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

{
  "code": 8002,
  "message": "uid 和 userMobile 均为空"
}

{
  "code": 8803,
  "message": "crmId 与 crmForeignId 不匹配"
}

{
  "code": 14004,
  "message": "普通工单 staffId 为空；非自动流转且 staffId=-1 时未解析出有效受理目标；uniqueId 超过 32 字符；附件数量/大小超限；JSON 格式错误"
}

{
  "code": 14100,
  "message": "staffId/targetStaffId 不存在或已停用"
}

{
  "code": 14101,
  "message": "typeId 无效或不存在"
}

{
  "code": 14102,
  "message": "targetGroupId 无效"
}

{
  "code": 14103,
  "message": "附件数量超限"
}

{
  "code": 14104,
  "message": "单个附件超限"
}

{
  "code": 14107,
  "message": "附件总大小超限"
}

{
  "code": 14108,
  "message": "uniqueId 重复，返回已有工单 ID"
}

{
  "code": 14109,
  "message": "uniqueId 超长"
}

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

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

{
  "code": 19254,
  "message": "坐席无工单权限"
}