SMS API 文档

概览

本文档基于项目 https://sms.speedonline.cloud/api 接口实现，提供两种集成方式：

1. SysKey方式：简单的 GET 接口，通过 syskey 识别请求者，适合快速集成轻量场景。

   • 验证码模式（默认）：直接发送验证码
   • 模板模式：使用预定义模板发送自定义内容

2. AK/SK方式：兼容阿里云短信 API 的签名方式，支持 GET/POST，适合与现有阿里云兼容工具或 SDK 集成。建议使用该方法

两种方式均会进行配额与速率校验，并记录发送日志。 以下请求中域名均为 https://sms.speedonline.cloud/api

---

一、SysKey方式接口

1.1 验证码模式（默认）

请求URL：

GET /?syskey=sk_xxx&phone=13800138000&code=123456

参数说明：

• syskey: 用户的SysKey（必填）
• phone: 手机号码（必填）
• code: 验证码（必填，4-6位数字）

响应示例：

{
  "Code": "OK",
  "Message": "短信已发送",
  "RequestId": "unique_id"
}

1.2 模板模式

请求URL：

GET /?syskey=sk_xxx&phone=13800138000&template_id=1&code={"name":"张三","order":"12345"}

参数说明：

• syskey: 用户的SysKey（必填）
• phone: 手机号码（必填）
• template_id: 模板ID（必填，从用户申请的模板中获取）
• code: 模板参数（必填，JSON格式字符串）

code参数格式说明：

• 必须是有效的JSON字符串
• JSON中的key对应模板中的变量（如 {name}, {order}）
• 例如：{"name":"张三","order":"12345"} 对应模板 尊敬的{name}，您的订单{order}已发货

响应示例：

{
  "Code": "OK",
  "Message": "短信已发送",
  "RequestId": "unique_id"
}

错误示例：

{
  "Code": "InvalidTemplate",
  "Message": "模板不存在或未通过审核"
}

---

二、AK/SK方式接口（兼容阿里云官方协议）

2.1 请求格式

请求URL：

POST /?AccessKeyId=xxx&Action=SendSms&PhoneNumbers=13800138000&SignName=签名&TemplateCode=模板ID&TemplateParam={"code":"123456"}&Signature=xxx

参数说明：

• AccessKeyId: 用户的AccessKeyId（必填）
• Action: 固定为 SendSms（必填）
• PhoneNumbers: 手机号码（必填）
• SignName: 短信签名（必填）
• TemplateCode: 模板代码（必填）
• TemplateParam: 模板参数（必填，JSON格式）
• Signature: 签名（必填，按照阿里云签名算法计算）

2.2 签名说明

• 服务器侧会读取 api_keys.access_key_id 和 access_key_secret 并使用相同的签名算法计算期望的 Signature（详细实现见阿里云官方方法）。
• 请求中需要包含 Signature 参数，服务端会比对计算出的签名与请求中的签名字符串。

2.3 请求示例

GET方式：

curl "https://sms.speedonline.cloud/api?AccessKeyId=ak_xxx&Action=SendSms&PhoneNumbers=13800138000&SignName=SpeedOnline&TemplateCode=SMS_CODE&TemplateParam={\"code\":\"123456\"}&Signature=..."

POST方式：

curl -X POST https://sms.speedonline.cloud/api \
  -d "AccessKeyId=ak_xxx" \
  -d "Action=SendSms" \
  -d "PhoneNumbers=13800138000" \
  -d "SignName=starcloud" \
  -d "TemplateCode=SMS_CODE" \
  -d "TemplateParam={\"code\":\"123456\"}" \
  -d "Signature=..."

---

三、错误码说明

错误码	说明
InvalidParameter	参数错误
InvalidSysKey	SysKey无效或已被禁用
InvalidAccessKeyId.NotFound	AccessKeyId无效或已被禁用
SignatureDoesNotMatch	签名验证失败
InvalidTemplate	模板不存在或未通过审核
OverQuota	配额已用尽
RateLimitExceeded	超过速率限制
NETWORK_ERROR	网络请求失败
PARSE_ERROR	响应格式错误

---

四、使用示例

4.1 PHP示例 - SysKey验证码模式

$url = 'https://sms.speedonline.cloud/api?syskey=sk_aaac8e6d8e6bf6c095aa172eb9cf144c&phone=13800138000&code=123456';
$response = file_get_contents($url);
$result = json_decode($response, true);

if ($result['Code'] === 'OK') {
    echo '发送成功';
} else {
    echo '发送失败：' . $result['Message'];
}

4.2 PHP示例 - SysKey模板模式

$template_param = json_encode(['name' => '张三', 'order' => '12345']);
$url = 'https://sms.speedonline.cloud/api?syskey=sk_xxx&phone=13800138000&template_id=1&code=' . urlencode($template_param);
$response = file_get_contents($url);
$result = json_decode($response, true);

if ($result['Code'] === 'OK') {
    echo '发送成功';
} else {
    echo '发送失败：' . $result['Message'];
}

4.3 PHP示例 - AK/SK方式

$params = [
    'AccessKeyId' => 'your_access_key_id',
    'Action' => 'SendSms',
    'Format' => 'JSON',
    'PhoneNumbers' => '13800138000',
    'SignName' => 'SpeedOnline',
    'TemplateCode' => 'SMS_123456789',
    'TemplateParam' => json_encode(['code' => '123456']),
    'SignatureMethod' => 'HMAC-SHA1',
    'SignatureNonce' => uniqid(),
    'SignatureVersion' => '1.0',
    'Timestamp' => gmdate('Y-m-d\TH:i:s\Z'),
    'Version' => '2017-05-25'
];

$params['Signature'] = calcSignature($params, 'your_access_key_secret', 'POST');

$ch = curl_init('https://sms.speedonline.cloud/api');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

---

五、配额与速率限制

• 表 api_keys：
  • total_quota：总配额（0 表示无限）
  • used_quota：已用配额（仅发送成功时累加）
  • rate_limit：速率限制（格式 次数:秒数）
• 超出配额或速率时接口返回 429 状态码和相应 Code（OverQuota / RateLimitExceeded）。
• 默认速率限制：每分钟100条（可在管理员后台为每个用户单独配置）。

---

六、测试建议

使用 curl 或 Postman 发送测试请求，检查返回结果。

---

七、注意事项

1. SysKey方式：

   • 验证码模式：code 参数直接传递验证码字符串
   • 模板模式：code 参数传递JSON格式的模板参数
   • 模板必须先在用户端申请并通过管理员审核

2. AK/SK方式：

   • 完全兼容阿里云官方接口协议
   • TemplateCode 直接使用阿里云的模板代码
   • TemplateParam 按照阿里云协议传递JSON格式参数

3. 通用要求：

   • 请求必须使用 HTTPS（建议）
   • 只有发送成功的短信才会扣除配额
   • 发送失败不扣除配额，但会记录日志

---