工单接口对接

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

• 1. 工单流出接口对接

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

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

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

• 5. 工单查询接口

• 6. 常见问题及使用说明

• 7. 满意度评价推送

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	工单结束时间
createTimestamp	int	创建时间毫秒数
relatedBusiness	String	有关联工单才有值
createUser	String	创建工单坐席
createMode	String	创建工单的方式
followedAgents	ArrayList	工单关注人设置，有关注人才有值
relatedCallSheet	ArrayList	关联通话
relatedWebchats	ArrayList	关联会话
priority	String	工单优先级
category	String	工单分类（同级不能重复），非必填。例：一级分类@二级分类@三级分类@四级分类@五级分类（若无法匹配到系统目前已有的工单分类，会统一返回格式无效。若传的参数为空，则表示为工单分类为其他）

json示例：

{
  "_id":"46479500-5b7d-11ee-b98e-cb41508bd72f",
  "customerId":"b9dcd3c0-2f6a-11ee-a047-23e7b5d70341",
  "user":"8998",
  "fields":[
        {
        "name":"动作字段",
        "type":"date",
        "value":""
        },
        {
        "name":"baixintest1",
        "type":"dropdown",
        "value":[
        ]
        }],
  "createTime":"2023-09-25 16:26:50",
  "createTimestamp":1695630410000,
  "action":"action2",
  "stepName":"testStep",
  "businessNumber":"2023092500003",
  "priority":"1",
  "category":"1级@test"
  "relatedBusiness":[
        "2023092500002"
  ],
  "createUser":"33522710-0f7e-11eb-80bb-6353065647b0",
  "createMode":"business",
  "visitorId":"ca788640-5b7d-11ee-8b6a-1df5a8bfee25",
  "followedAgents":[
        "99a4d530-dc00-11ec-9263-436b0cf21199",
        "b4acab50-e864-11ea-b89b-ad609aa38554"
  ],
  "relatedCallSheet":[
        "f96cbe91-a91e-40f7-87d0-4eae168f0442"
  ],
  "relatedWebchats":[
        "ef92bda0-5b65-11ee-b98e-cb41508bd72f"
  ],
  "flowInfo":"字段1:undefined,baixintest1:[]",
  "stepFields":[
        {
        "name":"字段1",
        "type":"single",
        "value":""
        },
        {
        "name":"bxtest1",
        "type":"dropdown",
        "value":[]
        }
  ]
}

返回值：

字段	含义
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表示普通,紧急,很紧急
category	String	工单分类（同级不能重复），非必填。例：一级分类@二级分类@三级分类@四级分类@五级分类（若无法匹配到系统目前已有的工单分类，会统一返回格式无效。若传的参数为空，则表示为工单分类为其他）

请求体示例：

{ 
    "_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",
    "category": "1级@test"
}

返回值：

字段	含义
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"
}

返回403示例，当前操作工单非对应座席或是角色权限不足去操作工单：

{
    "code": 403,
    "message": "403 is not Access"
}

返回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',  //固定必填，说明是备注的流出
    category: "1级@test"//工单分类（同级不能重复），非必填。例：一级分类@二级分类@三级分类@四级分类@五级分类（若无法匹配到系统目前已有的工单分类，会统一返回格式无效。若传的参数为空，则表示为工单分类为其他）
}

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这两个字段必填

参数	类型	是否必填	描述
number	String	否	工单编号
customerId	String	否	用户id
flow	String	否	工单模板
beginCreateTime	String	是	工单创建时间段的开始时间，时间格式为 yyyy-MM-dd HH:mm:ss
endCreateTime	String	是	工单创建时间段的结束时间，时间格式为 yyyy-MM-dd HH:mm:ss
beginLastUpdateTime	String	否	单最近更新时间段的开始时间，时间格式为 yyyy-MM-dd HH:mm:ss
endLastUpdateTime	String	否	工单最近更新时间段的结束时间，时间格式为 yyyy-MM-dd HH:mm:ss
historyStartTime	String	否	工单历史创建时间段的开始时间，时间格式为 yyyy-MM-dd HH:mm:ss
historyEndTime	String	否	工单历史创建时间段的结束时间，时间格式为 yyyy-MM-dd HH:mm:ss
category	String	否	工单分类（同级不能重复）
page	number	否	页数
pageSize	number	否	每页多少条

请求体示例：

{
    "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",
    "category": "1级@test",
    "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": "紧急",
    "category": "1级@test",
    "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,
    "satisfaction": {
            "chooseTitle": "请您对本次处理结果及服务做满意度评价",
            "choose": [
                {
                    "value": 3,
                    "tags": [],
                    "name": "一般",
                    "subTitle": "请您对本次处理结果做满意度评价"
                },
                {
                    "value": 3,
                    "tags": [],
                    "name": "一般",
                    "subTitle": "请您对本次的客服服务做满意度评价"
                }
            ],
            "randomKey": "esFciQJy",
            "otherQuestionTitle": "请留下您宝贵的意见与建议",
            "otherQuestionContent": "",
            "appraiseTime": "2023-10-08 09:32:31",
            "appraiseStatus": "appraised"
        },
    "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.history中action字段含义解释

字段值	说明	/
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
timeoutFlag	工单是否超时
relatedCallsheet	关联通话id
relatedWebchats	关联会话id
relatedBusiness	关联工单编号
satisfaction	满意度评价

6.常见问题及使用说明

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

7.满意度评价推送

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

满意度配置流程：

满意度评价显示：

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

字段	值
status	complete：完成 cancel：取消
satisfiedUrl	https://kf.7moor.com/appraise/6eSYgGnJ

注意：如需使用短信推送满意度评价链接在工单步骤配置触发器推送类型需要选发送满意度调查