创建工单

请求参数

名称	类型	必填	描述
subject	string	是	工单标题
descript	string	否	工单描述
custUserId	int	否	联系人id，说明该工单是为该客户解决问题
custUser	object	否	联系人信息
createrId	int	否	工单创建人id
createrType	int	否	工单创建人类型，0-客服 1-客户，不传此参数默认为0
servicerUserId	int	否	受理客服id
servicerGroupId	int	否	受理客服组id
ccUserIdList	string	否	抄送客服id列表
ccGroupIdList	string	否	抄送客服组id列表
ticketSource	int	否	工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建，7–API，8–工单模板发布，9–邮件接入
ticketType	int	否	工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel	int	否	工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus	int	否	工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
ticketTemplateId	int	是	工单模板id，创建工单需指明当前工单使用哪个工单模板
tagList	int	否	工单标签列表，以逗号分隔
lockKey	string	否	帮我吧中添加幂等锁的字段的唯一标识
lockValue	string	否	需要锁判断的字段的具体值，该值将被放入缓存，在5s内该参数值重复将不会重复创建工单。
custom_fields	array	否	工单自定义字段(可自定义类型：下拉列表，单行文本，多行文本，正整数，小数，复选框，高级复选框，日期，验证码，表单，附件，级联，地址位置)
tables	array	否	工单自定义表单数据（仅支持普通表单和评价表单，不支持资产表）
isAppraise	int	否	评价表单中的是否评价，1-已评价 0-未评价

请求地址

POST /api/v1/tickets.json

custUser参数说明

目前支持的联系人信息有mobilephone、name、fixnumber、qq、email、companyid，如果要使用该参数，则mobilephone是必需的，其余是选填项。如果数据库里没有该联系人信息，则会自动创建。当传companyid时，是为了绑定这个公司和这个手机号为当前工单的客户信息，要确认该companyid的公司下已经绑定该手机号，如果未绑定：

companyid存在于此服务商，创建工单失败提示：The phone number is not correct

companyId存在于其他服务商创建工单失败提示：The phone number is not correct

companyid错误id，不存在的或者不是数字创建工单失败提示：The phone number is not correct
当不传companyid时，则默认绑定该手机号绑定的第一家公司为当前工单的客户信息

"custUser":{ 
        "mobilephone": 13240138438,
        "name": "张三" ,
        "fixnumber": "010-63701717" ,
        "qq": "601100987" ,
        "email": "bangwo8@126.com" ,
        "companyid":"2349"
}

自定义字段说明

key是字段的唯一标识，可从"帮我吧后台"查看自定义字段的唯一标识；value是该字段的具体值。

"custom_fields":[
     {
      "key": "field_1",
      "value": "文本框内容"
     },
     {
      "key": "field_2",
      "value": "下拉框的某选项"
     }
    ]

上传工单附件

工单附件包含两种类型：自定义字段类型的附件和工单回复里的附件。上传附件有两种方式:
说明：传的附件会将原有的附件全量覆盖，请谨慎使用

方式一：直接将附件地址上传

（该地址需要是https协议地址），附件名称fileName一定要有后缀，后缀与附件的格式是一样的。

"custom_fields":[{
              "key": "zhuandanfujian",//附件自定义字段唯一标识
                  "value":[
                  {
                      "fileName":"file1.org", //命名需要有后缀才能在工单中正确显示
                      "fileUrl":"https://huixing.org" 
                  }, 
                  {
                      "fileName":"file2.org",
                      "fileUrl":"https://huixing.org" 
                  }
                  ]
          }]

方式二：先调用工单附件里的上传附件接口

调用成功后，系统会返回相应的附件token，然后将返回的token配置到value对应值即可。

/*自定义字段附件*/
"custom_fields": [
    {
            "key": "field_4", //附件自定义字段的唯一标识
            "value": "15761b339251466e9fec23698503eb53,
            12343b339251466e9fec23698503eb54" //上传附件接口返回的token
        }
]
/*工单回复里的附件*/
"ticketReply": {
        "attachments": [
           "15761b339251466e9fec23698503eb53", //附件1的token
           "12343b339251466e9fec23698503eb54" //附件2的token
        ]
}

创建带普通表单类型的工单

表单类型的字段与普通自定义字段传值方式不一样，不在"custom_fields"进行传值，而是在"tables"里传值，"tables"与"custom_fields"是并列关系，在创建表单数据时返回数据中会有一个curId，最好把每行数据curId存储，以便后期在调用更新工单的表单数据时根据curId进行更新表单数据。

"tables":[
        {
            "custom_fields_key":"",//工单表单字段的唯一标识
            "tableData":[
                {//第一行数据
                    "cpdm":"001.005",
                    "cpmc":"铺助面板",
                    "zjm":"PZMB",
                    "ggxh":"A6020青古"
                },
                {//第二行数据
                    "cpdm":"001.005",
                    "cpmc":"铺助面板",
                    "zjm":"PZMB",
                    "ggxh":"A6020青古"
                }
            ]
        }
    ]

创建带评价表单的工单

{
    "ticket":{
        "subject":"工单名字",
        "ticketTemplateId":"8",
        "custom_fields":[
            "field_30"："是"
        ],
        "tables":[
            {
                "custom_fields_key":"field_25",
                "tableData":[
                    {
                        "fwtd":"5",
                        "isAppraise":"1",    //该参数值为1时是"已评价"状态
                        "fwzl":"5",
                        "qlxc":"5",
                        "field_2":"评价",
                        "jsxx":"5",
                        "key":"field_3",
                        "value":[
                            {
                                "fileName":"1640312200299.jpg",
                                "fileUrl":"https://shenbin-xiaojin.f.wmeimob.com/upload/20211224/1640312200299.jpg"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

级联字段传值方式

级联字段可以通过选项内容传值也可以通过外部扩展id传值

选项内容传值：

{
    "ticket": {
        "subject": "API推送级联",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "question",
                "value": "1"
            },
            {
                "key": "field_4",
                "value": [
                    "北京市",
                    "海淀区",
                    "中关村"
                ]
            }
        ]
    }
}

通过外部扩展id传值：

{
    "ticket": {
        "subject": "API推送级联",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "question",
                "value": "1"
            },
            {
                "key": "field_4",
                "value": [
                    "1",
                    "11",
                    "111"
                ],
                "valtype": "extetnal_id"
            }
        ]
    }
}

复选框字段

普通复选框：0为置空，1为选中

{
    "ticket": {
        "subject": "API推送复选框",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "field_29",
                "value": "1"
            }
        ]
    }
}

高级复选框：两种方式，传选项id，或者传外部扩展id

{
    "ticket": {
        "subject": "API推送级联",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "field_4",
                "value": "356786,367528"
            },
            {
                "key": "field_5",
                "value":"01,02,03",
                "valtype": "extetnal_id"
            }
        ]
    }
}

调用示例

返回参数

名称	类型	必填	描述
ticketId	int	是	工单id，系统自动生成
subject	string	是	工单标题
ticketReply	object	是	工单描述
custUserId	int	否	联系人id，说明该工单是为该客户解决问题
custUser	object	否	联系人信息
servicerUserId	int	否	受理客服id
servicerGroupId	int	否	受理客服组id
ccUserIdList	string	否	抄送客服id列表
ccGroupIdList	string	否	抄送客服组id列表
ticketSource	int	否	工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建，7–API，8–工单模板发布，9–邮件接入
ticketType	int	否	工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel	int	否	工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus	int	否	工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
ticketTemplateId	int	是	工单模板id，创建工单需指明当前工单使用哪个工单模板
createrId	int	否	创建人id
tagList	int	否	工单标签列表，以逗号分隔
lockValue	string	否	帮我吧中添加幂等锁字段的唯一标识
lockValue	string	否	需要锁判断的字段的具体值，该值将被放入缓存，在5s内该参数值重复将不会重复创建工单。
custom_fields	array	否	工单自定义字段（包含自定义表单）

返回值示例

Status: 200 OK
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json

{
    "ticket": {
        "ticketId": "13309903",
        "custUserId": "32161762",
        "subject": "测试",
        "descript": "",
        "servicerUserId": "952726",
        "ccUserIdList": "",
        "ticketType": "0",
        "priorityLevel": "0",
        "tagList": "",
        "ticketStatus": "1",
        "createDT": "2020-12-23 13:14:15",
        "updateDT": "2020-12-23 13:14:15",
        "solveDT": "",
        "waitDT": "",
        "openDT": "",
        "closeDT": "",
        "servicerGroupId": "0",
        "createrId": "952726",
        "agentId": "587413",
        "ticketSource": "7",
        "ticketTemplateId": "4",
        "ccGroupIdList": "",
        "customTemplateId": "0",
        "createrType": "0",
        "currentNodeField": "",
        "currentNodeFieldValue": "",
        "nodeFieldIntoTime": "0",
        "queryIDs": "",
        "workflow_node_id": "",
        "workflow_id": "0",
        "custom_fields": [
            {
                "key": "field_1",
                "value": "问题详情"
            },
            {
                "key": "field_3",
                "value": "3296950"
            },
            {
                "key": "field_5",
                "value": "3298234"
            },
            {
                "key": "field_8",
                "value": "解决方案"
            },
            {
                "key": "field_9",
                "value": "3415675"
            },
            {
                "key": "field_19",
                "value": ""
            },
            {
                "key": "field_20",
                "value": ""
            },
            {
                "key": "field_112",
                "value": "4185970"
            },
            {
                "key": "carbon_copy",
                "value": "293345@qq.com"
            }
        ]
    }
}

添加幂等锁后触发锁机制返回参数

{
    "code": "40000",
    "message": "请2秒后再试",
    "data": {
        "lockKey": "field_167",
        "lockValue": "123123",
        "expAt": "1687760000"  //幂等锁解锁时间戳
    }
}

在 Header 添加参数

Authorization

，其值为在 Basic 之后拼接空格，以及经过 Base64 编码的 username:password

示例：

Authorization: Basic *****************

application/json

Body

示例

{
    "ticket": {
        "ticketId": "13309903",
        "custUserId": "32161762",
        "subject": "测试",
        "descript": "",
        "servicerUserId": "952726",
        "ccUserIdList": "",
        "ticketType": "0",
        "priorityLevel": "0",
        "tagList": "",
        "ticketStatus": "1",
        "createDT": "2020-12-23 13:14:15",
        "updateDT": "2020-12-23 13:14:15",
        "solveDT": "",
        "waitDT": "",
        "openDT": "",
        "closeDT": "",
        "servicerGroupId": "0",
        "createrId": "952726",
        "agentId": "587413",
        "ticketSource": "7",
        "ticketTemplateId": "4",
        "ccGroupIdList": "",
        "customTemplateId": "0",
        "createrType": "0",
        "currentNodeField": "",
        "currentNodeFieldValue": "",
        "nodeFieldIntoTime": "0",
        "queryIDs": "",
        "workflow_node_id": "",
        "workflow_id": "0",
        "custom_fields": [
            {
                "key": "field_1",
                "value": "问题详情"
            },
            {
                "key": "field_3",
                "value": "3296950"
            },
            {
                "key": "field_5",
                "value": "3298234"
            },
            {
                "key": "field_8",
                "value": "解决方案"
            },
            {
                "key": "field_9",
                "value": "3415675"
            },
            {
                "key": "field_19",
                "value": ""
            },
            {
                "key": "field_20",
                "value": ""
            },
            {
                "key": "field_112",
                "value": "4185970"
            },
            {
                "key": "carbon_copy",
                "value": "293345@qq.com"
            }
        ]
    }
}

创建工单

创建工单

请求参数

请求地址

custUser参数说明

自定义字段说明

上传工单附件

方式一：直接将附件地址上传

方式二：先调用工单附件里的上传附件接口

创建带普通表单类型的工单

创建带评价表单的工单

级联字段传值方式

选项内容传值：

通过外部扩展id传值：

复选框字段

普通复选框：0为置空，1为选中

高级复选框：两种方式，传选项id，或者传外部扩展id

调用示例

返回参数

返回值示例

添加幂等锁后触发锁机制返回参数

请求参数

请求示例代码

返回响应

创建工单

创建工单#

请求参数#

请求地址#

custUser参数说明#

自定义字段说明#

上传工单附件#

方式一：直接将附件地址上传#

方式二：先调用工单附件里的上传附件接口#

创建带普通表单类型的工单#

创建带评价表单的工单#

级联字段传值方式#

选项内容传值：#

通过外部扩展id传值：#

复选框字段#

普通复选框：0为置空，1为选中#

高级复选框：两种方式，传选项id，或者传外部扩展id#

调用示例#

返回参数#

返回值示例#

添加幂等锁后触发锁机制返回参数#

请求参数

请求示例代码

返回响应

创建工单

请求参数

请求地址

custUser参数说明

自定义字段说明

上传工单附件

方式一：直接将附件地址上传

方式二：先调用工单附件里的上传附件接口

创建带普通表单类型的工单

创建带评价表单的工单

级联字段传值方式

选项内容传值：

通过外部扩展id传值：

复选框字段

普通复选框：0为置空，1为选中

高级复选框：两种方式，传选项id，或者传外部扩展id

调用示例

返回参数

返回值示例

添加幂等锁后触发锁机制返回参数