1 接口规范说明

1.1 API调用说明

本文档中，所有调用IM服务接口的请求都需要按此规则校验，并且遵循如下规则：

1. IM服务端所有接口都只支持POST请求
2. 所有接口返回类型为JSON，同时进行UTF编码
3. 所有接口请求Content-Type类型为：application/x-www-form-urlencoded;charset=utf-8；

1.2 API接口校验

以下参数需要放在`Http Request Header`中，如下表： 

checksum校验和，出于安全性考虑，每个checksum的有效期为5分钟，以timestamp为准，建议每次请求都生成新的checksum,同时请确认发起的服务器是与标准时间NTP同步的。

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

import java.security.MessageDigest;

public class CheckSumBuilder {
    // 计算并获取CheckSum
    public static String getCheckSum(String appSecret, String nonce, String timestamp) {
        return encode("sha1", appSecret + nonce + timestamp);
    }


    // 计算并获取md5值
    public static String getMD5(String requestBody) {
        return encode("md5", requestBody);
    }

    private static String encode(String algorithm, String value) {
        if (value == null) {
            return null;
        }
        try {
            MessageDigest messageDigest
                    = MessageDigest.getInstance(algorithm);
            messageDigest.update(value.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();
    }
    private static final char[] HEX_DIGITS = { '0', '1', '2', '3', '4', '5',
            '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
}

1.3 IM通信ID分配

• app：开发者APP客户端
• appserver: 开发者APP服务端
• IM开发者平台：IM开发者平台服务
• IM服务：SDK直连的IM服务

2. API接口

2.1：创建IM账号

• 接口URL：https://console-sdk.253.com/qfdevelop/sdk/user/v1.0/create.action
• Content-Type: application/x-www-form-urlencoded;charset=utf-8
• 请求头Headers的设置请参考接口规范说明
• 接口描述

1. 第三方账号导入IM平台，注册成功后务必在自身的应用服务器上维护好appUserId和appUserSecret。
2. 注意appUserId的长度以及考虑管理appUserSecret。

参数说明：

• HTTP请求示例(Java)：

import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;

public class Test {
    public static void main(String[] args) throws Exception{
        DefaultHttpClient httpClient = new DefaultHttpClient();
        String url = "https://console-sdk.253.com/qfdevelop/im/user/create.action";
        HttpPost httpPost = new HttpPost(url);

        String appId = "94kid09c9ig9k1loimjg012345123456";
        String appSecret = "123456789012";
        String nonce =  "12345";
        String curTime = String.valueOf((new Date()).getTime() / 1000L);
        String checkSum = CheckSumBuilder.getCheckSum(appSecret, nonce ,curTime);//参考 计算CheckSum的java代码

        // 设置请求的header
        httpPost.addHeader("appId", appId);
        httpPost.addHeader("nonce", nonce);
        httpPost.addHeader("timestamp", curTime);
        httpPost.addHeader("checkSum", checkSum);
        httpPost.addHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");

        // 设置请求的参数
        List<NameValuePair> nvps = new ArrayList<NameValuePair>();
        nvps.add(new BasicNameValuePair("appId", appId));
        nvps.add(new BasicNameValuePair("appUserId", "A-1332467987075"));
        httpPost.setEntity(new UrlEncodedFormEntity(nvps, "utf-8"));

        // 执行请求
        HttpResponse response = httpClient.execute(httpPost);

        // 打印执行结果
        System.out.println(EntityUtils.toString(response.getEntity(), "utf-8"));
    }
}

• 返回说明：

“Content-Type”: “application/json; charset=utf-8”

{
    "code":"0",
    "desc":"success",
    "log_id":"L832939405-29212",
    "result": {
        "appUserId":"C198234AIUDF",
        "appUserSecret":"xxxxxxx",
        "name":"xx"
    }
}

2.2：更新IM账号

• 接口URL：https://console-sdk.253.com/qfdevelop/sdk/usersecret/v1.0/update.action
• Content-Type: application/x-www-form-urlencoded;charset=utf-8
• 请求Headers的设置请参考接口接口规范说明
• 接口描述：更新IM appUserSecret，通过该接口，可以对appUserId更新到指定的appUserSecret，更新后请开发者务必做好本地的维护，更新后，需要客户端SDK再次登录是携带的appUserSecret保持最新。

参数说明：

返回说明：

“Content-Type”: “application/json; charset=utf-8”

返回示例：

{
    "code":"0",
    "desc":"success",
    "log_id":"L832939405-29212",
    "result": {
        "appUserId":"C198234AIUDF",
        "appUserSecret":"xxxxxxx",
        "name":"xx"
    }
}

2.3：封禁IM账号

• 接口URL：https://console-sdk.253.com/qfdevelop/sdk/user/v1.0/freeze.action
• HTTP方法：POST
• 请求Header的设置请参考接口规范说明
• 接口描述：封禁IM账号后，此appUserId将不能再登录，若封禁，该appUserId处于登录状态，则当前登录不影响，仍然可以收发消息，封禁效果会在下次登录生效，因此建议将needKick设置为true，让改账号同时被踢出登录。处于安全目的，账号创建后只能封禁，不能删除，风景后账号仍然计入应用内账号总数。

参数说明：

返回说明：

“Content-Type”: “application/json; charset=utf-8”

返回示例：

{
    "code":"0",
    "desc":"success",
    "log_id":"L832939405-29212",
    "result": {
    }
}

2.4：解禁IM账号

• 接口URL：https://console-sdk.253.com/qfdevelop/sdk/user/v1.0/unfreeze.action
• HTTP方法：POST
• 请求Header的设置参考接口规范说明
• 接口描述：解禁被封禁的IM账号

参数说明：

返回说明：

“Content-Type”: “application/json; charset=utf-8”

返回示例：

{
    "code":"0",
    "desc":"success",
    "log_id":"L832939405-29212",
    "result": {
    }
}