发送短信API
接口功能
该接口用于客户请求短信业务平台向指定用户发送短信。
使用说明
- 前提条件
- 注意事项
- 群发短信时，如果“to”参数携带的号码中包含除数字和+之外的其他字符，则无法向该参数携带的所有号码发送短信。如果“to”参数携带的所有号码只包含数字和+，但部分号码不符合号码规则要求，则在响应消息中会通过状态码标识发送失败的号码，不影响其他正常号码的短信发送。号码之间以英文逗号分隔，每个号码最大长度为21位，最多允许携带500个号码。如果携带超过500个号码，则全部号码都会发送失败。
- 根据短信内容的长度，一条长短信可能会被拆分为多条短信发送，拆分规则详见短信发送规则。
- 通过X-WSSE方式鉴权时，生成随机数的时间与发送请求时的本地时间的差值不能超过24小时，否则会导致鉴权失败。
- 请求body中的参数需要进行urlencode。
- 通过特殊AK/SK鉴权时，生成随机数的时间与发送请求时的本地时间的差值不能超过15分钟，否则会导致鉴权失败。
接口类型
请求方法 |
POST |
|---|---|
访问URI |
/sms/batchSendSms/v1 |
通信协议 |
HTTPS/HTTP |
请求参数
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
Content-Type |
是 |
String |
无 |
固定填application/x-www-form-urlencoded。 |
Authorization |
是 |
String |
无 |
SDK-HMAC-SHA256 Access= app_key的值, SignedHeaders=参与签名的头域（小写）, Signature=经过签名算法计算得到的值 具体计算方式请参考添加签名信息到请求头。
|
X-WSSE |
否（X-WSSE认证必选） |
String |
无 |
取值为UsernameToken Username="app_key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
|
X-Sdk-Date |
否（特殊AK/SK认证必选） |
String |
无 |
格式为：yyyyMMdd'T'HHmmss'Z' X-Sdk-Date不能与发送请求时的本地时间相差太大（15分钟内），否则会导致鉴权失败。 |
Host |
否 |
String |
无 |
API调用目的地址，用于特殊AK/SK认证：如smsapi.cn-north-4.myhuaweicloud.com:443 |
编程语言 |
时间格式 |
|---|---|
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()转换后的时间格式去除毫秒后即为本接口要求的时间格式。 |
Go |
2006-01-02T15:04:05Z |
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
from |
是 |
String(1-21) |
无 |
短信发送方的号码。 |
to |
是 |
String(1-21999) |
无 |
短信接收方的号码，标准号码格式为：+{国家码}{地区码}{终端号码}。
如果携带多个接收方号码，则以英文逗号分隔。每个号码最大长度为21位，最多允许携带500个号码。 |
templateId |
是 |
String(1-32) |
无 |
短信模板ID，用于唯一标识短信模板，请在申请短信模板时获取模板ID。 “templateId”需要与“templateParas”参数配合使用。 中国大陆短信通道号码对应的签名类型和模板ID对应的模板类型必须相同。 |
templateParas |
否 |
String[] |
无 |
注：当使用无变量模板时，可不带templateParas参数。 短信模板的变量值列表，用于依次填充“templateId”参数指定的模板内容中的变量，该参数需填写为JSONArray格式。请参考模板和变量规范。 列表中变量值的个数及长度必须和“templateId”对应模板内容中定义的变量个数及长度保持一致，例如“templateId”对应的模板内容有2个变量且变量长度分别为5和6，则此处需要设置2个变量值且内容长度分别小于等于5和6。 如模板内容为“您有${NUM_5}件快递请到${TXT_6}领取”时，该参数可填写为'["3","人民公园正门"]'。 |
statusCallback |
否 |
String(1-1024) |
无 |
客户的回调地址，用于接收短信状态报告，如：http://my.com/receiveSMSReport。
|
extend |
否 |
String(1-128) |
无 |
扩展参数，在状态报告中会原样返回。 不允许赋空值，不允许携带以下字符：“{”，“}”（即大括号）。 |
signature |
否 |
String(0-32) |
无 |
仅中国大陆短信可携带此参数。 签名名称，必须是已审核通过的，与模板类型一致的签名名称。 仅在templateId指定的模板类型为通用模板时生效且必填，用于指定在通用模板短信内容前面补充的签名。 |
响应参数
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
code |
是 |
String(1-7) |
无 |
请求返回的结果码。 |
description |
是 |
String(1-512) |
无 |
请求返回的结果码描述。 |
result |
否 |
SmsID[1-1000] |
无 |
短信ID列表，当目的号码存在多个时，每个号码都会返回一个SmsID。 当返回异常响应时不携带此字段。 |
参数名称 |
是否必选 |
参数类型 |
默认值 |
说明 |
|---|---|---|---|---|
smsMsgId |
是 |
String(1-50) |
无 |
短信的唯一标识。 |
from |
是 |
String(1-21) |
无 |
短信发送方的号码。 |
originTo |
是 |
String(1-21) |
无 |
短信接收方的号码。 |
status |
是 |
String(1-7) |
无 |
短信状态码。以下举例状态码及其说明，具体处理建议请参考接口调用错误码处理。
|
createTime |
是 |
String(1-20) |
无 |
短信资源的创建时间，即短信平台接收到客户发送短信请求的时间，为UTC时间。 格式为：yyyy-MM-dd'T'HH:mm:ss'Z'。 |
countryId |
否 |
String(1-3) |
无 |
短信接收方号码的国家码。 |
total |
否 |
int |
无 |
短信拆分条数。 |
结果码说明
响应码 |
结果码 |
英文描述 |
中文描述 |
处理方法 |
|---|---|---|---|---|
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接口文档的参数描述和要求，检查请求携带的参数是否都合法。 |
|
E000040 |
The value of ContentType must be application/x-www-form-urlencoded. |
ContentType值应该为application/x-www-form-urlencoded。 |
请检查ContentType头域的取值是否为“application/x-www-form-urlencoded”。 |
|
E000503 |
The parameter format is incorrect. |
参数格式错误。 |
请检查参数格式是否正确。 |
|
E000510 |
The SMS fails to be sent. For details, see Status. |
短信发送失败，描述见参数status。 |
查看响应参数中的status确认发送失败的原因，修改后重新发送。 |
|
401 |
E000101 |
Authentication failed. |
鉴权失败。 |
请检查Authorization和X-WSSE参数的填写是否正确。 |
E000102 |
Invalid app_key. |
app_key无效。 |
请检查请求携带的app_key填写是否正确。 如app_key填写正确，建议检查app接入地址是否正确（从控制台“应用管理”获取）。 |
|
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 |
Incorrect username or password. |
用户名或密码错误。 |
系统找不到app_key对应的用户信息，请联系管理员处理。 |
|
E000112 |
The subscriber status is frozen. |
用户状态已冻结。 |
若是因账户欠费冻结，请参考华为云账户充值完成充值，到账后自动解冻。 若是因业务违规冻结，请整改业务后联系运营经理申请解冻。 |
|
403 |
E000620 |
The app client ip is not in ip white list. |
对端app IP不在白名单列表中。 |
|
E000623 |
Number of SMSs sent by the SP reached the limit. |
SP短信发送量达到限额。 |
请联系运营经理协商调整SP短信发送量最大限额。 |
接口示例
- 请求示例1（X-WSSE认证）
POST /sms/batchSendSms/v1 HTTP/1.1 x-real-ip: 10.10.10.168 x-real-port: 10443 host: ompap.inner content-length: 184 date: Fri, 13 Apr 2018 06:31:39 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/x-www-form-urlencoded from=1069031221280012&to=%2B8615512345678&templateId=abcdefghabcdefghabcdefghabcdefgh&templateParas=%5B%22520520%22%5D&statusCallback=http%3A%2F%2F205%2E145%2E111%2E168%3A9330%2Freport
- 请求示例2（AK/SK认证）
POST /sms/batchSendSms/v1 HTTP/1.1 Host: smsapi.cn-north-4.myhuaweicloud.com:443 content-length: 184 X-Sdk-Date: 20230519T005038Z Authorization: SDK-HMAC-SHA256 Access=uxOF5yvM0H3C0t5G0xc272g7hA2I, SignedHeaders=content-type;host;x-sdk-date, Signature=082f05bcd561e291a7469939980c022f721a581967cc30eb3725c7aea4bd634d Content-Type: application/x-www-form-urlencoded from=1069********0012&to=%2B86155****5678&templateId=abcdefghabcdefghabcdefghabcdefgh&templateParas=%5B%22520520%22%5D&statusCallback=http%3A%2F%2F205%2E145%2E111%2E168%3A9330%2Freport
- 响应示例
HTTP/1.1 200 OK Date: Fri, 13 Apr 2018 06:29:08 GMT Server: WebServer Content-Type: application/json;charset=UTF-8 Content-Length: 247 {"result":[{"originTo":"+8615512345678","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"d6e3cdd0-522b-4692-8304-a07553cdf591_8539659","status":"000000","countryId":"CN","total":2}],"code":"000000","description":"Success"}
