发送验证码短信

最近更新时间：2023.04.20 19:37:28

首次发布时间：2023.01.17 16:23:54

短信服务使用方可以调用SendSmsVerifyCode接口，生成验证码并下发验证码短信。

接口说明

请求方式：POST
接口地址：https://sms.volcengineapi.com/?Action=SendSmsVerifyCode&Version=2020-01-01

请求参数

参数	数据类型	是否必填	示例值	描述
AccessKey	string	是	AKLTNzEzY2****	发送请求的火山引擎账号的 Access Key ID。您可以登录密钥管理页面获取。
SecretKey	string	是	RGTLuSHvnYxn****	发送请求的火山引擎账号的 Secret Access Key。您可以登录密钥管理页面获取。
ServiceName	string	是	volcSMS	服务名称。短信服务的服务名称为`volcSMS`。
Region	string	是	cn-north-1	区域名称。短信服务的区域名称为`cn-north-1`。
Content-Type	string	是	application/json;charset=utf-8	指定请求消息体的结构化格式。短信服务的 Content-Type 为`application/json;charset=utf-8`。

Query

参数	数据类型	是否必填	示例值	描述
Action	string	是	SendSmsVerifyCode	接口名称。该接口固定值为`SendSmsVerifyCode`。
Version	string	是	2020-01-01	接口版本。短信服务接口版本为`2020-01-01`。

Body

参数	类型	是否必填	示例值	描述
SmsAccount	string	是	049c2666	消息组ID，验码主键之一
Sign	string	是	火山测试	短信签名
TemplateID	string	是	sms-12345	短信模板ID，模板变量只支持code。模板类型必须是CN_OTP 或 I18N_OTP
Tag	string	否	tag-123456	透传字段。这个字段用于关联发送请求和短信回执，在回传回执消息的时候，会将该字段原样返回给服务使用方。例：如果你在短信发送请求的Tag中传了一个唯一的ID，在短信回执的ext参数中会把这个ID也原样返回给调用方。
Scene	string	是	注册验证码	验证码使用场景，验码主键之一
CodeType	int32	否	4，6，8	控制验证码长度，默认为6，不是468中的数字会直接生成6位验证码下发
ExpireTime	int32	否	60	验证码有效时间，单位为秒，范围是180-1800，默认180秒，超过范围会使用默认时间
TryCount	int32	否	1	验证码可以尝试验证次数，范围是1-10，默认1次；如果传值不是1-10，强制转化为3次
PhoneNumber	string	是	13333333333	接收手机号，不支持批量发送，验码主键之一 - 如果您设置的是中国大陆手机号，则国际区号为可选项。例如+86188******和188******都是合法的手机号码。 - 如果您设置的是非中国大陆手机号，则国际区号为必填项，且格式需符合 E.164 标准。

返回参数

请求响应数据以JSON格式返回，以下仅列出了短信业务逻辑相关的字段，其他公共返回参数详见返回结果。

参数	数据类型	描述
ResponseMetadata	ResponseMetadata	响应公共参数。包含的参数说明请参见ResponseMetadata。
Result	Result	响应业务参数。包含的参数说明请参见Result。

ResponseMetadata

参数	数据类型	描述
RequestId	string	请求 ID。
Action	string	请求的接口名称。
Version	string	请求的版本号。
Service	string	请求的服务名称。
Region	string	请求的区域。
Error	Error	错误信息。如果请求没有异常则不会返回错误信息。包含的参数说明请参见Error。

Result

参数	数据类型	描述
MessageID	Array	响应的消息 ID。每一条消息 ID 对应一个手机号的请求。多条消息 ID 的展示顺序即为传入电话号码的顺序。

Error

参数	数据类型	描述
Code	string	错误码。
Message	string	错误信息。

示例

请求示例

{
    "SmsAccount": "A123****",
    "TemplateId": "ST_6f8c****",
    "PhoneNumber": "152********",
    "CodeType": 6,
    "TryCount":3,
    "ExpireTime": 1800,
    "Scene": "注册验证码"
}

返回示例

正确返回示例

{
    "ResponseMetadata": {
        "RequestId": "a8e0788d-334e-49fc-92e8-61b7878c9735",
        "Action": "SendSms",
        "Version": "2020-01-01",
        "Service": "volcSMS",
        "Region": "ap-singapore-1"
    },
    "Result": {
        "MessageID": [
            "c0603139-2613-4f17-a9e3-e6faa3846eda"
        ]
    }
}

错误返回示例

{
    "ResponseMetadata": {
        "RequestId": "202211221050270101330310****",
        "Action": "SendSms",
        "Version": "2020-01-01",
        "Service": "volcSMS",
        "Region": "cn-north-1",
        "Error": {
            "Code": "ZJ10101",
            "Message": "SmsAccount not exist."
        }
    }
}

错误码

如果您在返回结果中遇到错误消息，可以使用下表作为详细信息和解决方案的指南。其中火山引擎网关公共错误码请参考火山引擎网关公共错误码。

Code	Message	说明	处理建议
ZJ10100	Account not exist. Please check whether SMS is enabled	账号不存在，一般为没有开通短信服务	到火山引擎开通短信服务
ZJ10101	SmsAccount not exist.	SmsAccount 填写错误	填写正确的 SmsAccount
ZJ10102	Sign not exist.	参数中指定的签名不存在	使用审核通过的签名下发短信
ZJ10103	TemplateID not exist.	参数中指定的模板 ID 不存在	使用审核通过的模板下发短信
ZJ10200	Param error. Please check that the parameters are correct.	请求参数错误	--
ZJ10203	Mobile format error.	传入的电话号码格式错误	检查号码格式
ZJ10500	System error	系统错误	联系短信业务平台管理员