二、接口开发
1、接口说明
所有接口采用REST架构风格设计,其核心面向资源,REST对网络应用设计和开发方式,以降低开发的复杂性,提高系统的可伸缩性。
返回报文统一使用JSON,编码为UTF-8。
请会员用户登录到平台,在短信-->账号/签名-->查看指定账号apikey
请求地址: http://IP:port/rcsapi/rest 服务器地址: ip 端口:port
2、鉴权说明
融云平台基于安全考虑,开发者调用融云平台接口采用签名认证进行鉴权。 各接口统一请求URL地址如下:http://IP:Port/rcsapi/rest/xx/xxx.json?sid={sid}&sign={sign}
参数:
sid:账号 sign:签名
签名算法采用md5 32位算法,接口签名的具体要求请查看接口详细描述。建议直接查看demo中的相关源码。
3、账号接口
请求地址: http://IP:Port/rcsapi/rest/user/get.json?sid={sid}&sign={sign} 请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sid | 字符型 | 必填 | 账号 |
sign | 字符型 | 必填 | 签名认证 Md5(sid+apikey) |
响应参数:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
user | ||
username | 账号 | |
balance | 余额 | |
unit | 计量单位 | |
warnBalance | 预警余额 | |
isActive | 是否可用 | True-可用,false-禁用 |
apikey | 接入apikey | 为了账号安全,暂时不开放,为空 |
Ip | 报备ip | |
signature | 短信签名 | 如:【美圣融云】 |
remark | 备注 | |
speed | 速率 | |
subcode | 扩展码 |
响应成功Json报文示例:
{ "code": "0", "msg": "成功", "detail": "", "user": { "username": "ZH00000017", "balance": "3487", "unit": "条", "warnBalance": "56", "isActive": true, "apikey": "83a4943c-6739-4556-9ac4-08528082eefb", "ip": "", "signature": "【美圣融云】", "remark": "租赁", "speed": "10", "subcode": "260425" } }
响应失败Json报文示例:
{ "code": "1005", "msg": "请求认证失败", "detail": "请求认证失败" }
4、模板接口
4.1、查询账号所有模板
1、请求地址:http://IP:Port/rcsapi/rest/tpl/gets.json?sid={sid}&sign={sign}&pageindex={pageindex}&pagesize={pagesize} 2、请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sid | 字符型 | 必填 | 账号 |
sign | 字符型 | 必填 | 签名认证md5(sid+apikey) |
pageindex | 数字型 | 可选 | 默认:0 |
pagesize | 数字型 | 可选 | 默认:100,取值范围:0~100 |
成功响应参数:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
count | 模板数量 | |
tpls | ||
Id | 模板id | |
name | 模板名称 | |
content | 模板内容 | |
remark | 备注 | |
state | 审核状态 | 0-退回;1-通过;2-审核 |
isActive | 是否可用 | True-可用,false-禁用 |
响应成功json报文示例:
{ "code": "0", "msg": "成功", "detail": "", "count": "3", "tpls": [{ "id": "b6d46de1c9c94c0eaa2bba74213feea5", "name": "注册验证码", "content": "您好,欢迎注册,您的短信验证码是:@1@, 请尽快完成注册。", "remark": "", "state": "1", "isActive": true },{ "id": "6e173b50a5a34b1989a02e31f05deb0e", "name": "注册模板", "content": "您好@1@,欢迎使用@2@,后续咨询请关注@3@.", "remark": "", "state": "1", "isActive": true },{ "id": "f74b9c6ec4344da3878e80e17c9ac927", "name": "OA提醒", "content": "@1@你好,系统中有新问题需处理,请及时查收并处理。", "remark": "", "state": "1", "isActive": true }] }
响应失败Json报文示例:
{ "code": "1005", "msg": "请求认证失败", "detail": "请求认证失败" }
4.2、查询单个模板
1、请求地址:/tpl/get.json?sid={sid}&sign={sign}&tplid={tplid} 2、请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sid | 字符型 | 必填 | 账号 |
sign | 字符型 | 必填 | Md5(sid+apikey+tplid) |
tplid | 字符型 | 必填 | 模板id |
响应参数说明:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
tpl | ||
Id | 模板id | |
name | 模板名称 | |
content | 模板内容 | |
remark | 备注 | |
state | 审核状态 | 0-退回 1-通过 2-审核 |
isActive | 是否可用 | True-可用,false-禁用 |
响应成功Json报文示例:
{ "code": "0", "msg": "成功", "detail": "", "tpl": { "id": "6e173b50a5a34b1989a02e31f05deb0e", "name": "注册模板", "content": "您好@1@,欢迎使用@2@,后续咨询请关注@3@.", "remark": "", "state": "1", "isActive": true } }
响应失败Json报文示例:
{ "code": "1014", "msg": "未找到对应id模板", "detail": "881b3028fe1e462aab5f28b271ccebb11模板不存在", }
5、模板短信接口
1、请求地址:http://IP:Port/rcsapi/rest/sms/sendtplsms.json 2、请求方式:POST
请求Header:
属性 | 值 | 约束 |
---|---|---|
Content-Type | application/x-www-form-urlencoded | 必填 |
Content-Encoding | utf-8 | 必填 |
请求Body:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sign | 字符型 | 必填 |
签名认证:
md5(sid+apikey+tplid+mobile+content)
content中含有中文字符,需要gb2312或utf-8转码
|
sid | 字符型 | 必填 | 账号 |
tplid | 字符型 | 必填 | 模板ID |
mobile | 字符型 | 必填 | 手机号码,只支持一个11位的手机号 |
content | 字符型 | 必填 | 参数值,多个参数以“||”隔开 如:@1@=HY001||@2@=3281 |
extno | 字符串 | 可选 | 自定义扩展码,建议1-4位,需此功能请联系客服申请开通,取值范围:0-9999 |
成功响应参数
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
sm | ||
count | 发送次数 | 短信发送次数 |
fee | 计费条数 | 70字一条,超过70字按67个字一条。 |
apid | 消息ID | 对应状态报告apid |
响应成功JSON报文示例:
{ "code": "0", "msg": "成功", "detail": "", "sm": { "count": "1", "fee": "1", "apid": "mOlyQ2ifS8WhsZGExkimrw" } }
响应失败JSON报文示例:
{ "code": "1005", "msg": "请求认证失败", "detail": "请求认证失败" }
6、状态接口
每次请求只能获取未被获取过的短信状态报告,已获取的报告不会重复获取;单次请求最多获取10000条状态报告记录。
1、请求地址:http://IP:Port/rcsapi/rest/sms/queryrpt.json?sid={sid}&sign={sign} 2、请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sid | 字符型 | 必填 | 账号 |
sign | 字符型 | 必填 | 签名认证Md5(sid+apikey) |
响应参数说明:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
count | 记录数 | |
rpts | ||
apid | 消息id | 对于发送apid |
subcode | 扩展码 | |
mobile | 手机号码 | |
stat | 状态 | |
sendtime | 发送时间 | |
rpttime | 报告时间 |
响应成功JSON报文示例:
{ "code": "0", "msg": "成功", "detail": "", "count": "2", "rpts": [{ "apid": "4CZb93B-RNux4CrvyLwUXQ", "subcode": "260424", "rpttime": "2016-03-11 10:13:07", "sendtime": "2016-03-11 10:12:40", "stat": "DELIVRD", "mobile": "15951970000" },{ "apid": "Bf84qC4_R3WB7Ddd8huCNQ", "subcode": "260424", "rpttime": "2016-03-11 10:13:14", "sendtime": "2016-03-11 10:12:48", "stat": "DELIVRD", "mobile": "15951970001" }] }
7、上行接口
每次请求只能获取未被获取过的上行短信,已获取的上行短信不会重复获取;单次请求最多获取10000条上行短信记录
1、请求地址:http://IP:Port/rcsapi/rest/sms/querymo.json?sid={sid}&sign={sign} 2、请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sign | 字符型 | 必填 | 签名认证Md5(sid+apikey) |
sid | 字符型 | 必填 | 账号 |
成功响应参数:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
count | 记录数 | |
mos | ||
mobile | 手机号码 | |
spcode | 接收号码 | |
content | 上行内容 | |
time | 上行时间 |
响应成功JSON报文示例:
{ "code": "0", "msg": "成功", "detail": "", "count": "2", "mos": [{ "content": "江苏美圣信息技术有限公司", "time": "2016-03-11 10:19:11", "spcode": "1069079127260424", "mobile": "15951977097" },{ "content": "10690599", "time": "2016-03-11 10:19:20", "spcode": "1069079127260424", "mobile": "15951977097" }] }
8、检测黑名单
1、请求地址:http://IP:Port/rcsapi/rest/assist/bl.json?sid={sid}&sign={sign}&mobile={mobile} 2、请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sid | 字符型 | 必填 | 账号 |
sign | 字符型 | 必填 | 签名认证Md5(sid+apikey) |
mobile | 字符型 | 必填 | 手机号码 |
成功响应参数:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | |
msg | 消息 | |
detail | 详细描述 | |
mobile | 手机号码 | |
flag | 标记 | True-是黑名单 false-非黑名单 |
响应成功json报文示例:
{ "code": "0", "msg": "成功", "mobile": "15951977097", "detail": "", "flag": false }
响应失败JSON报文示例:
{ "code": "1005", "msg": "请求认证失败", "detail": "请求认证失败" }
9、检测敏感词
1、请求地址:http://IP:Port/rcsapi/rest/assist/sw.json?sid={sid}&sign={sign}&content={content} 2、请求方式:GET
参数说明:
参数名 | 类型 | 约束 | 描述 |
---|---|---|---|
sid | 字符型 | 必填 | 账号 |
sign | 字符型 | 必填 | 签名认证Md5(sid+apikey) |
content | 字符型 | 必填 | 待检测内容 |
响应参数说明:
参数名 | 名称 | 说明 |
---|---|---|
code | 返回码 | 待检测内容 |
msg | 消息 | |
detail | 详细描述 | |
words | 敏感词 | 多个敏感词以逗号隔开 |
响应成功JSON报文示例:
{ "code": "0", "msg": "成功", "detail": "", "words": "促销,枪支" }
响应失败JSON报文示例:
{ "code": "1005", "msg": "请求认证失败", "detail": "请求认证失败" }