一洽客服系统客服端接入业务系统
1.业务系统应用场景
客服的工作场景需要客服频繁的在不同的系统间切换来帮助客户解决问题或者进行答疑。一洽提供业务集成模块的目的是为了让客服的大部分业务操作能方便快捷的在一洽系统的对话页面完成，从而提高客服的工作效率和对访客的服务质量。
您是否也遇到了以下类似的问题，如果有，一洽的业务系统集成模块可能能帮助到您。
场景一：
访客：我的积分为什么被清零了
客服：？？？？您是哪位？什么级别的会员？？？
场景二：
访客：我刚下的订单弄错了，想取消怎么做呢
客服：您下单的手机号？订单号？购买的商品类型？
访客：我的手机号XXX，订单号在哪里找
客服：截图指引
访客：我的订单号xxxxx
客服：稍等正在帮您查询。。。。。
10秒钟。。。20秒钟。。。30秒钟。。。
客服：继续对话
场景三：
访客：我要退货
客服：。。。。。
访客：。。。。。。
客服进入退换货系统进行操作，10秒钟。。。20秒钟。。。
新对话接入
新问题产生
客服：解答问题
一洽工作台示例：
2.业务系统配置
使用管理者的权限登录一洽软件后，在设置-API接口页面，填写（如下图）：
1、填写您的业务系统URL和名称，该名称标签会显示在客服界面。
2、选择该URL要接收的业务数据，一洽服务器会通过iframe框架加载您的URL，并且通过GET方式传递您选择的业务数据至URL。
3、选择显示该标签的访客角色，比如该标签是“退换货”，而您希望只有登录的会员才显示“退换货”，那您就可以选择访客的角色是“登录的会员”，那么如果是未登录的访客咨询，则该URL不会被加载，客服也看不到“退换货”标签。
请根据您的实际情况选择。
4、选择显示该标签的客服分组，还比如标签是“退换货”，而您希望只有“退货组”才能看到该标签，其他组是看不到该标签的，那么您可以选择显示该标签的客服分组为“退货组”
，那么其他组的客服是不能看到该标签的，URL也不会被加载。
3.检验业务系统
客服端在加载已配置的业务系统时会将签名信息通过GET的方式传递给开发者的URL，双方通过签名来验证请求的合法性。
GET请求携带的参数如下表示：
| 参数 | 描述 |
|---|---|
| signature | 一洽加密签名，signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。 |
| timestamp | 时间戳 |
| nonce | 随机数 |
开发者通过检验signature对请求进行校验（下面有校验方式）。若确认此次GET请求来自一洽服务器，则进入正常的业务处理，否则进入异常处理流程：
1）将token、timestamp、nonce三个参数进行字典序排序
2）将三个参数字符串拼接成一个字符串进行sha1加密
3）开发者获得加密后的字符串可与signature对比，标识该请求来源于一洽
检验signature的JAVA示例代码：
public boolean verifyUrl(String msgSignature, String timeStamp, String nonce)
throws AesException {
String signature = SHA1.getSHA1(token, timeStamp, nonce);
if (!signature.equals(msgSignature)) {
throw new AesException(AesException.ValidateSignatureError);
}
return true;
}
一洽的签名生成方式和微信一致。
C# C++ Java PHP Python 微信代码示例下载：示例代码
示例：
token:myToken timestamp:myTimestamp nonce:myNonce signature输出：81ceaac69a2f44be4f98d4adbea202d5792c62bb getUrl:http://api.myserver.com/myBuinessPage?timestamp=myTimestamp&nonce=myNonce&signature=81ceaac69a2f44be4f98d4adbea202d5792c62bb
4.企业业务系统接收来自一洽的业务数据
一洽业务数据按照数据分类，以GET请求的参数形式传递给企业业务系统，业务参数如果存在多个属性值，则将多个属性以A=1&B=2的形式拼接完做URLEncode后赋值给业务参数。
例如：登录客服
数据
传参示例：
logData=logStaffId%3D14%26logStaffLogname%3D13666666666%26logStaffName%3D%E9%83%91%E4%B8%BD%E6%96%87%26logstaffRole%3D%E8%B6%85%E7%BA%A7%E7%AE%A1%E7%90%86%E5%91%98
urlDecode logData的值为：
logStaffId=14&logStaffLogname=13666666666&logStaffName=郑丽文&logstaffRole=超级管理员
4.1对话状态
参数：chatStatus
值：对话状态 0-未对话，1-对话开始，2-对话结束
4.2登录客服
参数：logData
子项描述：
| 参数 | 解释 |
|---|---|
| logStaffId | 登录客服的ID 例如：18 |
| logStaffLogname | 登录客服的登录名 例如：13666666666 |
| logStaffName | 登录客服的姓名 |
| logStaffRole | 登录客服的角色 |
4.3会员数据
参数：metaData
值：加密的会员信息，具体请参考访客端接入中的会员信息接入
4.4扩展数据
参数：myData
值：访客端接入时传给一洽的自定义业务数据，一洽原样返回给业务系统
4.5访客数据
参数：visitorData
子项描述：
| 参数 | 解释 |
|---|---|
| visitorMedia | 客户端的媒介，1-PC网页，2-手机网页，3-iphone sdk，4-android sdk，5-微信 |
| visitorType | 访客身份类型 -1未知，0-游客(web)，1-会员(vip)，2-SDK游客(sdk)，4-微信（wechat)，5-自定义接口(custom) |
| mediaId | visitorType==5时，此值有效，值为自定义去掉的渠道ID |
| visitorId | 访客ID，身份描述+ID 例如：vip123 |
| visitorName | 访客的姓名 |
| visitorPhoto | 访客的头像 |
| visitTimes | 访客来访的次数 |
| visitorLan | 访问者的语言，例如：en |
| visitorIp | 访客的IP地址 |
| visitorCountry | 国家 |
| visitorProvince | 省份 |
| visitorCity | 城市 |
| browserName | 访客的浏览器名称 |
| browserVersion | 访客的浏览器版本号 |
| screenResolution | 访客的屏幕分辨率 |
| osName | 访客的操作系统 |
| osVersion | 访客的操作系统版本 |
| se | 访客来源的搜索引擎标识 例如：baidu |
| keyword | 访客的来源搜索关键字 例如：一洽客服 |
| keywordType | 0：未区分SEO、推广 1：自然优化 2：推广 |
| referPage | 访客的来源页面 例如：http://www.echatsoft.com |
| firstTime | 访客的进入网站时间 例如：2016-01-09 17:53:32 |
| firstPage | 访客的落地页 例如：http://www.echatsoft.com |
| firstPageTitle | 落地页的标题 例如：一洽软件 |
| lastChatTime | 访客上次对话事件 例如：2015-07-08 11:23:36 |
| lastChatStaffId | 上次对话的客服ID |
| lastChatStaffLogname | 上次对话的客服登录名 |
| lastChatStaffName | 上次对话的客服的姓名 |
4.6路由数据
参数：routeData
子项描述：
| 参数 | 解释 |
|---|---|
| routeId | 访客进入网站或者发起对话所触发的路由ID -1表示web默认 -2表示微信默认 -3表示SDK默认 |
| routeName | 路由名称 例如：一洽客服 |
| styleId | 路由所使用的样式ID |
| chatDepartmentId | 接待分组的ID，0代表没有分组 |
| chatDepartmentName | 接待分组的名称 例如：一洽售后组 |
4.7对话数据
参数：chatData
正在对话的访客此参数有效
子项描述：
| 参数 | 解释 |
|---|---|
| chatPage | 对话发起页面 例如：http://www.echatsoft.com |
| chatPageTitle | 对话页面标题 例如：一洽软件 |
| chatTimes | 历史对话次数 |
| chatEvent | 对话发起的方式，1-点击图标，2-邀请对话，3-主动对话 |
| chatRequestTime | 请求对话的时间 |
| chatAnswerTime | 对话接通的时间 |
| chatType | 对话的类型，1-在线对话，2-忙碌对话，3-离线消息 |
| chatStaffId | 接待对话的客服ID |
| chatStaffLogname | 接待对话的客服登录名 |
| chatStaffName | 接待对话的客服姓名 |
| chatStaffRole | 接待对话的客服的内部角色名称 |
| chatEntrance | 对话入口 访客端传参为echatTag的值 |
| chatRecordId(已废弃) | 对话记录的ID |
| uniqueRecordId | 会话记录的唯一值ID，组成方式为:${talkType}_${talkId} talkType定义: 1:人工对话 3:留言会话 5:机器人会话 |
4.8客户数据
参数：crmData
子项描述：
| 参数 | 解释 |
|---|---|
| visitorId | 访客的唯一值 |
| category | 访客类别 例如：意向客户 |
| name | 访客姓名 |
| nickName | 访客昵称 |
| gender | 性别，0-未知， 1-男， 2-女 |
| age | 年龄 |
| birthday | 生日 例如：2015-08-01 |
| maritalStatus | 婚姻状况 1：未婚 2：已婚 0：未知 |
| phone | 电话号码 |
| QQ号码 | |
| 微信号 | |
| 邮箱地址 | |
| nation | 国家 |
| province | 省份 |
| city | 城市 |
| address | 地址 |
| photo | 头像 |
| memo | 备注 |
4.9工单数据
参数：jobData
子项描述：
| 参数 | 解释 |
|---|---|
| jobId | 工单id |
| jobFrom | 工单创建来源 1:web 2:邮件 3:控制台 4:sdk 5:接口创建 |
| replyEmail | 回复邮箱 |
| createTime | 工单创建时间 yyyy-MM - dd |
| jobStatus | 工单状态 1：新建，2：已开启，3：待回应，4：已挂起，5：已解决，6：已关闭 |
| jobDepartmentId | 工单处理分组ID |
| jobStaffId | 工单处理人ID |
5. demo代码下载
说明：可下载对应语言的demo工程，直接在项目上修改即可快速实现会员接入以及业务系统对接。
5.1 JAVA demo下载
说明：可下载对应语言的demo工程，直接在项目上修改即可快速实现会员接入以及业务系统对接。
5.1 JAVA demo下载
下载地址：java demo
6.业务系统集成流程
