一洽客服系统·工单系统-接收事件通知

在开发API-服务器交互-业务数据接收处开启接收工单数据后，当工单被更新（包括新建）时，一洽会向服务器配置处的URL推送对应的事件。

目录

  1. 选择数据接收模式
  2. 消息加解密说明
  3. 接收工单数据
  4. 工单创建
  5. 工单更新
  6. 工单满意度评价

1. 选择数据接收模式

使用管理者的权限登录一洽软件后，在更多设置-开放API页面中配置appId,消息加解密key（encodingAesKey),token.
如图：

配置信息说明：

appId：一洽系统自动生成的应用唯一值，用于接口交互时判断用户身份。

encodingAesKey（消息加解密key)：由开发者手动填写或随机生成，将用作JSON/XML数据加解密密钥，为保证数据安全推荐使用密文方式传输数据。

Token：Token可由开发者可以任意填写，用作生成签名

数据传输模式：明文：原始数据字符串 密文：通过AES加密过后的字符串

名词介绍：

apiServer：一洽提供给用户的接口服务器地址,例如：api.echatsoft.com

accessToken：调用一洽接口的授权令牌

ip白名单：允许访问一洽接口服务器的来源IP

2. 消息加解密说明

什么是EncodingAESKey？
一洽采用AES对称加密算法对消息体对行加密，EncodingAESKey则是加密所用的秘钥。消息接收方用此秘钥对收到的密文消息体进行解密。

消息加解密过程和微信公众平台的消息加解密方式一致。
示例代码（包括C++、php、Java、Python和C#版本）示例代码
注：一洽的签名信息在GET请求中，微信的示例代码签名在XML结构中，Encrypt节点的加解密方式是一样的。

Java要求jdk 1.6及1.6以上
异常java.security.InvalidKeyException:illegal Key Size的解决方案：在官方网站下载JCE无限制权限策略文件（请到官网下载对应的版本， 例如JDK7的下载地址：http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html 下载后解压，可以看到local_policy.jar和US_export_policy.jar以及readme.txt，如果安装了JRE，将两个jar文件放到%JRE_HOME%\lib\security目录下覆盖原来的文件；如果安装了JDK，将两个jar文件放到%JDK_HOME%\jre\lib\security目录下覆盖原来文件

注意：每次收到post请求后需要返回一洽 success 没有返回一洽会判断为未收到而重新发送

3.接收工单数据

接工单数据收>向开发者服务器URL推送相关数据，基础字段：

参数 参数类型 描述
jobId long 工单id
jobAttribute byte 工单属性，1=内部工单，2=外部工单

4. 工单创建

当工单创建时推送此消息，除了工单相关数据，开发者可登录一洽控制台，在开发API-服务器交互-工单数据处选择业务数据，包括：
会员数据、扩展数据、访客数据、路由数据，其中除了扩展数据，其它数据均只在web端创建外部工单有效。
GET参数追加：dataType=jobCreated

请求地址示例：

工单基础xml属性解释：

工单基础xml属性解释：

参数 参数类型 描述
title String 工单标题
content String 工单内容，超过5W字符会被截断
jobFollowerIds String 工单跟踪人id,多个用逗号分隔
jobFollowerNames String 工单跟踪人姓名,多个用逗号分隔
requesterLan String 工单请求语言
requesterUserId String 请求者id，访客vipId或客服id
requesterUserType byte 请求者类型，小于0表示客服，否则为访客
styleId long 样式id
jobType byte 工单类型, 1：问题,2：事务,3：故障,4：任务
departmentId long 工单指派分组
distributeUserId long 工单指派客服
priority byte 工单优先级，1：低，2：正常，3：高，4：紧急
jobTemplateId long 工单模板id
status byte 工单状态，1：新建，2：已开启，3：待回应，4：已挂起，5：已解决，6：已关闭
replyEmail String 回复邮箱
replyPhone String 回复短信
memo String 工单备注
attachments json 工单附件列表，对象列表，格式见后Attachment字段定义
name String crm字段-姓名
phone String crm字段-手机号
qq String crm字段-qq
wechat String crm字段-微信
email String crm字段-邮箱
address String crm字段-地址
nickName String crm字段-昵称
gender byte crm字段-性别
crmMemo String crm字段-备注
maritalStatus byte crm字段-婚姻状态
age byte crm字段-年龄
birthday String crm字段-生日
jobLink String 工单链接
c1-c20 String crm自定义字段
t1-t30 String 工单自定义字段
crmId long 客户crm信息的id

Attachment字段定义:

对象 参数 参数类型 描述
  type byte 文件类型，固定为1
fileValue url String 文件url
  name String 文件名称
  size long 文件大小，单位：字节
  fileType int 0:其它，1：语音，2：视频，3：地理位置，4：图片

示例： 

<xml>
  <jobId>1088</jobId>
  <jobAttribute>2</jobAttribute>
  <jobData>
    <title><![CDATA[标题]]></title>
    <requesterLan><![CDATA[en]]></requesterLan>
    <requesterUserId><![CDATA[79]]></requesterUserId>
    <requesterUserType>1</requesterUserType>
    <styleId>225</styleId>
    <jobType>1</jobType>
    <departmentId>2</departmentId>
    <distributeUserId>78</distributeUserId>
    <priority>3</priority>
    <jobTemplateId>4</jobTemplateId>
    <status>2</status>
    <replyEmail><![CDATA[huangzhilin2015@outlook.com]]></replyEmail>
    <replyPhone><![CDATA[18349975744]]></replyPhone>
    <memo><![CDATA[备注]]></memo>
    <attachments>
      <attachment>
        <type>1</type>
        <fileValue>
          <url><![CDATA[http://x.xx/a.png]]></url>
          <name><![CDATA[a.png]]></name>
          <size>12442</size>
          <fileType>0</fileType>
          <key><![CDATA[job/1/e26a4bb7-2639-4c1d-9c45-9a43da8567d9_350_1556]]></key>
		<bucket><![CDATA[chat]]></bucket>
        </fileValue>
      </attachment>
      <attachment>
        <type>1</type>
        <fileValue>
          <url><![CDATA[http://x.xx/b.png]]></url>
          <name><![CDATA[b.png]]></name>
          <size>115487</size>
          <fileType>0</fileType>
          <key><![CDATA[job/1/e26a4bb7-2639-4c1d-9c45-9a43da8567d9_350_1556]]></key>
		<bucket><![CDATA[chat]]></bucket>
        </fileValue>
      </attachment>
    </attachments>
  </jobData>
</xml>

5. 工单更新

GET参数追加：dataType=jobUpdated

请求地址示例：

当工单更新时推送此消息，消息包含更新的字段和更新的内容，目前支持通知以下字段：

参数 参数类型 描述
status byte 工单状态，1：新建，2：已开启，3：待回应，4：已挂起，5：已解决，6：已关闭，
replyTpe byte 工单回复类型，1=内部回复，2=外部回复，3=内部回复和外部回复
priority byte 工单优先级，1：低，2：正常，3：高，4：紧急
jobType byte 工单类型, 1：问题,2：事务,3：故障,4：任务
topic   主题
topicId long 主题ID
topicName String 主题名
distributeUser   处理人
staffId long 客服id
staffName String 客服名
staffRole String 客服角色名
staffLogname String 客服登录名
replyContent String 工单回复内容(外部回复或者内部回复)，超过5W字符会被截断
replyEmail String 回复邮箱地址
replyPhone String 回复手机号码
jobUpdator   更新人,其中type值=-1表示客服,>0表示访客类型
memo String 工单备注
c1-c20 String crm自定义字段
t1-t30 String 工单自定义字段
name String crm字段-姓名
phone String crm字段-手机号
qq String crm字段-qq
wechat String crm字段-微信
email String crm字段-邮箱
address String crm字段-地址
nickName String crm字段-昵称
gender byte crm字段-性别
crmMemo String crm字段-备注
maritalStatus byte crm字段-婚姻状态
age byte crm字段-年龄
birthday String crm字段-生日

Attachment字段定义:

对象 参数 参数类型 描述
  type byte 文件类型，固定为1
fileValue url String 文件url
  name String 文件名称
  size long 文件大小，单位：字节
  fileType int 0:其它，1：语音，2：视频，3：地理位置，4：图片

示例： 

<xml>
	<msgId>275867516</msgId>
	<tm>1668150932968</tm>
	<jobId>5715</jobId>
	<jobAttribute>2</jobAttribute>
	<jobData>
		<replyType>2</replyType>
		<jobUpdator>
			<type>-1</type>
			<updaterId><![CDATA[1556]]></updaterId>
			<updaterName><![CDATA[胡仲舜]]></updaterName>
		</jobUpdator>
		<replyContent><![CDATA[<p>你的问题已经处理好了</p>]]></replyContent>
		<attachments>
			<attachment>
				<type>1</type>
				<fileValue>
					<url><![CDATA[https://qnfile.echatsoft.com/job/1/e26a4bb7-2639-4c1d-9c45-9a43da8567d9_350_1556]]></url>
					<name><![CDATA[h5-webview文件上传.png]]></name>
					<size>173837</size>
					<fileType>4</fileType>
					<key><![CDATA[job/1/e26a4bb7-2639-4c1d-9c45-9a43da8567d9_350_1556]]></key>
					<bucket><![CDATA[chat]]></bucket>
				</fileValue>
			</attachment>
		</attachments>
	</jobData>
</xml>

6. 工单满意度评价

GET参数追加：dataType=jobEvaluation

请求地址示例：

当有用户评价工单时推送此消息，消息包含评价满意度信息，目前支持通知以下字段：

参数 参数类型 描述
jobId long 工单所属公司id
evaluateDatetime long 用户评价时间，长整型时间戳
mainItem byte 评价满意度，取值在[1,5]，5表示非常满意，1表示非常差评
comment String 访客评价备注内容，最多50字符
subItems String 评价子项

示例： 

<xml>
  <jobId>1063</jobId>
  <evaluateDatetime>1634132442000</evaluateDatetime>
  <mainItem>5</mainItem>
  <comment><![CDATA[服务态度非常好,我很喜欢]]></comment>
  <subItems><![CDATA[态度良好,回复及时]]></subItems>
</xml>