# 发送短信 #### 功能介绍 该接口用于向单个或多个手机号发送相同内容的短信。 #### 前提条件 - 已[创建短信应用](https://support.huaweicloud.com/usermanual-msgsms/sms_03_0001.html)，获取APP_Key、APP_Secret和APP接入地址。 - （仅国内短信）已[申请短信签名](https://support.huaweicloud.com/usermanual-msgsms/sms_03_0002.html)，获取签名通道号。 - 已[申请短信模板](https://support.huaweicloud.com/usermanual-msgsms/sms_03_0003.html)，获取模板ID。 #### 调试 您可以参考[发送短信代码样例](https://support.huaweicloud.com/devg-msgsms/sms_04_0018.html#ZH-CN_TOPIC_0000001606982993__section12610871145)，进行快速上手调试。 #### 接口类型 表1接口类型说明 | 请求方法 | POST | |---|---| | **访问URI** | /sms/batchSendSms/v1 | | **通信协议** | HTTPS/HTTP | #### 请求参数 表2请求Headers参数 | 参数名称 | 是否必选 | 参数类型 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | Content-Type | 是 | String | 无 | 固定填application/x-www-form-urlencoded。 | | Authorization | 是 | String | 无 | - 通过特殊AK/SK方式鉴权时，取值为： SDK-HMAC-SHA256 Access= ***app_key*** ***的值*** , SignedHeaders=***参与签名的头域（小写）*** , Signature=***经过签名算法计算得到的值*** 具体计算方式请参考[添加签名信息到请求头](https://support.huaweicloud.com/devg-apisign/api-sign-algorithm-001.html)。 - 通过X-WSSE方式鉴权时，取值为：WSSE realm="SDP",profile="UsernameToken",type="Appkey"。 | | X-WSSE | 否（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]。 | | 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 | 表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()转换后的时间格式去除毫秒后即为本接口要求的时间格式。 | | Go | 2006-01-02T15:04:05Z | 表4请求Body参数说明 | 参数名称 | 是否必选 | 参数类型 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | from | 是 | String(1-21) | 无 | 短信发送方的号码。 - 国内短信填写为短信平台为短信签名分配的通道号码，请在[申请短信签名](https://support.huaweicloud.com/usermanual-msgsms/sms_03_0002.html)时获取签名通道号，如：csms100000001，且通道号码对应的签名类型和模板ID对应的模板类型必须相同。 请在短信控制台"国内短信 \> 签名管理"内查看签名的通道号，签名和模板为对应关系，模板所属签名可在"国内短信 \> 模板管理"查看。 | | to | 是 | String(1-21999) | 无 | 短信接收方的号码，标准号码格式为：+{国家码}{地区码}{终端号码}。 - 发送国内短信：接收号码为国内手机号码时，所填号码可以不带+86，系统默认添加86，其他号码需符合标准号码格式：+{国家码}{地区码}{终端号码}。示例：+**86** 131\*\*\*\*5678，+**86**155\*\*\*\*6666。 如果携带多个接收方号码，则以英文逗号分隔。每个号码最大长度为21位，最多允许携带500个号码。 | | templateId | 是 | String(1-32) | 无 | 短信模板ID，用于唯一标识短信模板，请在[申请短信模板](https://support.huaweicloud.com/usermanual-msgsms/sms_03_0003.html)时获取模板ID。 "templateId"需要与"templateParas"参数配合使用。 国内短信通道号码对应的签名类型和模板ID对应的模板类型必须相同。 请在短信控制台"国内短信 \> 模板管理"内查看模板的ID。 注：API调用场景，请参考[响应参数](https://support.huaweicloud.com/api-msgsms/sms_05_0040.html)template_id。 | | templateParas | 否 | String\[\] | 无 | 说明： 当使用无变量模板时，可不带templateParas参数。 短信模板的变量值列表，用于依次填充"templateId"参数指定的模板内容中的变量，该参数需填写为JSONArray格式。请参考[模板规范](https://support.huaweicloud.com/productdesc-msgsms/sms_templates.html)和[变量规范](https://support.huaweicloud.com/productdesc-msgsms/sms_faq_0003.html)。 列表中变量值的个数及长度必须和"templateId"对应模板内容中定义的变量个数及长度保持一致，例如"templateId"对应的模板内容有2个变量且变量长度分别为5和6，则此处需要设置2个变量值且内容长度分别小于等于5和6。 如模板内容为"您有${1}件快递请到${2}领取"时，该参数可填写为'\["3","人民公园正门"\]'。 | | statusCallback | 否 | String(1-1024) | 无 | 用户的回调地址，用于接收短信状态报告，如：https://my.com/receiveSMSReport。 - 如果设置了该字段，则该消息的状态报告将通过"接收状态报告"接口直接通知用户。 - 如果未设置该字段，则短信平台收到运营商短信中心返回的状态报告不会推送给用户，该状态报告将在短信平台中保存1个小时，超时后系统会自动删除。 - 回调地址推荐使用域名。 | | extend | 否 | String(1-128) | 无 | 扩展参数，在状态报告中会原样返回。 不允许赋空值，不允许携带以下字符："{"，"}"（即大括号）。 | | signature | 否 | String(0-32) | 无 | 签名名称，必须是已审核通过的，与模板类型一致的签名名称。 仅在templateId指定的模板类型为[通用模板](https://support.huaweicloud.com/msgsms_faq/sms_faq_0066.html)时生效且必填，用于指定在通用模板短信内容前面补充的签名。 | #### 响应参数 表5响应结果参数 | 参数名称 | 是否必选 | 参数类型 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | code | 是 | String(1-7) | 无 | 请求返回的结果码。 | | description | 是 | String(1-512) | 无 | 请求返回的结果码描述。 | | result | 否 | [SmsID]\[1-1000\] | 无 | 短信ID列表，当目的号码存在多个时，每个号码都会返回一个SmsID。 当返回异常响应时不携带此字段。 | 表6SmsID定义 | 参数名称 | 是否必选 | 参数类型 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | smsMsgId | 是 | String(1-50) | 无 | 短信的唯一标识。 | | from | 是 | String(1-21) | 无 | 短信发送方的号码。 | | originTo | 是 | String(1-21) | 无 | 短信接收方的号码。 | | status | 是 | String(1-7) | 无 | 短信状态码。以下举例状态码及其说明，具体处理建议请参考[API错误码](https://support.huaweicloud.com/api-msgsms/sms_05_0050.html)。 - 000000：短信平台处理请求成功 - E200015：待发送短信数量太大 - E200028：模板变量校验失败 - E200029：模板类型校验失败 - E200030：模板未激活 - E200031：协议校验失败 - E200033：模板类型不正确 - E200041：同一短信内容接收号码重复 | | createTime | 是 | String(1-20) | 无 | 短信资源的创建时间，即短信平台接收到用户发送短信请求的时间，为UTC时间。 格式为：yyyy-MM-dd'T'HH:mm:ss'Z'。 | | countryId | 否 | String(1-3) | 无 | 短信接收方号码的国家码。 | | total | 否 | int | 无 | 短信拆分条数。 | #### 请求示例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=1069********0012&to=%2B86155****5678&templateId=abcdefghabcdefghabcdefghabcdefgh&extend=test&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":"+86155****5678","createTime":"2018-05-25T16:34:34Z","from":"1069********0012","smsMsgId":"d6e3cdd0-522b-4692-8304-a07553cdf591_8539659","status":"000000","countryId":"CN","total":2}],"code":"000000","description":"Success"} ``` #### 返回值 表7响应结果码 | 响应码 | 结果码 | 返回信息 | 描述 | 处理方法 | |:---|:---|:---|:---|:---| | 200 | 000000 | Success. | 发送请求成功。 | 无需处理。 | | 400 | E000000 | System error. | 系统异常。 | 请先对照代码样例检查templateParas参数设置是否正确。若排查代码后仍未解决问题，请联系管理员处理。 | | 400 | E000001 | Authorization not contained in the HTTP header. | HTTP消息头未找到Authorization字段。 | 请检查HTTP消息头中是否携带了Authorization字段。 | | 400 | E000002 | realm not contained in Authorization. | Authorization字段中未找到realm属性。 | 请检查Authorization字段中的是否携带了realm属性。 | | 400 | E000003 | profile not contained in Authorization. | Authorization字段中未找到profile属性。 | 请检查Authorization字段中的是否携带了profile属性。 | | 400 | E000004 | The value of realm in Authorization must be SDP. | Authorization中realm属性值应该为"SDP"。 | 请检查Authorization字段中的realm属性值是否为"SDP"。 | | 400 | E000005 | The value of profile in Authorization must be UsernameToken. | Authorization中profile属性值应该为"UsernameToken"。 | 请检查Authorization字段中的profile属性值是否为"UsernameToken"。 | | 400 | E000006 | The value of type in Authorization must be app_key. | Authorization中type属性值应该为"Appkey"。 | 请检查Authorization字段中的type属性值是否为"Appkey"。 | | 400 | E000007 | type not contained in Authorization. | Authorization字段中未找到type属性。 | 请检查Authorization字段中是否携带了type属性。 | | 400 | E000008 | WSSE not contained in Authorization. | Authorization中没有携带WSSE。 | 请检查Authorization字段中是否携带了WSSE。 | | 400 | E000020 | X-WSSE not contained in the HTTP header. | HTTP头未找到X-WSSE字段。 | 请检查HTTP消息头中是否携带了X-WSSE字段。 | | 400 | E000021 | UserName not contained in X-WSSE. | X-WSSE字段中未找到UserName属性。 | 请检查X-WSSE字段中的是否携带了UserName属性。 | | 400 | E000022 | Nonce not contained in X-WSSE. | X-WSSE字段中未找到Nonce属性。 | 请检查X-WSSE字段中的是否携带了Nonce属性。 | | 400 | E000023 | Created not contained in X-WSSE. | X-WSSE字段中未找到Created属性。 | 请检查X-WSSE字段中的是否携带了Created属性。 | | 400 | E000024 | PasswordDigest not contained in X-WSSE. | X-WSSE字段中未找到PasswordDigest属性。 | 请检查X-WSSE字段中的是否携带了PasswordDigest属性。 | | 400 | E000025 | The format of Created is incorrect. | Created属性格式错误。 | 请检查X-WSSE字段中的Created属性格式是否正确。 | | 400 | E000026 | UsernameToken not contained in X-WSSE. | X-WSSE字段中未找到UsernameToken属性。 | 请检查X-WSSE字段中的是否携带了UsernameToken属性。 | | 400 | E000027 | Invalid request. | 非法请求。 | 根据API接口文档的参数描述和要求，检查请求携带的参数是否都合法。 | | 400 | E000040 | The value of ContentType must be application/x-www-form-urlencoded. | ContentType值应该为application/x-www-form-urlencoded。 | 请检查ContentType头域的取值是否为"application/x-www-form-urlencoded"。 | | 400 | E000041 | X-Sdk-Date header is empty. | X-Sdk-Date为空 | 特殊AK/SK认证时，请检查HTTP消息头X-Sdk-Date的值。 | | 400 | E000042 | The format of X-Sdk-Date header is invalid. | X-Sdk-Date格式错误 | 特殊AK/SK认证时，请检查HTTP消息头X-Sdk-Date的格式，格式为：yyyyMMdd'T'HHmmss'Z' | | 400 | E000043 | The format of Authorization header is incorrect. | Authorization格式错误 | 特殊AK/SK认证时，请检查HTTP消息头Authorization格式。 | | 400 | E000044 | X-Sdk-Date is expired. | X-Sdk-Date过期 | 特殊AK/SK认证时，请检查HTTP消息头X-Sdk-Date的时间，不能与发送请求时的本地时间相差太大（15分钟内），否则会导致鉴权失败。 | | 400 | E000045 | Authorization verify failed. | Authorization校验失败 | 特殊AK/SK认证时，请检查HTTP消息头Authorization中的Signature字段。 | | 400 | E000503 | The parameter format is incorrect. | 参数格式错误。 | 请检查参数格式是否正确。 | | 400 | E000510 | The SMS fails to be sent. For details, see status. | 短信发送失败，描述见参数status。 | 查看响应参数中的status确认发送失败的原因，修改后重新发送。 | | 401 | E000101 | Authentication failed. | 鉴权失败。 | 请检查Authorization和X-WSSE参数的填写是否正确。 | | 401 | E000102 | Invalid app_key. | app_key无效。 | 请检查请求携带的app_key填写是否正确。 如app_key填写正确，建议检查app接入地址是否正确（从控制台"应用管理"获取）。 | | 401 | E000103 | The status of the app_key is unavailable. | app_key不可用。 | 请联系管理员确认该app_key状态是否正常。 | | 401 | E000104 | Invalid app_secret. | app_secret无效。 | 请检查请求携带的app_secret填写是否正确。 | | 401 | E000105 | Invalid digest. | PasswordDigest无效。 | 请检查请求携带的PasswordDigest填写是否正确。 | | 401 | E000106 | The app_key is not allowed to invoke this API. | app_key没有调用本API的权限。 | 请联系管理员确认该app_key是否具有"短信能力开放"能力。 | | 401 | E000109 | The user status is deactivated. | 用户状态未激活。 | 请联系管理员激活用户。 | | 401 | E000110 | Time out limit. | 时间超出限制。 | 请确认X-WSSE鉴权时，生成随机数的时间与发送请求时的本地时间不能相差太大（具体差值请与管理员确认）。 | | 401 | E000111 | Incorrect username or password. | 用户名或密码错误。 | 系统找不到app_key对应的用户信息，请联系管理员处理。 | | 401 | E000112 | The subscriber status is frozen. | 用户状态已冻结。 | 若是因账户欠费冻结，请参考[华为云账户充值](https://support.huaweicloud.com/usermanual-billing/bills-topic_30000002.html)完成充值，到账后自动解冻。 若是因业务违规冻结，请整改业务后联系运营经理申请解冻。 | | 403 | E000620 | The app client ip is not in ip white list. | 对端app IP不在白名单列表中。 | - IP白名单配置生效约有10\~15分钟的时延，未及时生效可能导致该报错。 - IP白名单配置不正确。请前往控制台"应用管理"单击"修改"应用，检查并修改自行配置的IP白名单，或重新添加正确的IP白名单（IP白名单为平台管理员配置时）。 | | 403 | E000623 | Number of SMSs sent by the SP reached the limit. | SP短信发送量达到限额。 | 请联系运营经理协商调整SP短信发送量最大限额。 | | 403 | E000630 | Number of SMSs sent by the SP reached the country/region limit. | SP 发送量达到国家/地区级限额 | 设置流量阈值时，为该号码所属国家/地区设置了限额值。租户发往该国家/地区的短信数量累计 超过限额值导致短信发送失败。 请在控制台"通用设置"页面，修改/删除该号码所属国家/地区的限额值。详细操作请参见[设置流量阈值](https://support.huaweicloud.com/usermanual-msgsms/sms_03_1007.html#section1)。若限额值大小不满足需求，请联系运营经理协商调整SP短信发送量最大限额。 |