文档首页 > > API参考> 发送分批短信API

发送分批短信API

分享
更新时间:2020/09/27 GMT+08:00

接口功能

该接口用于客户请求短信平台向不同用户发送不同的短信。

使用说明

  • 前提条件
    1. 创建短信应用,获取APP_Key、APP_Secret和APP接入地址(国际短信还需获取通道号)。
    2. (仅国内短信)已申请短信签名,获取签名通道号。
    3. 申请短信模板,获取模板ID。
  • 注意事项
    1. 单条短信最多允许携带1000个号码,号码之间以英文逗号分隔,每个号码最大长度为21位。如果单条短信携带超过1000个号码,则该单条短信全部号码都会发送失败。
    2. 通过X-WSSE方式鉴权时,生成随机数的时间不能与发送请求时的本地时间相差太大(具体差值请与管理员确认),否则会导致鉴权失败。

接口类型

表1 接口类型说明

请求方法

POST

访问URI

/sms/batchSendDiffSms/v1

通信协议

HTTPS

请求参数

表2 请求Headers参数

参数名称

是否必选

参数类型

默认值

说明

Content-Type

String

固定填application/json。

Authorization

String

取值为WSSE realm="SDP",profile="UsernameToken",type="Appkey"。

X-WSSE

String

取值为UsernameToken Username="app_key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
  • PasswordDigest:根据PasswordDigest = Base64 (SHA256 (Nonce + Created + Password))生成,直接使用Nonce、Created、Password拼接后的字符串进行SHA256加密即可,字符串中无需包含+号和空格。其中,Password为app_secret的值。
  • Nonce:客户发送请求时生成的一个随机数,长度为1~128位,可包含数字和大小写字母。例如:66C92B11FF8A425FB8D4CCFE0ED9ED1F。
  • Created:随机数生成时间。采用标准UTC格式,例如:2018-02-12T15:30:20Z。不同编程语言中的时间格式转换方式不同,部分语言可参考表3
表3 不同编程语言的时间格式

编程语言

时间格式

Java

yyyy-MM-dd'T'HH:mm:ss'Z'

PHP

Y-m-d\TH:i:s\Z

Python

%Y-%m-%dT%H:%M:%SZ

C#

yyyy-MM-ddTHH:mm:ssZ

Node.js

toISOString().replace(/.[0-9]+\Z/, 'Z')

注:Node.js中,使用toISOString()转换后的时间格式去除毫秒后即为本接口要求的时间格式。

表4 请求Body参数说明

参数名称

是否必选

参数类型

默认值

说明

from

String(1-21)

短信发送方的号码。

  • 国内短信填写为短信平台为短信签名分配的通道号码,请在申请短信签名时获取签名通道号,如:csms100000001,且通道号码对应的签名类型和模板ID对应的模板类型必须相同。
  • 国际/港澳台短信填写为创建短信应用时分配的通道号,如:isms100000001。

请在短信控制台“国内短信>签名管理”内查看签名的通道号,签名和模板为对应关系,模板所属签名可在“国内短信>模板管理”查看。

statusCallback

String(1-1024)

客户的回调地址,用于接收短信状态报告,如:http://my.com/receiveSMSReport。

  • 如果设置了该字段,则该消息的状态报告将通过“接收状态报告”接口直接通知客户。
  • 如果未设置该字段,则短信平台收到运营商短信中心返回的状态报告不会推送给客户,该状态报告将在短信平台中保存1个小时,超时后系统会自动删除。
  • 回调地址推荐使用域名。

smsContent

SmsContent[]

发送的通知短信内容,短信内容不能超过64KB。

extend

String(1-128)

扩展参数,在状态报告中会原样返回。

不允许赋空值,不允许携带以下字符:“{”,“}”(即大括号)。

表5 SmsContent定义

参数名称

是否必选

参数类型

默认值

说明

to

String[](1-21999)

群发短信接收方的号码,标准号码格式为:+{国家码}{地区码}{终端号码}。

  • 发送国内短信,如果“+{国家码}”不存在,则默认为+86,如果接收方号码为手机号码,则{地区码}可选。如:+8613112345678。
  • 发送国际/港澳台短信:不区分接收号码类型,所填号码都必须符合标准号码格式。示例:+2412000000(加蓬号码)

如果携带多个接收方号码,则以英文逗号分隔。每个号码最大长度为21位,最多允许携带1000个号码。

templateId

String(1-32)

短信模板ID,用于唯一标识短信模板,请在申请短信模板时获取模板ID。

“templateId”需要与“templateParas”参数配合使用。

国内短信通道号码对应的签名类型和模板ID对应的模板类型必须相同。

请在短信控制台“国内短信>模板管理”内查看模板的模板ID。

templateParas

String[]

注:当使用无变量模板时,可不带templateParas参数。

短信模板的变量值列表,用于依次填充“templateId”参数指定的模板内容中的变量,该参数需填写为JSONArray格式。请参考模板和变量规范

列表中变量值的个数及长度必须和“templateId”对应模板内容中定义的变量个数及长度保持一致,例如“templateId”对应的模板内容有2个变量且变量长度分别为5和6,则此处需要设置2个变量值且内容长度分别小于等于5和6。

如模板内容为“您有${1}件快递请到${2}领取”时,该参数可填写为["3","人民公园正门"]。

signature

String(0-32)

签名名称,必须是已审核通过的,与模板类型一致的签名名称。

仅在templateId指定的模板类型为通用模板时生效且必填,用于指定在通用模板短信内容前面补充的签名。

国际/港澳台短信无需关注此参数。

响应参数

表6 响应结果参数

参数名称

是否必选

参数类型

默认值

说明

code

String(1-7)

请求返回的结果码。

description

String(1-512)

请求返回的结果码描述。

result

SmsID[]

短信结构体,当返回响应出现异常时不包含此字段。

表7 SmsID定义

参数名称

是否必选

参数类型

默认值

说明

smsMsgId

String(1-50)

短信的唯一标识。

from

String(1-21)

短信发送方的号码。

originTo

String(1-21)

短信接收方的号码。

status

String(1-7)

短信状态码,请参考API错误码

  • 000000:短信平台处理请求成功
  • E200015:待发送短信数量太大
  • E200028:模板变量校验失败
  • E200029:模板类型校验失败
  • E200030:模板未激活
  • E200031:协议校验失败
  • E200033:模板类型不正确
  • E200041:同一短信内容接收号码重复

createTime

String(1-20)

短信资源的创建时间,即短信平台接收到客户发送短信请求的时间,为UTC时间。

格式为:yyyy-MM-dd'T'HH:mm:ss'Z'。

结果码说明

表8 响应结果码

响应码

结果码

英文描述

中文描述

处理方法

200

000000

Success.

发送请求成功。

无需处理。

400

E000000

System error.

系统异常。

请先对照代码样例检查templateParas参数设置是否正确。若排查代码后仍未解决问题,请联系管理员处理。

E000001

Authorization not contained in the HTTP header.

HTTP消息头未找到Authorization字段。

请检查HTTP消息头中是否携带了Authorization字段。

E000002

realm not contained in Authorization.

Authorization字段中未找到realm属性。

请检查Authorization字段中的是否携带了realm属性。

E000003

profile not contained in Authorization.

Authorization字段中未找到profile属性。

请检查Authorization字段中的是否携带了profile属性。

E000004

The value of realm in Authorization must be SDP.

Authorization中realm属性值应该为“SDP”。

请检查Authorization字段中的realm属性值是否为“SDP”

E000005

The value of profile in Authorization must be UsernameToken.

Authorization中profile属性值应该为“UsernameToken”。

请检查Authorization字段中的profile属性值是否为“UsernameToken”

E000006

The value of type in Authorization must be app_key.

Authorization中type属性值应该为“Appkey”。

请检查Authorization字段中的type属性值是否为Appkey

E000007

type not contained in Authorization.

Authorization字段中未找到type属性。

请检查Authorization字段中是否携带了type属性。

E000008

WSSE not contained in Authorization.

Authorization中没有携带WSSE。

请检查Authorization字段中是否携带了WSSE。

E000020

X-WSSE not contained in the HTTP header.

HTTP头未找到X-WSSE字段。

请检查HTTP消息头中是否携带了X-WSSE字段。

E000021

UserName not contained in X-WSSE.

X-WSSE字段中未找到UserName属性。

请检查X-WSSE字段中的是否携带了UserName属性。

E000022

Nonce not contained in X-WSSE.

X-WSSE字段中未找到Nonce属性。

请检查X-WSSE字段中的是否携带了Nonce属性。

E000023

Created not contained in X-WSSE.

X-WSSE字段中未找到Created属性。

请检查X-WSSE字段中的是否携带了Created属性。

E000024

PasswordDigest not contained in X-WSSE.

X-WSSE字段中未找到PasswordDigest属性。

请检查X-WSSE字段中的是否携带了PasswordDigest属性。

E000025

The format of Created is incorrect.

Created属性格式错误。

请检查X-WSSE字段中的Created属性格式是否正确。

E000026

UsernameToken not contained in X-WSSE.

X-WSSE字段中未找到UsernameToken属性。

请检查X-WSSE字段中的是否携带了UsernameToken属性。

E000027

Invalid request.

非法请求。

根据API接口文档的参数描述和要求,检查请求携带的参数是否都合法。

E000503

The parameter format is incorrect.

参数格式错误。

请检查参数格式是否正确。

E000510

The SMS fails to be sent. For details, see status.

短信发送失败,描述见参数status。

查看响应参数中的status确认发送失败的原因,修改后重新发送。

E000623

Number of SMSs sent by the SP reached the limit.

SP短信发送量达到限额。

请联系运营经理协商调整SP短信发送量最大限额。

401

E000101

Authentication failed.

鉴权失败。

请检查Authorization和X-WSSE参数的填写是否正确。

E000102

Invalid app_key.

app_key无效。

请检查请求携带的app_key填写是否正确。

E000103

The status of the app_key is unavailable.

app_key不可用。

请联系管理员确认该app_key状态是否正常。

E000104

Invalid app_secret.

app_secret无效。

请检查请求携带的app_secret填写是否正确。

E000105

Invalid digest.

PasswordDigest无效。

请检查请求携带的PasswordDigest填写是否正确。

E000106

The app_key is not allowed to invoke this API.

app_key没有调用本API的权限。

请联系管理员确认该app_key是否具有“短信能力开放”能力。

E000109

The user status is deactivated.

用户状态未激活。

请联系管理员激活用户。

E000110

Time out limit.

时间超出限制。

请确认X-WSSE鉴权时,生成随机数的时间与发送请求时的本地时间不能相差太大(具体差值请与管理员确认)。

E000111

Inccorect username or password.

用户名或密码错误。

系统找不到app_key对应的用户信息,请联系管理员处理。

E000112

The subsriber status is frozen.

用户状态已冻结。

请联系管理员解冻用户。

403

E000620

The app client ip is not in ip white list.

对端app IP不在白名单列表中。

联系管理员检查IP白名单是否配置正确。

接口示例

  • 请求示例
    POST /sms/batchSendDiffSms/v1 HTTP/1.1
    x-real-ip: 10.10.10.168
    x-real-port: 10443
    host: ompap.inner
    content-length: 315
    date: Fri, 13 Apr 2018 06:48:35 GMT
    authorization: WSSE realm="SDP",profile="UsernameToken",type="Appkey"
    x-wsse: UsernameToken Username="ZRBRz4bAXoFgEH7o4Ew308eXc1RA",PasswordDigest="NDA1MWIwNjI2ZTkyNWFlM2FhMTE5NDE1YTk5NjU1YWE4NjNlZTY1MmRhYzkxZGViNzczZjdjMjkzZWQ4ZjAwNA==",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z"
    accept: application/json
    content-type: application/json
    
    {"from":"1069031221280012","smsContent":[{"to":["+8615512345678","+8615512345679"],"templateId":"abcdefghabcdefghabcdefghabcdefgh","templateParas":["062569"]},{"to":["+8615512345680"],"templateId":"hgfedcbahgfedcbahgfedcbahgfedcba","templateParas":["605623"]}],"statusCallback":"http://205.145.111.168:9330/report"}
  • 响应示例
     HTTP/1.1 200 OK
    Date: Fri, 13 Apr 2018 06:46:04 GMT
    Server: WebServer
    Content-Type: application/json;charset=UTF-8
    Content-Length: 541
    
    {"result":[{"originTo":"+8615512345678","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_52","status":"000000"},{"originTo":"+8615512345679","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_53","status":"000000"},{"originTo":"+8615512345680","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"5963c5be-f189-4c0c-ab2e-7cab0c42c798_54","status":"000000"}],"code":"000000","description":"Success"}

相关推荐

相关文档

相关产品

语音通话

隐私保护通话

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问