# 通用说明

# 数据校验

七鱼服务器和您的服务器进行数据传递时，POST请求会带以下这些参数：

参数	参数说明
appKey	你的企业的appKey (仅在您的服务器向七鱼服务器发送数据时需要，七鱼服务器向您的服务器发送数据时无此参数)
time	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksum	SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)
eventType	七鱼服务器向开发者服务器推送事件时的事件类型。（开发者服务器向七鱼服务器发送请求时无此参数）

其中，checksum 用于校验数据的完整性，其计算规则中，AppSecret 可在七鱼管理后台->「系统」->「扩展与集成」页面找到，md5 为整个请求 json 字符串的 md5 哈希值（小写形式），即 md5 = MD5(content).toLowwerCase()，如果是上传文件，则是整个文件内容的 md5，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。

计算 checksum 的 Java 示例代码如下：

 public class QiyuPushCheckSum {

    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();
    }
}

# 服务端登录

服务端登录功能可以达到七鱼免登的效果，用于将七鱼客服端作为工具条嵌入第三方网站或者实现第三方认证之后对七鱼进行免登。功能使用步骤拆解:

 步骤1: 向自己服务器端发起异步请求，获取`SDK`地址；
 步骤2: 将SDK地址作为Ifram工具条嵌入第三方页面或者直接跳转新页签实现免登

# 获取`SDK`接入地址

第三方向七鱼请求SDK接入地址的时候，七鱼会执行客服在七鱼的登录事件，并生成含动态口令的SDK接入地址返回给第三方

接口调用及数据校验规则参考上面数据校验

curl请求样例如下：

curl -X POST \
  'http://qiyukf.com/openapi/staff/login?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
  -H 'content-type: application/json;charset=utf-8' \
  -d '{"staffName": "admin"}'

请求参数说明

参数	是否必须	数据类型	参数说明
staffName	是	String	客服在七鱼这边对应的客服名(此处对应的参数值为客服账号)

接口返回数据为JSON格式，最外层参数如下：

参数	参数说明
code	错误码。200表示设置成功。
result	code为200时，返回值有效。
message	请求错误时，填错误提示信息

如果code等于200表示客服登录成功，result内容为json数据，返回样例如下：

{
    "code": 200,
    "message": "",
    "result": {
        "sdk_url": "https://xxx.qiyukf.com/toolbar/script/get?token=cb1ec3c43089493eb4039945685ebf51",
        "corp_code": "xxx",
        "token": "cb1ec3c43089493eb4039945685ebf51"
    }
}

result内的参数说明如下：

参数	数据类型	参数说明
sdk_url	String	生成的含动态登录口令的`SDK`接入地址
corp_code	String	登录客服对应的七鱼企业域名
token	String	动态登录口令

重要提示: 本文档中提供的所有接口均面向开发者服务器端调用，用于计算 checksum 的 AppSecret 开发者应妥善保管,可在应用的服务器端存储和使用，但不应存储或传递到客户端，也不应在网页等前端代码中嵌入。

# 通用错误码列表

错误码	含义
200	OK
14001	参数 appKey 错误
14002	参数 checksum 错误，请重新检查 checksum 计算方式
14003	参数 time 错误，请确保 time 参数与当前时间差小于 5 分钟，或检查服务的时间是否与标准时间同步
14004	内容格式校验错误，请参加详细错误信息，并对照对应的接口文档修正
14008	请求来源 IP 不在被允许的范围内
14009	请求频率过快，超出接口限制
14500	服务器内部错误，请反馈给我们具体场景
14501	数据量过大，超出接口限制
14515	权限不足

← 概述 CRM对接 →

# 通用说明

# 数据校验

# 服务端登录

# 获取SDK接入地址

# 通用错误码列表

# 获取`SDK`接入地址