开发指南

# 平台电商（Platform OpenAPI）

# 接口鉴权

接口鉴权参考通用说明-数据校验 (opens new window)

# 接口协议

接口属性描述了接口的方法、地址和Content-Type，Payload部分描述了接口的协议内容。

# 第三方登录

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/account/login?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
	"userName":"qiyu_merchant@163.com",
	"code":"qiyu_merchant",
	"shopCode":"merchant"
}

接口参数说明如下:

参数 是否必须 参数说明
userName 是 登录的平台所属企业中的账号
code 是 登录平台所属企业code，商户二级域名前缀，商户登录域名为qiyu_merchant.qiyukf.com，code即为qiyu_merchant
shopCode 是 登录平台所属企业shopCode，商户二级域名前缀‘_’后的内容，商户登录域名为qiyu_merchant.qiyukf.com，shopCode即为merchant
  • code和shopCode必填其一，都存在的情况下，优先以code为准;

响应：

{
	"code":200,
	"result":{redirectUrl:”http://qiyu_merchant.qiyukf.com?thirdToken=ahudgsabdasbdahsbdasbdasbdu”},
	"message":"success",
	"total":0
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果，一个如下对象{redirectUrl:”http://qiyu_merchant.qiyukf.com?thirdToken=ahudgsabdasbdahsbdasbdasbdu”}。直接打开对象中的url可完成一次直接登录
message 状态信息描述
total 此处无意义
  • 的redirectUrl可以使用一次登录，直接跳转至这个链接即可，使用一次后失效

# 创建商户

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/create?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "password":"e10adc3949ba59abbe56e057f20f883e",
    "domain":"qiyu-merchant",
    "contact":"13588895902",
    "name":"七鱼商户1号",
    "seatNumber":1,
    "account":"qiyu-merchant@163.com",
    "portrait":"/9j/4AAQSkZJRg...省略若干字符...LE9q0jeKsTQ1kf/2Q=="
}

接口参数说明如下:

参数 是否必须 参数说明
domain 是 商户二级域名前缀，不需要带平台前缀，即是前文提到的shopCode.如平台code为qiyu，商户code为qiyu-merchant,那商户的domain(shopCode)即为merchant
name 是 商户名，50个字符以内
seatNumber 是 坐席数，不能超过剩余平台剩余总坐席数，可以为0
account 是 商户超管超管账号，格式为邮箱，最好是可用邮箱
contact 否 联系方式，50个字符以内
password 是 商户超管登录密码，MD5(32位小写)加密后发送
portrait 否 头像图片文件内容base64运算后的字符串
  • 由于图像图片上传速度较慢，所以这个接口需要上传头像时的超时限制请放宽一些

响应：

{
    "code":200,
    "result":102143,
    "message":"success",
    "total":0
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果,此处成功返回新增商户id
message 状态信息描述
total 此处无意义

# 修改商户

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/update?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "contact":"18668021155",
    "name":"七鱼商户2号",
    "id":"102106",
    "seatNumber":2,
    "account":"qiyu-merchant2@163.com",
    "portrait":"/9j/4AAQSkZJRg...省略若干字符...LE9q0jeKsTQ1kf/2Q=="
}

接口参数说明如下:

参数 是否必须 参数说明
id 是 商户id,与商户列表接口拉取到的数据中id对应
shopCode 否 标识商户，商户二级域名前缀'_'后的字串，与id只需传一个
name 否 商户名，50个字符以内
seatNumber 否 坐席数，增加的数量不能超过剩余平台剩余总坐席数，可以为0
account 否 商户超管超管账号，格式为邮箱，最好是可用邮箱
contact 否 联系方式，50个字符以内
portrait 否 头像图片文件内容base64运算后的字符串
  • 由于图像图片上传速度较慢，所以这个接口需要上传头像时的超时限制请放宽一些
  • 当id与shopCode同时存在时，优先用id标识商户

响应：

{
    "code":200,
    "result":"success",
    "message":"success",
    "total":0
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果,此处成功为success字符串
message 状态信息描述
total 此处无意义

# 启用商户

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/enable?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "id": 102106
}

接口参数说明如下:

参数 是否必须 参数说明
id 是 商户id,与商户列表接口拉取到的数据中id对应
shopCode 否 标识商户，商户二级域名前缀'_'后的字串，与id只需传一个
  • 当id与shopCode同时存在时，优先用id标识商户

响应：

{
    "code":200,
    "result":"success",
    "message":"success",
    "total":0
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果,此处成功为success字符串
message 状态信息描述
total 此处无意义

# 停用商户

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/disable?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "id": 102106
}

接口参数说明如下:

参数 是否必须 参数说明
id 是 商户id,与商户列表接口拉取到的数据中id对应
shopCode 否 标识商户，商户二级域名前缀'_'后的字串，与id只需传一个
  • 当id与shopCode同时存在时，优先用id标识商户

响应：

{
    "code":200,
    "result":"success",
    "message":"success",
    "total":0
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果,此处成功为success字符串
message 状态信息描述
total 此处无意义

# 修改商户密码

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/changePassword?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "id": 102106,
	"password":"e10adc3949ba59abbe56e057f20f883e"
}

接口参数说明如下:

参数 是否必须 参数说明
id 是 商户id,与商户列表接口拉取到的数据中id对应
shopCode 否 标识商户，商户二级域名前缀'_'后的字串，与id只需传一个
password 是 商户超管登录密码，MD5(32位小写)加密后发送
  • 当id与shopCode同时存在时，优先用id标识商户

响应：

{
    "code":200,
    "result":"success",
    "message":"success",
    "total":0
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果,此处成功为success字符串
message 状态信息描述
total 此处无意义

# 获取商户列表

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/list?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "offset":5,
    "limit":4
}

接口参数说明如下:

参数 是否必须 参数说明
offset 是 获取列表分页偏移量(偏移量，并不是页数)
limit 是 获取列表分页大小

响应：

{
    "code":200,
    "result":[
        {
            "id":102146,
            "domain":"qiyu-merchant2",
            "name":"merchant2",
            "seatNumber":33,
            "account":"qiyu-merchant2@163.com",
            "contact":"13800000000",
            "status":1
        },
        {
            "id":102145,
            "domain":"qiyu-merchant3",
            "name":" merchant3",
            "seatNumber":1,
            "account":"qiyu-merchant3@163.com",
            "contact":"13588895902",
            "status":1
        },
        {
            "id":102144,
            "domain":"qiyu-merchant4 ",
            "name":"merchant4",
            "seatNumber":34,
            "account":"qiyu-merchant4@163.com ",
            "contact":"13800000000",
            "status":1
        },
        {
            "id":102143,
            "domain":"qiyu-merchant5",
            "name":"merchant5",
            "seatNumber":1,
            "account":"qiyu-merchant5@163.com ",
            "contact":"13588895902",
            "status":1
        }
    ],
    "message":"success",
    "total":27
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果，一个jsonArray数组，内部是获取的商户列表
message 状态信息描述
total 表示平台下总共有多少商户

# 获取商户信息

POST 请求为：

POST https://qiyukf.com/platform/api/openapi/merchant/query?appKey={appKey}&time={time}&checksum={checksum}
Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
    "id":102146,
    "shopCode":"merchant2"
}

接口参数说明如下:

参数 是否必须 参数说明
id 是 启用商户id，与商户列表接口拉取到的数据中id对应
shopCode 否 商户shopCode，二级域名前缀'_'后的字串
  • id与shopCode两个选一个上传即可，但必须上传一个，当id与shopCode同时上传时，以id为优先参考

响应：

{
    "id":102146,
    "domain":"qiyu-merchant2",
    "name":"merchant2",
    "seatNumber":33,
    "account":"qiyu-merchant2@163.com",
    "contact":"13800000000",
    "status":1,
    "appkey":"c6221648142d4c0822bffe57f8d7a667",
    "appsecret":"C6FE8746920D4B68B968529388BF1A01"
}

响应参数说明如下:

参数 参数说明
code 返回状态码，见状态码表
result 返回结果，一个商户对象
message 状态信息描述
total 此处无意义

# 获取会话记录

# 概述

  1. 此文档描述平台企业通过七鱼提供的开放接口获取平台企业及其子企业会话相关信息的步骤及细节。
  2. 由于会话是跟企业息息相关的数据，为保证数据的安全，七鱼要求企业在调用每个接口时提供相关信息以保证数据的安全。
  3. 同一企业在24小时内, 批量下载任务相同任务最大并发请求访问为一次（所有参数都一样即是同一个任务），访问时间必须在每天的凌晨2点至6点之间。

# 接口鉴权

  1. 企业需单独申请该接口权限（仅限专业版及以上客户）。
  2. 数据鉴权：需要使用 appkey 和 appsecret 参与鉴权，参数可在七鱼后台获取，专业版以上支持该功能（首次进入是可以看到appsecret为空，点击"重置"后会第一次生成，之后点击就是刷新） 设置

# 接口示例

# 批量导出完整请求地址如下例（POST）：

https://qiyukf.com/openapi/export/session/shop?appKey=APPKEY&time=TIME&checksum=CHECKSUM (opens new window) 接口 body内容如下（json格式）：

{"start":"1504972800000","end":"1505016000000","code": "企业二级域名"}

checksum计算方法如下：

package test;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Calendar;
import javax.crypto.Cipher;
import javax.crypto.KeyGenerator;
import javax.crypto.spec.SecretKeySpec;

public class checksum {
    private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};

    public static String encode(String appSecret, String nonce, String time) {
        String content = appSecret + nonce + time;
        try {
            MessageDigest messageDigest = MessageDigest.getInstance("sha1");
            messageDigest.update(content.getBytes());
            return getFormattedText(messageDigest.digest());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private static String getFormattedText(byte[] bytes) {
        int len = bytes.length;
        StringBuilder buf = new StringBuilder(len * 2);
        for (int j = 0; j < len; j++) {
            buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
            buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
        }
        return buf.toString();
    }

    public static String MD5encryption(String plain) {
        String re_md5 = new String();
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            md.update(plain.getBytes());
            byte b[] = md.digest();
            int i;
            StringBuffer buf = new StringBuffer("");
            for (int offset = 0; offset < b.length; offset++) {
                    i = b[offset];
                    if (i < 0)
                            i += 256;
                    if (i < 16)
                            buf.append("0");
                    buf.append(Integer.toHexString(i));
            }
            re_md5 = buf.toString();
        } catch (NoSuchAlgorithmException e) {
                e.printStackTrace();
        }
        return re_md5;
    }

    public static void main(String[] args) {
        String content = "{\"start\":\"1504972800000\",\"end\":\"1505016000000\"}";
        String encryptKey = "APPSECRET";
        String nonce = MD5encryption(content);
        String time = Long.toString(Calendar.getInstance().getTimeInMillis() / 1000);
        String b = encode(encryptKey, nonce, time);
        System.out.println("time:" + time);
        System.out.println("ck:" + b);
    }
}

# 接口访问步骤

分为两步：添加任务，校验任务是否完成（如果已完成则提供数据下载链接）。

# 1.添加任务

地址：https://qiyukf.com/openapi/export/session/shop 描述：该接口用于告诉七鱼,企业将开始一个导出数据的任务。 参数： start和end一同决定了要导出的数据的时间范围，其最大时间间隔不能超过2天。

  • start: 时间戳毫秒单位
  • end: 时间戳毫秒单位
  • code: 企业二级域名

如果一切检查通过，那么该接口会立即返回,其中"message"值是一个有关本次请求的一个专有key用于 2 接口请求时的参数值。

{"code":200,"message":"key"}

# 2.校验任务是否完成

地址：https://qiyukf.com/openapi/export/session/shop/check 描述，该接口用于检测任务是否已做完 参数:

  • key: 即 1 接口返回的 message值
  • code: 企业二级域名

如果一切检查合法并且任务执行完毕将返回

{"code":200,"message":"httpUrl"}

该message值即为一个请求下载数据文件的链接,企业可以利用该链接去下载到一个数据文件，这是一个zip格式文件，解压密码是企业appkey的前12个字符。该下载链接有效时间为6小时。解压之后，可得到两个txt文件。 如果不合法则返回

{"code": 非200,"message":"相关描述"}

由于 1 接口在创建任务后不一定会马上完成，所以最好是在创建任务成功后等待一定时间后再去使用key调用 2 接口。而且根据任务量的不同，任务执行时间长短不定；若 2 接口返回

{"code":14403,"message":"Wait..."}

需要等待一定时间后再次去请求（等待时间由开发者自己设定），直到成功为止。

# 字段说明

  1. session说明如下：
字段 数据库中字段类型和长度 含义 规则细节
id bigint(20) 会话id 全局唯一
startTime bigint(20) 会话开始时间 单位毫秒
endTime bigint(20) 会话结束时间 单位毫秒
sType tinyint(4) 会话类型 0：正常会话.1(2)：离线留言，3：排队超时
treatedTime bigint(20) 留言处理时间(如果该会话是留言) 单位毫秒
category varchar(128) 会话末级咨询分类 末级咨询分类名
categoryDetail varchar(128) 会话咨询分类明细 一级分类名/二级分类名/三级分类名/四级分类名/五级分类名
evaluation tinyint(4) 满意度值 2：(100满意; 1不满意);3：(100满意; 50一般; 1不满意);5：(100非常满意; 75满意; 50一般; 25不满意; 1非常不满意)否则未评价
evaluationType bigint(20) 满意度类型
evaluationRemark varchar(255) 满意度评价内容
relatedType tinyint(4) 关联会话类型 0：无关联; 1=从机器人转接过来; 2：机器人会话转接人工; 3：历史会话发起; 4：客服间转接; 5：被接管
relatedId bigint(20) 被关联的会话id 若是无关联则此字段未定义
interaction tinyint(4) 会话交互类型 0：客服正常会话，1：机器人会话，2：呼叫中心会话3=推送消息
closeReason tinyint(4) 会话关闭原因 参照[接收会话结束通知]中的closeReason
fromGroup varchar(255) 会话来自分流组名 或为空
fromGroupId bigint(20) 会话来自分流组id 或为空
fromStaff varchar(255) 会话来自哪个客服 或为空
inQueueTime bigint(20) 排队开始时间点 若<=0忽略此字段
visitRange bigint(20) 与上一次来访的时间差 默认一年(360天),单位毫秒
vipLevel tinyint(4) VIP级别 0=非VIP用户
staffId bigint(20) 客服id <=0 则为机器人
staffName varchar(255) 客服名字 或为"机器人"
userId varchar(255) 访客id
foreignId varchar(255) 外部id 由企业提供
fromIp varchar(64) 访客来源ip 或为空
fromPage varchar(128) 来源页 或为空
fromTitle varchar(128) 来源页标题 或为空
fromType varchar(64) 来源类型 Ios：苹果设备; Android:安卓设备; Web:网页版（含H5）; Wx：微信; wx_ma：微信小程序; Wb：微博; Open:消息接口
customFiled varchar(6000) 自定义字段 所有自定义字段
description varchar(128) 备注 备注
transferRgType varchar(128) 转人工类型 机器人会话转成人工会话的触发原因
fromHumanTransfer tinyint(4) 是否来自客服转接 0：非转接会话；1：客服转接过来的会话
transferFromStaffName varchar(128) 转接来源分流客服名称 转接会话有该字段
transferFromGroup varchar(128) 转接来源分流客服组名称 转接会话有该字段
transferRemarks varchar(2046) 转接来源分流会话备注 转接会话有该字段
humanTransferSessionId bigint(20) 客服转接来源会话ID 如果该会话不是客服转接过来的，该值为null，否则值为转接来源会话的ID
worksheetIds varchar(1000) 会话关联工单id 会话关联工单id, 逗号分隔
roundNumber bigint(20) 会话回合数 会话回合数
status tinyint(4) 客服解决状态 0：未解决，1：已解决，2：解决中
userResolvedStatus tinyint(4) 用户解决状态 0：未选择，1：已解决，2：未解决
firstReplyCost bigint(20) 客服首次响应时长 访客首条消息与客服首次回复消息的时间间隔
avgRespDuration bigint(20) 客服平均响应时长 客服整个会话中的平均响应时长
isValid tinyint(4) 是否是有效会话 0：无效会话，1：有效会话
transferType varchar(128) 转接类型 静默转接/人工转接
staffMessageCount tinyint(4) 客服消息数 客服在整个会话中的消息总量
userMessageCount tinyint(4) 用户消息数 用户在整个会话中的消息总量
overflowFrom varchar(128) 溢出来源 会话溢出的来源客服组

← 企微管理 →