StarCloud 云文档

Appearance

腾讯云协议接口 ​

腾讯云协议兼容腾讯云短信 SendSms 接口（版本 2021-01-11），采用 TC3-HMAC-SHA256 签名鉴权，可直接使用腾讯云官方 SDK 对接。

请求识别 ​

满足以下任一条件的请求按腾讯云协议处理：

  • 请求参数中 Version 为 2021-01-11；
  • 请求头包含 X-TC-Action 或 X-TC-Version。

请求格式 ​

http
POST / HTTP/1.1
Host: smspanel.szczk.top
Content-Type: application/json
Authorization: TC3-HMAC-SHA256 Credential=你的AccessKeyId/2026-09-27/sms/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=签名
X-TC-Action: SendSms
X-TC-Version: 2021-01-11
X-TC-Timestamp: 1758956400

{"PhoneNumberSet":["+8613800138000"],"TemplateId":"SMS_500650100","TemplateParamSet":["123456"],"SignName":"starcloud"}

鉴权说明（TC3-HMAC-SHA256） ​

  • Credential 中的 SecretId 填写短信后台的 AccessKeyId，签名密钥使用对应的 AccessKeySecret。
  • 签名算法与腾讯云官方 TC3-HMAC-SHA256 完全一致，服务固定为 sms，请求路径按 POST / 计算，可直接使用腾讯云 SDK。
  • X-TC-Timestamp 与服务器时间误差不能超过 15 分钟（900 秒），且日期须与 Credential 中的日期一致，否则返回 AuthFailure.SignatureExpire。
  • SignedHeaders 中列出的请求头必须全部存在，否则返回 AuthFailure.SignatureFailure。

签名详细规则参考 腾讯云 TC3 签名文档。

请求参数（JSON Body） ​

参数必填说明
PhoneNumberSet是手机号数组，仅取第一个号码发送。可带 +86 / 86 前缀，系统会自动去除。
TemplateId是模板 ID。SMS_500650100 为内置验证码模板，无需申请；其他模板须已在后台审核通过。
TemplateParamSet是模板参数数组，按模板变量出现顺序依次传值，参数个数必须与模板变量数一致。内置验证码模板只传 1 个纯数字验证码。
SignName否短信签名。可省略，系统按账户类型自动处理（会员可配置签名前缀，免费用户强制默认签名）。

响应格式（腾讯云风格 JSON） ​

成功响应（HTTP 200） ​

json
{
  "Response": {
    "SendStatusSet": [
      {
        "Code": "Ok",
        "Message": "发送成功",
        "PhoneNumber": "13800138000",
        "SerialNo": "unique_id"
      }
    ],
    "RequestId": "unique_id"
  }
}

失败响应 ​

json
{
  "Response": {
    "Error": {
      "Code": "InvalidParameter",
      "Message": "缺少手机号、模板ID或模板参数"
    },
    "RequestId": ""
  }
}

错误码 ​

错误码HTTP 状态码说明
InvalidParameter400请求参数或 TC3 鉴权头无效、缺少手机号/模板/参数、手机号格式不正确、验证码参数非数字。
InvalidParameter.TemplateId400模板不存在、未通过审核，或参数数量与模板变量数不匹配。
AuthFailure.SecretIdNotFound401SecretId（AccessKeyId）无效或已被禁用。
AuthFailure.SignatureExpire401请求时间戳无效或已过期（误差超过 15 分钟）。
AuthFailure.SignatureFailure401签名验证失败或签名头不完整。
IpNotAllowed403当前 IP 不在白名单中。
InvalidPhoneNumber400号码真实性检测失败。
VirtualNumberBlocked400虚拟运营商号段已被拦截。
CarrierBlocked400第三方运营商号码已被拦截。
OverQuota429短信包余额不足。
RateLimitExceeded429超过速率限制。
InternalError500数据库错误。

使用腾讯云 SDK 对接 ​

将 SDK 的 Endpoint 指向 https://smspanel.szczk.top，SecretId/SecretKey 分别填写短信后台的 AccessKeyId/AccessKeySecret 即可。以 Python 为例：

python
from tencentcloud.common import credential
from tencentcloud.sms.v20210111 import sms_client, models
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile

cred = credential.Credential("你的AccessKeyId", "你的AccessKeySecret")
http_profile = HttpProfile()
http_profile.endpoint = "smspanel.szczk.top"  # 指向本平台
client_profile = ClientProfile()
client_profile.httpProfile = http_profile

client = sms_client.SmsClient(cred, "", client_profile)
req = models.SendSmsRequest()
req.PhoneNumberSet = ["+8613800138000"]
req.TemplateId = "SMS_500650100"
req.TemplateParamSet = ["123456"]
resp = client.SendSms(req)
print(resp.to_json_string())

注意

  • 仅支持 SendSms 一个 Action，其他 Action 返回 InvalidParameter。
  • SmsSdkAppId 等腾讯云特有字段会被忽略，无需填写真实值。
  • 群发短信请循环调用，每次只发送 PhoneNumberSet 中的第一个号码。