短信开发文档
1. 引言
本文档主要提供短信平台对用户开放的主要接口和定义说明。
2. 短信接口
注：终端客户的接入方式设置为http接入时才能使用此接口。
以下http://xxx/msg/send/json 或者https://xxx/msg/send/json请求地址不完整， 请登录253云通讯自助通平台或者询问您的商务负责人获取。
该接口数据请求和响应返回均采用json格式封装的字符串，编码（对整个请求的字符串编码）统一为UTF-8，采用post方式提交请求。
2.1 短信下发
名称 |
说明 |
协议 |
HTTP |
提交方式 |
只支持POST |
编码格式 |
UTF-8 |
Content-Type |
application/json |
http地址 |
http://xxx/msg/send/json |
https地址（更安全） |
https://xxx/msg/send/json |
说明 |
此接口可以提交不超过50000个手机号码，每个号码用英文逗号间隔。 |
请求说明 |
以下json内容为提交请求格式： {"account":"N6000001", "password":"123456", "msg":"【253】您的验证码是：2530", "phone":"15800000000", "sendtime":"201704101400", "report":"true", "extend":"555", "uid":"321abc" } 字段说明 account：用户账号，必填 password：用户密码，必填 msg：短信内容。长度不能超过536个字符，必填 phone：手机号码。多个手机号码使用英文逗号分隔，必填 sendtime：定时发送短信时间。格式为yyyyMMddHHmm，值小于或等于当前时间则立即发送，默认立即发送，选填 report：是否需要状态报告（默认false），选填 extend：下发短信号码扩展码，纯数字，建议1-3位，选填 uid：该条短信在您业务系统内的ID，如订单号或者短信发送记录流水号，选填 |
响应说明 |
该响应为提交响应，发送到手机是否成功请获取状态报告确认 响应数据格式： {"time":"20170410103836", "msgId":"17041010383624511", "errorMsg":"", "code":"0" } 字段说明： time：响应时间 msgId：消息id errorMsg：状态码说明（成功返回空） code：状态码（详细参考提交响应状态码）
|
2.2 变量短信
名称 |
说明 |
协议 |
HTTP |
提交方式 |
只支持POST |
编码格式 |
UTF-8 |
Content-Type |
application/json |
http地址 |
http://xxx/msg/variable/json |
https地址（更安全） |
https://xxx/msg/variable/json |
说明 |
msg字段中最多支持20个变量{$var}。 params字段最多不能超过1000个参数组。 格式不符的参数，系统自动会过滤掉。 |
请求说明 |
以下json内容为提交请求格式： {"account":"N6000001", "password":"123456", "msg":"【253】您的验证码是：{$var}", "params":"15800000000,1234;13800000000,4321", "sendtime":"201704101400", "report":"true", "extend":"555", "uid":"321abc" } 字段说明 account：用户账号，必填 password：用户密码，必填 msg：短信内容。长度不能超过536个字符，必填 params：手机号码和变量参数，多组参数使用英文分号;区分，必填 sendtime：定时发送短信时间。格式为yyyyMMddHHmm，值小于或等于当前时间则立即发送，默认立即发送，选填 report：是否需要状态报告（默认false），选填 extend：下发短信号码扩展码，纯数字，建议1-3位，选填 uid：该条短信在您业务系统内的ID，如订单号或者短信发送记录流水号，选填 |
响应说明 |
该响应为提交响应，发送到手机是否成功请获取状态报告确认 响应数据格式： {"failNum":"0", "time":"20170410103836", "successNum":"1", "msgId":"17041010383624511", "errorMsg":"", "code":"0" } 字段说明： failNum：失败条数 time：响应时间 successNum：成功条数 msgId：消息id errorMsg：状态码说明（成功返回空） code：状态码（详细参考提交响应状态码）
|
2.3 查询余额
名称 |
说明 |
协议 |
HTTP |
提交方式 |
只支持POST |
编码格式 |
UTF-8 |
Content-Type |
application/json |
http地址 |
http://xxx/msg/balance/json |
https地址（更安全） |
https://xxx/msg/balance/json |
说明 |
查询当前账号可用余额 |
请求说明 |
以下json内容为提交请求格式： {"account":"N6000001", "password":"123456" } 字段说明 account：用户账号，必填 password：用户密码，必填 |
响应说明 |
成功响应数据格式： {"balance":"2530", "time":"20170410103836", "errorMsg":"", "code":0 } 字段说明： code：状态码（详细参考提交响应状态码） balance：剩余可用余额条数 errorMsg：状态码说明（成功返回空） time：响应时间
失败响应数据格式： {"time":"20170410103836", "msgId":"", "errorMsg":"请求参数错误", "code":"130" } |
2.4 回送上行明细
名称 |
说明 |
推送协议 |
HTTP |
推送方式 |
GET |
说明 |
如果用户需要主动推送上行短信，那需要管理员设置用户账号为需要回送上行短信，并且配置上行短信的回送地址。回送地址服务器需要启动一个http服务用于接收上行短信。用户在收到上行短信后需要自己写个方法去做处理收到的参数。 |
示例说明 |
比如用户账户设置的上行短信回送地址为：http://client_url，那么当253平台收到运营商回送的上行短信后便会以get请求访问以下url： http://client_url?receiver=admin&pswd=12345&moTime=1704142009&mobile=15201810385&msg=收到&destcode=106905841963717198&spCode=1069058419637171¬ifyTime=170414200957 字段说明 client_IP:PORT:客户自己绑定的回送地址 receiver：接收验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空 pswd：接收验证的密码，可以为空 moTime：上行时间，格式yyMMddHHmm，其中yy=年份的最后两位（00-99） mobile：上行手机号码 msg：上行内容，内容经过URLEncode编码(UTF-8) destcode：运营商通道码 spCode：平台通道码 notifyTime：253平台收到运营商回复上行短信的时间，格式yyyyMMDDhhmmss isems：是否为长短信的一部分，1:是，0，不是。不带该参数，默认为普通短信 emshead：isems为1时，本参数以ASCII码形式显示长短信的头信息。用“,”隔开，分为三个部分，第一部分标识该条长短信的ID（该ID为短信中心生成）；第二部分，表明该长短信的总条数（pk_total）；第三部分，该条短信为该长短信的第几条(pk_number)。 例如：234,4,1，该短信的ID为234,该长短信的总长度为4条，1，当前为第一条。 |
2.5 拉取上行明细
名称 |
说明 |
协议 |
HTTP |
提交方式 |
只支持POST |
编码格式 |
UTF-8 |
Content-Type |
application/json |
http地址 |
http://xxx/msg/pull/mo |
https地址（更安全） |
https://xxx/msg/pull/mo |
说明 |
如果管理员设置用户账号需要主动拉取，则用户可以通过上面的URL拉取其发送短信的上行明细。数据拉取成功后服务器会删除当前拉取成功的数据，不再保存！请用户及时存储。此状态报告保存时间为72小时，最大存储10万条。 |
请求说明 |
以下json内容为提交请求格式： {"account":"N6000001", "password":"123456", "count":"20" } 字段说明 account：用户账号，必填 password：用户密码，必填 count：拉取个数（最大100，默认20），选填 |
响应说明 |
响应数据格式： {"ret": 0, "result": [{ "spCode": "1069058419637252493", "moTime": "1704151325", "messageContent": "短信收到谢谢！", "destCode": "1069058419637252493", "mobile": "15821842837" }]} 字段说明： ret：请求状态。0成功，其他状态为失败 result：上行明细结果，没结果则返回空数组 spCode：平台通道码 moTime：上行时间，格式yyMMddHHmm，其中yy=年份的最后两位（00-99） messageContent：上行内容 descCode：运营商通道码 mobile：上行手机号码
失败响应数据格式： {"ret": 1, "error":"账号和密码不能为空" } error：请求错误描述 |
2.6 回送状态报告
名称 |
说明 |
推送协议 |
HTTP |
推送方式 |
GET |
说明 |
如果用户需要主动推送发送短信的状态报告，那需要管理员设置用户账号为需要回送状态报告，并且配置状态报告的回送地址。回送地址服务器需要启动一个http服务用于接收状态报告。用户在收到状态报告后需要自己写个方法去做处理收到的参数。 |
示例说明 |
比如用户账户设置的状态报告回送地址为：http://sms.253.com/msg_report/callback，那么当253平台收到运营商回送的状态报告后便会以get请求访问以下url： http://client_url?receiver=admin&pswd=12345&msgid=17041010383624511&reportTime=1704101038&mobile=15700000004¬ifyTime=170410103838&uid=17041010383624511&status=DELIVRD&statusDesc=短信发送成功 字段说明 receiver：接收验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空 pswd：接收验证的密码，可以为空 msgid：消息id reportTime：运营商返回的状态更新时间，格式YYMMddHHmm，其中YY=年份的最后两位（00-99） mobile：接收短信的手机号码 notifyTime：253平台收到运营商回复状态报告的时间，格式yyyyMMddHHmmss uid：用户在提交该短信时提交的uid参数，未提交则无该参数 status：状态（详细参考常见常见状态报告状态码） statusDesc：状态说明，内容经过URLEncode编码(UTF-8) |
2.7 拉取状态报告
名称 |
说明 |
协议 |
HTTP |
提交方式 |
只支持POST |
编码格式 |
UTF-8 |
Content-Type |
application/json |
http地址 |
http://xxx/msg/pull/report |
https地址（更安全） |
https://xxx/msg/pull/report |
说明 |
如果管理员设置用户账号需要主动拉取，则用户可以通过上面的URL拉取其发送短信的状态报告。数据拉取成功后服务器会删除当前拉取成功的数据，不再保存！请用户及时存储。此状态报告保存时间为72小时，最大存储10万条。 |
请求说明 |
以下json内容为提交请求格式： {"account":"N6000001", "password":"123456", "count":"20" } 字段说明 account：用户账号，必填 password：用户密码，必填 count：拉取个数（最大100，默认20），选填 |
响应说明 |
响应数据格式： {"ret": 0, "result": [{ "uid":"17041010383624511", "reportTime":"1704261558", "notifyTime":"170426155812"， "status":"DELIVRD", "msgId":"17041010383624511", "statusDesc":"用户短信接收成功", "mobile":"15700000004" }]} 字段说明： ret：请求状态。0成功，其他状态为失败 result：状态明细结果，没结果则返回空数组 uid：用户在提交该短信时提交的uid参数，未提交则无该参数 reportTime：状态更新时间，格式yyMMddHHmm，其中yy=年份的最后两位（00-99） notifyTime：253平台收到运营商回复状态报告的时间，格式yyyyMMddHHmmss status：状态（详细参考常见常见状态报告状态码） msgId：消息id statusDesc：状态说明 mobile：接收短信的手机号码
失败响应数据格式： {"ret": 1, "error":"账号和密码不能为空" } error：请求错误描述 |
3. 短信状态码
3.1 提交响应状态码
状态码 |
描述 |
0 |
提交成功 |
101 |
无此用户 |
102 |
密码错 |
103 |
提交过快（提交速度超过流速限制） |
104 |
系统忙（因平台侧原因，暂时无法处理提交的短信） |
105 |
敏感短信（短信内容包含敏感词） |
106 |
消息长度错（>536或<=0） |
107 |
包含错误的手机号码 |
108 |
手机号码个数错（群发>50000或<=0） |
109 |
无发送额度（该用户可用短信数已使用完） |
110 |
不在发送时间内 |
113 |
扩展码格式错（非数字或者长度不对） |
114 |
可用参数组个数错误（小于最小设定值或者大于1000）;变量参数组大于20个 |
116 |
签名不合法或未带签名（用户必须带签名的前提下） |
117 |
IP地址认证错,请求调用的IP地址不是系统登记的IP地址 |
118 |
用户没有相应的发送权限（账号被禁止发送） |
119 |
用户已过期 |
120 |
违反防盗用策略(日发送限制) |
123 |
发送类型错误 |
124 |
白模板匹配错误 |
125 |
匹配驳回模板，提交失败 |
127 |
定时发送时间格式错误 |
128 |
内容编码失败 |
129 |
JSON格式错误 |
130 |
请求参数错误（缺少必填参数） |
3.2 常见状态报告状态码
状态码 |
描述 |
DELIVRD |
短信发送成功 |
UNKNOWN |
未知短信状态 |
REJECTD |
短信被短信中心拒绝 |
MBBLACK |
目的号码是黑名单号码 |
REJECT |
审核驳回 |
其他 |
网关内部状态 |
注：其他状态码可以参考http://code.253.com
请联系专属服务：15502129863