使用指南 API接口 审核规范
本文档为开发者提供产品接入的开发流程、测试调试、正式接入使用说明。
Account Sid

开发者在云通信平台的唯一标识,在REST请求中使用

开发者账号ID在网站注册后,系统自动生成,不可更改

Auth Token

相当于开发者账号sid(Account Sid)的密码,REST请求中使用

初始的开发者Auth Token在网站注册后,客服会一个工作日内提供或者联系客服人员获取

如果出现开发者Token泄露的情况,系统支持开发者重置Auth Token

AppId

为每个应用分配的唯一标识,在REST请求中使用

每个应用都有相关的能力权限,权限决定了应用可调用的API 能力接口

开发者创建应用后会自动生成appId

云通信开放平台的API是基于HTTP协议来调用的,开发者根据API接口协议来封装HTTP请求进行调用,以下主要是针对封装HTTP请求进行API调用的原理进行详细解说。

根据API接口协议:填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json结果,以下是大体的调用过程示意图:

生产环境:http://api.caihcom.com

请求URL

http://api.caihcom.com/rest/[产品代码]/[版本号]/[服务名]/[方法名]

例子: http://api.caihcom.com/rest/isms/v1/smsService/send

产品代码、版本号、服务名、方法名请参考各业务线API定义。

请求格式
        		
{
     "header": {
        "appkey": "5e32d8403be022f7542555a89b4e9b4b",
        "startTime": "2017-12-18 11:09:41",
        "appId": "99397c9b4e941af5f1051cf3632b5f9c"
    },
    "body": {
        "templateId": "55",
        "templateArgs": ["123"],
        "phones": "15210631938",
        "subcode": "8528",
        "sendtime": "2017-12-18 12:30"
    }
}
        		
        	

说明:

header头中为公共参数,其中appkey对应账户中的account Sid,appId对应使用应用的appId,startTime为请求发送时间(10分钟内请求有效)。

body中为业务参数,请参考api接口进行构造。

http的请求头(header)中需要加入签名认证sign参数,sign生成过程请参考“签名认证章节”

响应格式
        		
{
    "header": {
        "status": 0,  //0: 成功, 1:部分失败  2:全部失败  3:系统错误
        "desc": "success",    //描述
        "errorInfo": {
            "code": 800,
            "message": "系统内部错误"
        },                          
        "total": 2, //操作数据条数
        "succ": 1, //成功操作数据条数
        "optTime": 31 //接口调用消耗时间,单位为毫秒
    },
    "body": [ //具体结果,取决于接口返回数据 ]
}
        		
        	

说明:

header中为请求的调用结果,body中为业务结果

states为0时,不会有errorInfo信息

body返回中不管包含一个对象或多个对象,返回都为数组形式

注意:所有的请求和响应数据编码皆为utf-8格式,所有请求的Content-Type是application/json。

http请求头(header)中增加sign字段传输签名,签名过程如下:

基础参数签名算法

String signText = authToken + requestJson + authToken;

sign = upperCase(toHex(md5(signText)))

authToken是东信开放平台分配给用户的密钥。

requestJson为用户发送的json请求体(注意:json字符串中的json分隔符(,";{}[]等)之间不能留空白)。

md5指通过MD5算法进行加密得到byte数组。

toHex指将byte数组转换成16进制,sign为32位。

upperCase指将字符串全部大写。

生成的sign字符串通过http中header传输。

例子

用户authToken为:be737f12cfdf311ac048efc3f1b94eb1

请求json体为:

        		
{
    "header": {
        "appkey": "6416b416c30b32fb306c26b7c8acbf69",
        "startTime": "2017-03-22 09:37:20",
        "appId":"6416b416c30b32fb306c26b7c8acbf6"
    },
    "body": {
        "msgid": "2c92825934837c4d0134837dcba00150",
        "phones": "18507717847",
        "content": "您好,您的手机验证码为:430237。",
        "sign": "【XXXX】",
        "subcode": "8528",
        "sendtime": "2014-05-05 12:30"
    }
}
        		
        	

则需要进行md5的字符串为:

be737f12cfdf311ac048efc3f1b94eb1{"header":{"appkey":"6416b416c30b32fb306c26b7c8acbf69","startTime":"2017-03-22 09:37:20","appId":"6416b416c30b32fb306c26b7c8acbf6"},"body":{"msgid":"2c92825934837c4d0134837dcba00150","phones":"18507717847","content":"您好,您的手机验证码为:430237。","sign":"【XXXX】","subcode":"8528","sendtime":"2014-05-05 12:30"}}be737f12cfdf311ac048efc3f1b94eb1

则经过upperCase(toHex(md5(signText)))得出的sign为:D03170BA204C72CC84063090F6C92BB9

业务错误码参见各API接口定义,系统错误码定义如下:

800 服务器内部错误
8101 请求url有误,建议检查修正后,重发请求。
8102 请求json解析有误,建议检查修正后,重发请求。
8103 请求appkey为空,建议检查修正后,重发请求。
8104 请求service有误,不存在此service,建议检查修正后,重发请求。
8105 请求appId为空,建议检查修正后,重发请求。
8201 系统内部错误。API服务器系统升级时,或系统问题时会出现此错误。建议等待10分钟后重试。如仍有错误,请反馈给API小组。
8202 系统内部错误。API服务器系统升级时,或系统问题时会出现此错误。建议等待10分钟后重试。如仍有错误,请反馈给API小组。
8203 系统内部错误。API服务器系统升级时,或系统问题时会出现此错误。建议等待10分钟后重试。如仍有错误,请反馈给API小组。
8301 请求appkey为空,建议检查修正后,重发请求。
8302 请求签名为空,建议检查修正后,重发请求。
8303 签名认证失败,建议检查修正后,重发请求。
8304 请求时间为设置,建议检查修正后,重发请求。
8305 请求时间格式有误,建议检查修正后,重发请求。
8306 请求时间超期。
8307 您没有权限访问此业务线API,请先开通权限。
8401 账户余额不足。