1、发送短信接口
注意事项
- 号码格式：国家代码+正确的手机号码。例如中国：8617321342252
- 国际接口支持国际国内发送，默认关闭，需要发国内权限找对应商务申请开通，号码加中国代码：+86，并且内容一定要加签名，内容一定要报备。发送国外无需报备，签名不限制。签名最好以【253 云通讯】为格式例子。
- 发国外营销短信最好用英文或者当地语言，需要中文发送的话请联系商务确认你要发送的国家运营商是否支持中文。
- 短信收到慢，或者收不到请联系对应商务或者客服，一般是号码格式错误，内容触发审核，或者国内号码黑名单。
1.1加签方式
- 将请求头参数名 nonce 及所有请求体参数名（key）以 ASCII 码表顺序升序排列；
- 排序后把参数值非空的参数名（key）参数值（value）依次进行字符串拼接，拼接处不包含其他字符；
- 拼接成包含 kv 的长串后，在该长串的尾部拼接账号的 password，得到签名字符串的组装；
- 最后对签名字符串，使用 MD5 算法加密后，得到 MD5 加密密文后转为小写，即为请求头 sign 值
加签代码示例
package com.angi;
import com.alibaba.fastjson.JSONObject;
import org.apache.commons.lang3.StringUtils;
import org.springframework.util.DigestUtils;
import java.util.Map;
import java.util.TreeMap;
/**
-
参数进行加签验签
*/
public class SignUtil {
private static final String SIGN = "sign";
/**
- 发送加签
*/
public static String sendSign(String password, TreeMap<String, String> paramMap) {
paramMap.remove(SIGN);
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> entry : paramMap.entrySet()) {
if (StringUtils.isNotBlank(entry.getValue())) {
sb.append(entry.getKey());
sb.append(entry.getValue());
}
}
return DigestUtils.md5DigestAsHex((sb.toString() + password).getBytes()).toLowerCase();
}
/**
- 发送验签
*/
public static boolean verifySendSign(String password, TreeMap<String, String> paramMap) {
String sign = paramMap.remove(SIGN);
String computed = sendSign(password, paramMap);
return StringUtils.equals(sign, computed);
}
public static void main(String[] args) {
/*发送加签验签/
String password = "4Z7bMS1eLI6895";
TreeMap<String, String> paramMap = new TreeMap<>();
paramMap.put("nonce", "222222");
paramMap.put("account", "IM6742671");
paramMap.put("mobile", "8618916198813");
paramMap.put("msg", "test 666661 ");
System.out.println(JSONObject.toJSONString(paramMap));
String sign = sendSign(password, paramMap);
System.out.println(sign);
TreeMap<String, String> newParamMap = new TreeMap<>(paramMap);
newParamMap.put(SIGN, sign);
boolean validate = verifySendSign(password, newParamMap);
System.out.println(validate);
}
}
2.2协议说明
2.3请求头
| 名称 | 类型 | 是否必填 | 示例 | 说明 |
|---|
| sign | string | 是 | 1234abcd7890qwer | 签名，请参照加签方式生成签名 |
| nonce | string | 是 | 1653043349000 | 时间戳 |
2.4请求体
| 名称 | 类型 | 是否必填 | 示例 | 说明 |
|---|
| account | string | 是 | I6000000 | API 账号，50 位以内 |
| mobile | string | 是 | 8615800000000 | 手机号码，格式(区号+手机号码)，例如：8615800000000，其中 86 为中国的区号， 区号前不使用 00 开头,15800000000 为接收短信的真实手机号码。5-20 位 |
| msg | string | 是 | 【253】Your verification code is：2530 | 短信内容。长度不能超过 2000 个字符 |
| senderId | string | 否 | SENDER0 | 用户收到短信之后显示的发件人，国内不支持自定义，国外支持，但是需要提前和运营商沟通注册，具体请与 TIG 对接人员确定 |
| uid | string | 否 | 123456 | 客户自定义批次号，64 字以内 |
| tdFlag | int | 否 | 1 | 退订开启标识，1 开启；0 或 null 关闭 |
2.5响应
| 名称 | 类型 | 示例 | 说明 |
|---|
| code | string | 0 | 状态码: 0-成功,非 0 标识失败 |
| message | string | 提交成功 | 状态码说明 |
| data | string | null | 消息体 |
返回示例-成功
{
"code": "0",
"message": "提交成功",
"data": {
"messageId": "162575412960104448"
}
}
注：code 为响应状态码，可参照提交响应状态码对比
2、推送状态报告
推送明细说明
请求方式：采用 get 传参
请求协议：http/https（客户方提供）
编码格式：utf-8
功能说明：此接口默认开通，回送地址服务器需要启动一个 http 服务用于接收状态报告。用户在收到状态报告后需要自己写个方法去做处理收到的参数。
推送状态报告
功能说明：该功能是我们为您实时推送的状态报告。您需要提供一个 url 地址，接受 httpget 请求。运营商返回状态之后，我们会即时将状态推送到您配置的接收地址上。
请求
该地址需要贵司服务器端配置一个我司可以访问的地址用来接收状态
访问方式：get
推送参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|
| receiver | string | 是 | 接收验证的用户名，配置时不填写则为空，如需配置请联系技术 |
| pswd | string | 是 | 接收验证的密码，配置时不填写则为空，如需配置请联系技术 |
| msgid | string | 是 | 提交短信时平台返回的 msgid |
| reportTime | string | 是 | 格式 YYMMDDhhmm，其中 YY=年份的最后两位（00-99），MM=月份（01-12），DD=日（01-31），hh=小时（00-23），mm=分钟（00-59）网关平台返回的时间 有时差 |
| mobile | string | 是 | 提交短信时的手机号码 |
| status | string | 是 | 状态字符串 具体含义参见状态报告状态码 |
推送示例
备注
处理成功请返回字符串"OK"，其他返回值将被认为是失败。该接口失败会重推，次数为 3 次，每次间隔 1 分钟。
3、推送上行明细
功能说明：该功能是我们为您实时推送用户回复的内容。您需要提供一个 url 地址，接受 httpget 请求。运营商将上行内容推送到我们平台之后，我们会即时推送到您配置的接收地址上。
请求
该地址需要贵司服务器端配置一个我司可以访问的地址用来接收上行
访问方式：get
推送参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|
| receiver | string | 是 | 接收状态报告验证的用户名（不是账户名），是按照用户要求配置的名称，默认为空 |
| pswd | string | 是 | 接收状态报告验证的密码，默认为空 |
| moTime | string | 是 | 格式 YYMMDDhhmm，其中 YY=年份的最后两位（00-99），MM=月份（01-12），DD=日（01-31），hh=小时（00-23），mm=分钟（00-59） |
| mobile | string | 是 | 单一的手机号码 |
| msg | string | 是 | MO 短信内容，文字内容使用 UTF-8 编码 |
| destcode | string | 是 | 用户上行的目的号码 |
推送示例
备注
1、pushMoUrl 为用户启动的服务地址。
2、需要发送短信的服务器起一个 http 服务，和服务器的 IP 地址组成一个接收地址，能够让 253 的服务器访问到客户的服务器。状态报告实现原理：客户通过对应接入号编辑发送短信内容，如编辑短信：你好---->到对应接入号--->运营商--->253 服务器-->接收地址。
在收到短信上行后需要自己写个方法去做处理收到的参数。
3、由于国家运营商的规则不同，部分国家不支持上行，详情请咨询对接商务。
4、拉取状态报告
拉取明细说明
功能说明：开通此接口功能后，数据拉取成功后服务器会删除当前拉取成功的数据，不再保存！请妥善处理接口返回的数据。此状态报告保存时间为 72 小时，上限存储 10 万条。
备注：该接口默认不开放，联系运营人员开启
拉取状态报告
功能说明：开通此接口功能后，数据拉取成功后服务器会删除当前拉取成功的数据，不再保存！请用户及时存储。此状态报告保存时间为 72 小时，上限存储 10 万条。
备注：该接口默认不开放，联系运营开启。
请求
请求方式：json 格式封装的字符串，采用 post 方式提交请求
请求协议：http，https
编码格式：utf-8
Content-Type：application/json
请求参数
| 参数名 | 类型 | 是否必须 | 描述 | 示例 |
|---|
| account | string | 是 | API 账号 | "account":"I9000001" |
| password | string | 是 | API 密码 | "password":"ABCdef15301" |
| count | String | 否 | 拉取个数（上限 100，默认 20） | "count":"20" |
请求格式
{
"account":"I6000001",
"password":"123456",
"count":"20"
}
响应参数
| 参数名 | 类型 | 描述 | 示例 |
|---|
| result | string | 状态明细结果，没结果则返回空数组 | "result":[{ XXX：XXX }] |
| notifyTime | string | 253 平台收到运营商回复状态报告的时间，格式 yyMMddHHmmss | "notifyTime":"180522104730" |
| mobile | string | 接收短信的手机号码 | "mobile":"15744444444" |
| msgid | string | 消息 id | "msgid":"18052210472127924" |
| reportTime | string | 状态更新时间，格式 yyMMddHHmm，其中 yy=年份的最后两位（00-99） | "reportTime":"1805221047" |
| status | string | 运营商返回的状态（详细参考常见常见状态报告状态码） | "status":"DELIVRD" |
响应示例
{
"result":[
{
"notifyTime":"181114181739",
"mobile":"8618338779986",
"msgid":"18111418171006662505",
"reportTime":"1811141817",
"status":"DELIVRD"
}
],
"code":0,
"error":""
}
5、拉取上行明细
功能说明：开通此接口功能后，数据拉取成功后服务器会删除当前拉取成功的数据，不再保存！请妥善处理接口返回的数据。此状态报告保存时间为 72 小时，上限存储 10 万条。
备注：该接口默认不开放，联系运营人员开启。
请求
请求方式：json 格式封装的字符串，采用 post 方式提交请求
请求协议：http，https
编码格式：utf-8
Content-Type：application/json
请求参数
| 参数名 | 类型 | 是否必须 | 描述 | 示例 |
|---|
| account | string | 是 | API 账号 | "account":"I6000001" |
| password | string | 是 | API 密码 | "password":"ABCdef15301" |
| count | integer | 否 | 拉取个数（上限 100，默认 20） | "count":"20" |
请求格式
{
"account":"I6000001",
"password":"123456",
"count":"20"
}
响应参数
| 参数名 | 类型 | 描述 | 示例 |
|---|
| result | string | 上行明细结果，没结果则返回空数组 | "result":[{XXX}] |
| destCode | string | 通道码 | "destCode":"106598054231708616" |
| mobile | string | 上行手机号码 | "mobile":"106598054231708616" |
| moTime | string | 上行时间，格式 yyMMddHHmm，其中 yy=年份的最后两位（00-99） | "moTime":"1805221048" |
| msg | string | 上行内容 | "msg":"您好" |
响应示例
{
"result":[
{
"msg":"您好",
"destcode":"1864342",
"mobile":"8618600000000",
"moTime":"1542184275967"
}
],
"code":0,
"error":""
}
返回码说明
返回码总体说明
code = 0:正确返回，提交成功。
code > 0&code<=133:调用 API 时发生错误，根据不同返回值
找到问题处理人（开发者，技术支持，客服，商务）进行相应的处理。
返回值示例
| 参数名 | 类型 | 描述 | 示例 |
|---|
| code | String | 状态码 | 0 |
| msgId | String | 消息 id | 17041010383624511 |
| time | String | 响应时间 | 20170410103836 |
| errorMsg | String | 状态码说明（成功返回空） | 无此用户 |
API 调用成功，返回成功结果示例：
{
"code":"0",
"msgId":"17041010383624511",
"time":"20170410103836",
"errorMsg":""
}
API 调用失败，返回错误结果示例：
{
"code":"101",
"msgId":"",
"time":"20170410103836",
"errorMsg":"无此用户"
}
6、余额查询接口
6.1 协议说明
注;请根据账号所在节点请求对应URL，否则查询的余额不准确。
6.2 请求包体为json字符串，参数如下：
| 参数名 | 类型 | 是否必须 | 描述 | 示例 |
|---|
| account | string | 是 | API 账号 | "account":"I9000001" |
| password | string | 是 | API 密码 | "password":"ABCdef15301" |
6.3 返回示例
{
"code": "0",//状态码
"error": "",//状态码说明（成功返回空字符串）
"balance": "7.298" //剩余可用余额，保留三位小数点
}
接口响应码
| 状态码 | 描述 |
|---|
| 0 | 提交成功 |
| 101 | 账号不存在 |
| 102 | 密码错误 |
| 103 | 拉取条数格式错误 |
| 104 | 拉取条数不在范围内 |
| 105 | 批次编号大于128位 |
| 106 | 短信内容长度错误(>3000) |
| 108 | 手机号码格式错误(>20或<5) |
| 109 | 手机号码个数错误 |
| 110 | 余额不足 |
| 112 | 产品配置错误 |
| 114 | 请求ip和绑定ip不一致 |
| 115 | 没有开通国内短信权限 |
| 116 | 账号已删除或禁用 |
| 117 | 接入号长度超过20位 |
| 119 | 账号不在当前节点 |
| 123 | 短信内容不能为空 |
| 124 | 简介或验证码不能为空 |
| 125 | 特定客户手机号码同一天不能超过十次 |
| 126 | 定时短信发送时间不能为空 |
| 126 | 定时短信发送时间错误 |
| 128 | 账号长度错误(>50或<=0) |
| 129 | 产品价格配置错误 |
| 130 | 未知异常 |
| 131 | 超过日发送上限 |
| 132 | 超过月发送上限 |
| 133 | 超过发送上限 |
| 134 | 超过反投诉限制 |
| 135 | 变量数量不符 |
| 135 | 短信内容不匹配 |
状态报告状态码
| 状态码 | 描述 |
|---|
| DELIVRD | 短信发送成功 |
| UNKNOWN | 未知短信状态 |
| REJECTD | 短信被短信中心拒绝 |
| MBBLACK | 目的号码是黑名单号码 |
| SM11 | 网关验证号码格式错误 |
| SM12 | 我方验证号码格式错误 |
| 其他 | 网关内部状态 |
计费规则说明
1.国际短信不支持 emoji 表情
2.编辑器中空格都会以”."表示，如出现不带”.”的空格则说明有隐藏代码，会导致 1 条短信算成 2 条的风险请留意。
3.国际号码必须添加对应国家的区域号，例如中国号码 86138****1234，86 为中国区号。
4.发送中国号码殷时，短信内容必须以[签名]开头，然名内容为: 公司或品牌名称，字数要求 2-80 个字符，运营商规定必填。
5.发送中国号码段时，内客合法，不能发送房产、发票、移民等国家法律法规严格禁止的内容。
6.超链接地址请写在短信内容中，便于核实，部分安卓系统存在超链接识别问题，需在超链接前后添加空
格。
7.短信中含非英文字符按中文计费。
对接回填率
1.什么是回填率
指验证码短信下发至用户手机端后，用户实际填写验证码的比率，是衡量短信通道质量的重要指标。
2.对接回填率有什么好处
便于我们实时监控您的短信真实发送效果，当发送效果出现下滑情况，我们可以为您切换到更优质的通道。
3.回填率接口文档
请求示例:
请求方法：post
参数格式:json
参数:{
"phone":"8611111111111",
"time":1634006690,
"messageId":"141615506720432128"，
"account":"xxx",
"countryNum":"86"
}
没有更多了
