工单接口对接

本接口对接内容由四个部分组成,工单的流出流入,工单备注的流出流入,其中工单流出指的是将七陌系统把坐席对工单的处理信息推送给第三方系统,需要第三方系统提供接口。工单流入指的是第三方系统可以通过调用七陌提供的接口在七陌系统内创建工单,工单备注的流出流入同理。



1.流出工单对接

接口详解:第三方系统提供一个公网可以访问的地址,7moor系统会把工单数据以json的形式推送到提供的接口中,推送是在工单流转中触发,流转到工单的某一步骤时,如果当前步骤配置了工单流出接口,才会推送当前步骤数据。数据推送请求为post、格式为一个json对象,其中每一个json对象对应一个步骤动作信息。

配置工单流出接口:

请求体【以下表格中字段为必填项】

字段 类型 备注
_id String 工单ID
customerId String 客户ID
fields Object类型数组 当前步骤动作界面字段信息(name:字段名称 type:字段类型value:字段值)
user String 处理坐席的工号
createTime String 工单创建时间
flowInfo String 当前步骤的的步骤信息
stepFields String 当前步骤界面可操作字段信息
action String 执行的动作名称
stepName String 当前步骤的名称
businessNumber String 工单编号
processEndTime String 工单结束时间
creatTimestamp String 创建时间毫秒数

json示例:

{
    "_id":"xxxxxxx",
    "customerId":"d6e1b200-5c4e-11e8-a355-ef17e9d190d7",
    "fields":[
        {"name":"日期","type":"date","value":"2020-09-06"},
        {"name":"单选框","type":"radio","value":"北京市"},
        {"name":"下拉框","type":"dropdown","value": ["北京市","天津市"]},
        {"name":"附件","type":"file","value":[{
            "name":"24a643a0-edad-11e6-85cc-9f6ba46d3479(1) (1).jpg",
            "value":"https://fs-test.7moor.com/N00000000103/business/2020-09-30/1506753687899/62d132b0-a5aa-11e7-a7c1-ef308e254ecc"}]
        },
        {"name":"复选框","type":"checkbox","value":
            ["checkbox1","checkbox2","checkbox3"]
        },
        {"name":"来源","type":"single","value":"abc"}
    ],
    "user":"工号",
    "createTime":"yyyy-mm-dd HH:mm:ss",
    "action":"动作名称",
    "creatTimestamp":"1505716040000",
    "setpName":"当前步骤名称",
    "processEndTime":"2020-07-31 17:34:21",
    "businessNumber":"工单编号",
    "flowInfo":"日期:2017-09-06",
    "stepFields":[{"name":"日期","type":"date","value":"2020-09-06"}]
}

返回值:

字段 含义
200 同步成功
400 同步失败




2.流入(暂存)工单对接

接口详解: 通过接口在系统中创建工单、流转工单。工单流入的数据结构是根据系统中配置的每个工单模板的变化而来,可以在系统中查看工单流入的数据格式。

注意:

1、工单暂存接口和目前系统的工单流入(新建工单)走的是同一个接口
传的参数同工单流入的接口(_id不传),多加一个参数 actionType = "temp",表示工单暂存的流入。

2、工单暂存与工单流入的区别:工单暂存是将创建工单的数据提交到客服系统保存,不做流转,该坐席可以在客服系统上查看并编辑;工单流入是提交创建工单数据并进入流转,所属坐席可以查看工单,但是不能继续修改。

3、工单ID或工单编号同时为空时是创建工单,当工单ID和工单编号同时存在时以“工单ID”为准执行动作,当工单ID和工单编号单独存在时以“工单号”或“工单ID”执行动作。

  • 接口请求方式:POST

  • 接口参数格式:json

  • 请求链接:{HOST}/v20170704/business/handleBusiness/{ACCOUNTID}?sig={SIG}

  • 请求时请将{HOST}换成[对接数据

  • ](../data-query.md)中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

请求url:

-请求示例:

https://apis.7moor.com/v20170704/business/handleBusiness/N00000000556?sig=41276A8E7767352A0FE7456D20F03D3

请求体:

字段 类型 备注
_id String 工单ID
number String 工单编号
uniqueId String 用户区别是否是同一请求,24小时内同一个账户不允许传递相同的uniqueId,相同时返回错误,返回值`{message:"uniqueId exists",code:400})`
customerId String 客户ID,如果为空则表示未知客户
fields Object类型数组 工单字段(name:字段名称, type:字段类型,value:字段值)
注:字段类型是file,字段值里面的value字段可以换成url传附件的地址,换成url了前面的name字段的值后缀要和链接的后缀保持一致,比如说链接是.js的后缀,那文件名要是xxx.js
targetUser String 工号或auto(指派给谁处理)
createUser String 工号(创建工单的坐席或者工单流转过程中当前坐席)
flowName String 系统配置的工单模版名称
comment String 备注
stepName String 工单步骤名称
action String 动作名称
priority String 工单优先级,创建工单时可传1,2,3表示普通,紧急,很紧急

请求体示例:

{ 
    "_id":"工单id",
    "customerId":"客户id",  
    "fields":[
        {"name":"单选框","type":"radio","value":"abc"},
        {"name":"附件","type":"file","value": [
                {"name":"123.jpg","value":"文件的base64码"},
                {"name":"jquery.js","url":"https://code.jquery.com/jquery-migrate-3.1.0.min.js"}
            ]
        },//支持jpg,pdf,txt等多种格式
        {"name":"下拉框","type":"dropdown","value": ["select1"]},//下拉框的值必须是数组类型,字典是几级,数组的长度就是几
        {"name":"数字","type":"number","value":"1"},
        {"name":"日期","type":"date","value":"YYYY-MM-DD"},
        {"name":"单行文本","type":"single","value":"abc"},
        {"name":"多行","type":"multi","value":"abc"},
        {"name":"复选框","type":"checkbox","value":["checkbox1","checkbox2","checkbox3"]} 
    ], 
    "targetUser":"工号|auto",
    "createUser":"工号", 
    "flowName":"工单模版名称", 
    "comment":"备注", 
    "stepName":"工单步骤名称",
    "action":"1",
    "priority":"1"
}

返回值:

字段 含义
code 响应码
message 响应信息
businessId 工单唯一id,code值为200时才返回
number 工单编号,可以在客服系统中通过这个编号去搜索工单,code值为200时返回

返回错误码及含义:

错误码 含义
200 请求成功
400 请求体参数错误
403 鉴权参数错误
500 服务器错误

返回200示例

{
    "code": 200,
    "message": "ok"
}
或
{
    "code": 200,
    "message": "success!",
    "businessId": "faab2490-a673-11e8-b108-d77b0ef7f559"//工单的_id,
    "number": "2019010900001"//工单编号
}

返回400示例:

{
    "code":400,
    "message": "Please check your parameters"
}

返回403示例:

{
    "code": 403,
    "message": "Forbidden"
}

返回500示例:

{
    "code": 500,
    "message": "Internal Server Error"
}

返回400 message示例:

参数名 说明
Message String _id not found:根据id没有找到对应工单
flowName is required:工单模板名称必填
createUser is required:创建坐席必填
next step of the worksheet is not the step:执行的步骤不是当前工单的下一步
flowName not found:没有找到该流程(工单模板)
customerId not found:没有找到该客户
action not found: 没有找到该动作
targetUser not found:没有找到该坐席
createUser not found:没有找到该坐席
field is required field:单选框字段是必填字段
field does not match the system field type:单选框字段的类型传错
field must be of string type:单选框字段必须是字符串类型
field must be of number type:单选框字段必须是数字类型
field must be of yyyy-MM-dd type:单选框字段必须是日期类型
field must be of array type:单选框字段必须是数组类型
not be found dic: 没有找到对应的字典




3.工单备注流出接口对接

工单备注流出接口与工单流出接口都是可以后台客服系统进行选择配置,只是流出的数据格式不一样。配置后工单流出以及工单备注流出的数据都会流出到配置的第三方企业接口。配置界面如下图:

工单备注流出数据格式:

{
    _id: "faab2490-a673-11e8-b108-d77b0ef7f559",   // 工单id,不能为空
    user: "8000",  //坐席工号
    createTime: "2020-01-01 12:20:11", //备注创建时间
    createTimestamp: 1542117465741,  //备注创建时间毫秒数
    comment: "好的呀", //备注内容
    attachs: ["http://www.baidu.comg/sdfdsfap.jsg"],  //附件 ['附件地址1','附件地址2']
    actionType: 'comment'  //固定必填,说明是备注的流出
}




4.工单备注流入接口对接

接口请求方式:POST

接口参数格式:json

注意:本接口的使用需要进行接口鉴权

请求url: http://apis.7moor.com/v20170704/business/handleBusiness/{accountID}?sig=xxxx

请求url示例:

http://apis.7moor.com/v20170704/business/handleBusiness/N00000000556?sig=41276A8E7767352A0FE7456D20F03D3

请求体:

字段 类型 备注
_id String 工单ID【必填】
user String 坐席工号如8000【必填】,由哪个坐席添加,如果是客户添加的则可以固定指定一个坐席工号
createTime String 创建时间,不填或格式不对时使用服务器时间
格式:"yyyy-mm-dd HH:mm:ss"
comment String 备注内容,必填,不填返回失败
attachs String[] 附件的链接地址,数组
格式:["附件地址1","附件地址2"]
actionType String 固定comment【必填】,说明是备注流入

请求体示例:

{
    "_id":"571d4880-ba5a-11e8-8e8a-0de867e1f3a4",
    "user":"8180",
    "comment":"好像的是的",
    "actionType":"comment",
    "attachs":["https://gss0.bdstatic.com/-4o3dSag_xI4khGkpoWK1HF6hhy/baike/w%3D268%3Bg%3D0/sign=42f2a7fab01c8701d6b6b5e01f44f912/e1fe9925bc315c60582972f18eb1cb134954776b.jpg"]
}

返回400示例:

{
    "code":453,
    "message": "附件内容过大,附件大小最多不能超过20M"
}

返回错误码信息:

code值 message提示信息
431 _id参数未传,该参数是必传参数
432 user参数未传,该参数是必传参数
433 备注信息不能为空
434 附件参数必须是数组形式,且值为http或https链接形式
435 未找到该工单信息
436 该工号未找到
437 actionType错误,请填写comment表示流入工单备注
451 上传附件失败
452 下载附件失败, 请检查附件地址
453 附件内容过大,附件大小最多不能超过20M
499 unknown error occured!

5.工单查询接口

接口请求方式:POST

接口参数格式:json

注意:本接口的使用需要进行接口鉴权

频次限制:20次/每分钟,查询数据限制:默认最多返回200条数据

请求url: {HOST}/v20170704/business/getBusinessDetail/ACCOUNTID?sig=SIG

请求时请将{HOST}换成对接数据查询中获取到的请求域名,ACCOUNTID替换为账户编号,SIG是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

请求url示例:

http://apis.7moor.com/v20170704/business/getBusinessDetail/N00000000556?sig=41276A8E7767352A0FE7456D20F03D3

请求体参数: 只传一个参数number时,不考虑beginCreateTime,endCreateTime这两个是否必填

参数 类型 是否必填 描述
number String 工单编号

传的参数不止一个时,考虑beginCreateTime,endCreateTime这两个字段必填

    <tr>
        <td>flow</td>
        <td>String</td>
        <td>否</td>
        <td>工单模板</td>
    </tr>
    <tr>
        <td>beginCreateTime</td>
        <td>String</td>
        <td>是</td>
        <td>工单创建时间段的开始时间,时间格式为 yyyy-MM-dd HH:mm:ss</td>
    </tr>
    <tr>
        <td>endCreateTime </td>
        <td>String</td>
        <td>是</td>
        <td>工单创建时间段的结束时间,时间格式为 yyyy-MM-dd HH:mm:ss</td>
    </tr>
    <tr>
        <td>beginLastUpdateTime</td>
        <td>String</td>
        <td>否</td>
        <td>单最近更新时间段的开始时间,时间格式为 yyyy-MM-dd HH:mm:ss</td>
    </tr>
    <tr>
        <td>endLastUpdateTime </td>
        <td>String</td>
        <td>否</td>
        <td>工单最近更新时间段的结束时间,时间格式为 yyyy-MM-dd HH:mm:ss</td>
    </tr>
    <tr>
        <td>historyStartTime </td>
        <td>String</td>
        <td>否</td>
        <td>工单历史创建时间段的开始时间,时间格式为 yyyy-MM-dd HH:mm:ss</td>
    </tr>
    <tr>
        <td>historyEndTime </td>
        <td>String</td>
        <td>否</td>
        <td>工单历史创建时间段的结束时间,时间格式为 yyyy-MM-dd HH:mm:ss</td>
    </tr>
    <tr>
        <td>page  </td>
        <td>number</td>
        <td>否</td>
        <td>页数</td>
    </tr>
    <tr>
        <td>pageSize  </td>
        <td>number</td>
        <td>否</td>
        <td>每页多少条</td>
    </tr>
</tbody>
参数 类型 是否必填 描述
number String 工单编号
customerId String 客户id

请求体示例:

{
    "number": "2020070700001",
    "flow": "",
    "beginCreateTime": "2020-06-14 23:59:59",
    "endCreateTime": "2020-07-13 23:59:59",
    "beginLastUpdateTime": "",
    "endLastUpdateTime": "2020-07-14",
    "historyStartTime": "2020-06-13 23:59:59",
    "historyEndTime": "2020-07-14 23:59:59",
    "page": 1,
    "pageSize": 200
}

返回400示例:

1、只传number,为空或不对:

{
    "code": 400,
    "message": "Please check your parameters, because business is inexistence!"
}

2、传多个参数,未传beginCreateTime,endCreateTime

{
    "code": 400,
    "message": "Please check your parameters, beginCreateTime and endCreateTime must need"
}

3、beginCreateTime, endCreateTime超过了一月限制

{
     "code": 400,
     "message": "beginCreateTime and endCreateTime must within a month!"
}

返回500示例:

{
    "code": 500,
    "message": "server has error"
}

返回200示例:

{
"code": 200,
"message": "success!",
"totalCount": 1,
"data": [
    {
        "_id": "0c6753e0-c001-11ea-872e-3785eca9b7a7",
        "number": "2020070700001",
        "flow": "f2dbf4e0-d2ac-11e9-a569-c5359b9a58f5",
        "flowName": "请假申请",
        "status": "dealing",
        "priority": "紧急",
        "createUser": "1234",
        "createTime": "2020-07-07 11:22:12",
        "lastUpdateTime": "2020-07-09 11:38:26",
        "customer": "79a67370-a187-11ea-a279-dfd3fd9ce306",
        "customerName": "111112222",
        "totalDuration": 0,
        "history": [
            {
                "master": "1234",
                "excuteUser": "4321",
                "fromStep": "审核申请",
                "step": "填写申请",
                "backInfo": "哒哒哒哒哒哒",
                "duration": {
                    "stayDuration": "21 h 21 m 51 s"
                },
                "time": "2020-07-09 11:38:26",
                "action": "backIn"
            },
            {
                "master": "1234",
                "step": "审核申请",
                "backInfo": "水水水水",
                "attach": [],
                "time": "2020-07-08 14:16:35",
                "action": "comment"
            },
            {
                "master": "1234",
                "info": "工单优先级由【普通】调整为【紧急】",
                "excuteUser": "1234",
                "time": "2020-07-08 14:14:29",
                "action": "changePriority"
            },
            {
                "master": "1234",
                "trigger": "审核申请-触发器通知",
                "info": "分配给座席【4321】",
                "time": "2020-07-07 11:22:12",
                "action": "triggerAssign"
            },
            {
                "master": "1234",
                "excuteUser": "",
                "fromStep": "填写申请",
                "step": "审核申请",
                "data": {},
                "duration": {},
                "time": "2020-07-07 11:22:12",
                "action": "transformIn"
            },
            {
                "master": "1234",
                "excuteUser": "",
                "step": "填写申请",
                "data": {
                    "b-土地": "地球-->中国-->北京",
                    "c-土地": "学校1-->班级1-1",
                    "申请人": "111112222"
                },
                "time": "2020-07-07 11:22:12",
                "action": "create"
            }
        ]
    }
  ]
}

返回参数字段解释:

1、返回数据data.historyaction字段

字段值 说明 /
create 新建 step:步骤,data:可能有自定义字段
bcakIn 退回 fromStep step backInfo
recreate 重新提交 step data
transformIn 流转 fromStep step
comment 备注 backInfo备注内容,attach备注的附件
share 关注 currentFollowedAgents:数组,存放的关注人
assign 分配 assignUser:被分配的人
triggerSendSms 触发器发送短信 trigger触发器名称,info
triggerSendEmail 触发器发送邮件 trigger触发器名称,info
triggerAssign 触发器分配 trigger触发器名称,info
changePriority 改变优先级 info
complete 完成

字段值 说明
excuteUser 下一步处理人
master 当前处理人
step 当前步骤
fromStep 上一步骤
data 自定义字段
duration 处理时长(一般只有流转有)
info 该步骤信息
backInfo 备注(备注、退回有该字段)
totalDuration 总的处理时长
customer 客户id
customerName 客户名称
status 工单状态
flow 工单模板
creatUser 创建人
_id 工单id

6.常见问题及使用说明

1.常用字段解释。action(动作名称),stepName(当前步骤的名称)字段含义如图所示。

gddj-1

7.满意度评价推送

工单满意度评价配置:在简单版设置→工单设置→其他设置里,在配置这个满意度评价配置之前需要先在工单满意度设置里面配置工单满意度详情 注意:在配置满意度详情之前需要先到设置→渠道设置→短信/闪信→短信模板管理→报备短信模板,报备的场景需要选工单模板

满意度配置流程:

满意度评价显示:

工单配置流程业务完成的时候("status": "complete")会推送满意度评价链接"satisfiedUrl": "https://kf.7moor.com/appraise/6eSYgGnJ"

字段
status complete:完成
cancel:取消
satisfiedUrl https://kf.7moor.com/appraise/6eSYgGnJ
注意:如需使用短信推送满意度评价链接在工单步骤配置触发器推送类型需要选发送满意度调查