短信接口文档(1.0)

1.短信发送请求接口

1.1发送请求

方式:http post

PS:请求串是键值对格式,返回串有两种格式XML和JSON,默认返回XML格式。

参数定义

名称 类型 必需 描述
mcid String 必选 客户唯一标识,需平台分配
usernumber String 必选 手机号码,不带+86(暂只支持一个号码)
smscontent String 必选 短信内容,必须携带签名,URL编码(UTF8)
timestamp String 必选 时间戳
sign String 必选 参数签名值
tid String 必选 短信模板ID

sign 签名值生成规则:

上述所有参数(sign除外),以小写方式带上参数值用url传参形式拼接,按参数名的正序排列再拼接上加密串signKey(平台分配)用MD5加密后输出32位大写字母。

示例: Md5("mcid=2312&smscontent=xxx&tid=456&timestamp=1541565672&usernumber=13800000000"+signKey)

1.2返回值

接口body输出示例:

<?xml version="1.0"?>
<ResponseData>
  <ResultCode>000</ResultCode >
  <ResultDesc>鉴权成功</ResultDesc >
  <SmsId>892869</SmsId>
</ResponseData>
名称 类型 描述
ResultDesc String 返回码解释
SmsId String 短信唯一的ID,根据此ID,推送通知给客户
ResultCode String 返回码(参见返回码定义)

1.3返回码定义

返回码 描述
000 成功
100 XML格式不对
104 时间戳为空
105 时间戳格式错误
106 时间戳超时
107 appkey为空
108 appkey过长
109 appkey非法
112 sign_code长度错误
999 未知错误
9001 参数不符合约定
8008 IP黑名单
7009 Sign验签失败
8007 手机号码黑名单
8005 账号验证失败
7005 流程异常
9230 报告没有准备好

2.状态报告通知

合作方需按此开发,并提供接口地址给我方,将通过该接口同步短信状态数据。

2.1请求格式

提交方式:http post

提交格式:xml

字段定义:

字段 类型 说明
MsgId Long 短信序列号
SendStatus Int 短信下发状态码
SmsMsg String 短信下发状态描述
ReceiveNum String 接收手机号码(不带86)
ReceiveTime Date 状态报告返回时间(为空表示短信返回失败,失败情况请参看返回结果中短信发送的返回码)

body示例:

<?xml version="1.0" encoding="utf-8"?>
<Root>
  <ResponseData> 
    <MsgId>2771156304</MsgId>
    <SmsMsg>DELIVRD</SmsMsg>
    <SendStatus>0</SendStatus>
    <ReceiveNum>13512345678</ReceiveNum>
    <ReceiveTime>20150522 10:28:41</ReceiveTime>
  </ResponseData>
  <ResponseData>
    <MsgId>2771156305</MsgId>
    <SmsMsg> DELIVRD </SmsMsg>
    <SendStatus>0</SendStatus>
    <ReceiveNum>13512345688</ReceiveNum>
    <ReceiveTime>20150522 10:28:41</ReceiveTime>
  </ResponseData>
  <ResponseData>
    <MsgId>2771156308</MsgId>
    <SmsMsg> DELIVRD </SmsMsg>
    <SendStatus>0</SendStatus>
    <ReceiveNum>13512345699</ReceiveNum>
    <ReceiveTime>20150522 10:28:41</ReceiveTime>
  </ResponseData>
</Root>

2.2返回值

Body返回数据说明:

字段 类型 说明
RetCode Int 应答码:0:推送成功 1:推送失败
RetMsg String 应答说明 成功:success 失败:fail

示例:

<?xml version="1.0" encoding="utf-8"?>
<Root>
  <RetCode>0</RetCode>
  <RetMsg>1</RetMsg>
</Root>

3.上行短信通知

合作方需按此开发,并提供接口地址给我方,将通过该接口同步短信上行数据。

3.1请求格式

提交方式:http post

提交格式:xml

字段定义:

字段 类型 说明
SpNumber String 端口号
UserNumber String 用户手机号码
MoMsg String 上行内容
MoTime Date 上行时间
TimeStamp String 时间戳
Sign String 时间戳和key值的md5摘要,md5(timestamp+key)

请求body示例:

<?xml version="1.0" encoding="utf-8"?>
<Root>
  <SpNumber>XXX</SpNumber>
  <UserNumber>XXX</UserNumber>
  <MoMsg>XXX</MoMsg>
  <MoTime>XXX</MoTime>
  <TimeStamp>XXX</TimeStamp >
  <Sign>XXX</Sign>
</Root>

3.2返回值

格式:xml

参数说明:

字段 类型 说明
RetCode Int 应答码 0:成功 非0 :失败
RetMsg String 应答说明 成功 :success 失败:fail

示例:

<?xml version="1.0" encoding="utf-8"?>
<Root>
  <RetCode>0</RetCode>
  <RetMsg>1</RetMsg>
</Root>

4.批量发送接口

4.1请求参数

请求参数 类型 说明
posttype Posttype=xml,Posttype=json

4.2请求包体

(1)格式1:

<?xml version="1.0"?>
<BatchSmsRequest>
  <Mcid>xx</Mcid>
  <Phone>
    <string>15x109765xx</string>
    <string>15x327818xx</string>
  </Phone>
  <Content>【中通快递】快递在2018-09-01到恒大名都,记得前去取。如有疑问请致电:18901029323,详情请查看</Content>
  <Tid>xx</Tid>
  <ExtendString>xms</ExtendString>
</BatchSmsRequest>

(2)格式2

{
"Mcid": xx,
"Content": "【中通快递】快递在2018-09-01到恒大名都,记得前去取。如有疑问请致电:18901029323,详情请查看",
"Tid": xx,
"ExtendString": "xms",
"Phone": ["158109765xx", "150327818xx"]
}

4.3请求字段解释

字段 类型 说明
Mcid Int 客户ID
Content String 短信内容
Tid Int 模板ID
ExtendString String 透传(自定义)参数
Phone String[] 号码集合,最大支持100个

4.4错误解释

具体请查看1.3错误列表

4.5请求DEMO:

http://43.250.238.135/SMS/BatchSms.ashx?posttype=json

4.6下发字段解释

字段 类型 说明
Code Int 状态码-详细请查看1.3错误列表
Msg String 消息提示
ResultCode String 每条对应的提交状态code
ResultDesc String 每条消息提示
SmsId String[] 短信唯一的ID,根据此ID获取状态报告

5.获取批量提交的状态报告

5.1请求参数

请求参数 类型 说明
posttype Posttype=xml,Posttype=json

5.2请求包体

(1)格式1

<?xml version="1.0"?>
<ReportPhone>
  <Mcid>1</Mcid>
  <SmsIdlist>
    <string>18461242750341120</string>
    <string>18461242764824576</string>
  </SmsIdlist>
</ReportPhone>

(2)格式2

{
"Mcid": 1,
"SmsIdlist": ["18461242750341120","18461242764824576"]
}

5.3请求字段解释

字段 类型 说明
Mcid Int 客户ID
SmsIdlist String[] 号码集合,最大支持100个

5.4错误解释

具体请查看1.3错误列表

5.5请求DEMO:

http://43.250.238.135/SMS/GetReport.ashx?posttype=json

5.6下发字段解释

字段 类型 说明
Code Int 状态码-详细请查看1.3错误列表
Msg String 消息提示
SmsId String 短信唯一ID
Report String 状态,参考附录一

6.查询余额接口

请求方式:GET

接口地址:http://43.250.238.135/SMS/SmsCount.ashx

6.1请求字段解释

字段 类型 说明
CorpID String 账号ID
Pwd String 密码

6.2下发字段解释

字段 类型 说明
Count Long 剩余条数
Code Int 返回码(参见6.3返回码定义)

6.3返回码定义

返回码 描述
1 正常响应
1002 代表参数为空
1003 代表没有查询到此账号
500 内部异常

附录一 RptMemo 短信状态报告错误描述

对应于短信状态报告( CMPP_DELIVER )包中 中的状态码( Stat) 字段

RptMemo 说明
DELIVRD 成功(移动短信网关,成功将短信送达手机终端)
EXPIRED 短信已过期
DELETED 短信已经删除
UNDELIV 无法送达短信
ACCEPTD 短信处于接受状态(但是仍无法成功送达)
UNKNOWN 未知原因
REJECTD 短信处于拒绝状态
MA:xxxx SMSC不返回响应消息时的状态报告
MB:xxxx SMSC返回错误响应消息时的状态报告
MC:xxxx 没有从SMSC处接收到状态报告时的状态报告
MI:xxxx 表示用户长时间关机或者不在服务区等导致的短信息超时没有递交到用户手机上
MJ:xxxx DELETED
MK:xxxx 表示全球通用户因为状态不正确如处于停机、挂起等状态而导致的用户无法享受服务
MM:xxxx UNKNOWN
MN:xxxx 消息因为某些原因被拒绝
CA:xxxx SCP不返回响应消息时的状态报告
CB:xxxx SCP返回错误响应消息时的状态报告
DA:xxxx DSMP不返回响应消息时的状态报告
DB:xxxx DSMP返回错误响应消息时的状态报告
SA:xxxx SP不返回响应消息时的状态报告
SB:xxxx SP返回错误响应消息时的状态报告
IA:xxxx 下一级ISMG不返回响应消息时的状态报告
IB:xxxx 下一级ISMG返回错误响应消息时的状态报告
IC:xxxx 没有从下一级ISMG处接收到状态报告时的状态报告

附录二 RptCode 短信状态报告错误码

RptMemo的数字化描述

RptCode 说明
0 RptMemo的DELIVRD状态
99 短信发送中(移动短信网关,正在给手机终端发送短信)
1 消息结构错
2 命令字错
3 消息序号重复
4 消息长度错
5 资费代码错
6 超过最大信息长
7 业务代码错
8 流量控制错
9 其他
35 SCP返回3号错误
42 SCP返回10号错误
45 SCP返回15号错误
12 计费地址错误,消息中计费地址为空或计费地址不是正确运营商的手机号码,消息中计费地址被EC区域管理功能拦截。
42 计费号码是异网号码,消息计费地址为异网号码,该消息被系统禁止,请检查消息计费地址号码是否正确。
76 短信网关拦截