# 通用说明
# 数据校验
七鱼服务器和您的服务器进行数据传递时,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 | 权限不足 |