工单接口对接

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



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":"2017-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/2017-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":"2019-07-31 17:34:21",
    "businessNumber":"工单编号",
    "flowInfo":"日期:2017-09-06",
    "stepFields":[{"name":"日期","type":"date","value":"2017-09-06"}]
}

返回值:

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




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

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

注意:

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

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

  • 接口请求方式:POST

  • 接口参数格式:json

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

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

  • 鉴权文档:接口鉴权

请求url:

-请求示例:

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

请求体:

字段 类型 备注
_id String 工单ID,如果为空则表示新建工单
uniqueId String 用户区别是否是同一请求,24小时内同一个账户不允许传递相同的uniqueId,相同时返回错误,返回值`{message:"uniqueId exists",code:400})`
customerId String 客户ID,如果为空则表示未知客户
fields Object类型数组 工单字段(name:字段名称, type:字段类型,value:字段值)
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码"}]},//支持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: "2018-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.常见问题及使用说明

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

gddj-1