阿里云短信服务对接使用完全指南：从资质申请到多语言SDK集成

一、认识阿里云短信服务

短信服务是企业业务系统中不可或缺的基础通信能力。无论是用户注册登录时的验证码发送、订单状态变更后的通知推送、服务到期前的提醒触达，还是会员活动中的营销推广，短信都承担着连接企业与用户的重要角色。阿里云短信服务作为企业级通信服务，国内验证短信秒级触达，到达率最高可达99%，国际短信覆盖200多个国家和地区，历经双十一等极端流量场景考验。

然而在实际接入过程中，短信并不是调用一个接口、把内容发出去那么简单。尤其是首次接入时，企业通常需要依次完成资质提交、签名申请、模板审核、运营商实名报备、API对接、发送状态查询和回执配置等多个环节。本文将从零开始，完整拆解整个接入链路，并提供多种主流开发语言的SDK集成示例。

需要先登录阿里云控制台，点击：阿里云控制台

二、整体接入流程概览

一条短信从你想发送到用户收到，中间经过了完整的审核与发送链路。全流程可以拆解为以下核心环节：

• 账号准备与开通服务：注册阿里云账号、完成企业实名认证、开通短信服务
• 申请资质：提交企业营业执照等资质材料，审核通过后方可申请签名
• 申请短信签名：创建签名并等待审核通过，工作时间提交最快24小时
• 运营商实名报备：2025年起新增的必要环节，平均5至7个工作日
• 申请短信模板：创建模板并等待审核通过，约2至4小时
• 购买资源包或充值：确保账户有足够余额
• 发送短信：通过控制台群发助手或API、SDK程序化发送

需要注意的是，阿里云短信服务目前仅支持企业认证账号。个人认证用户功能受限，无法发送营销短信，且可能影响签名审核通过率。如果个人认证用户仅需发送验证码短信，可以考虑申请开通阿里云号码认证服务的短信认证功能。

三、准备工作

3.1 注册账号与企业实名认证

访问阿里云官网注册账号后，需要进行企业实名认证。个体工商户通常也算企业认证。实名认证是开通短信服务的硬性门槛。

3.2 开通短信服务

在阿里云产品列表中找到短信服务并开通，登录短信服务控制台，根据提示完成服务开通。

3.3 购买资源包或确保余额充足

短信服务计费方式分为按量计费和套餐包两种。国际站默认采用短信资源包付费模式，需要先购买资源包。如果有短信套餐包则先扣除套餐包，超出套餐包额度后按量计费，扣除账户余额。短信服务使用全流程中，仅在发送短信时产生费用。

3.4 创建RAM用户并获取AccessKey

AccessKey是调用API的凭证。强烈建议使用RAM子用户的AccessKey，并授予其AliyunDysmsFullAccess权限策略，这比直接使用主账号的AccessKey更安全。

创建RAM用户的步骤：

• 访问RAM控制台创建子用户
• 为该子用户设置对应的权限，推荐授予AliyunDysmsFullAccess短信管理权限
• 获取该子用户的AccessKey ID和AccessKey Secret

安全最佳实践：使用环境变量存储AccessKey（禁止硬编码）、定期轮换密钥、遵循最小权限原则。

四、申请短信资质

短信资质是阿里云对发送方身份的基础审核，相当于确认你是谁。企业需要提交营业执照或相关证件，阿里云会审核企业信息的真实性。资质审核通过后，才能进入签名和模板的申请环节。

资质申请需要准备的材料包括：短信发送方业务信息、短信发送方企业实名信息（企业名称、统一社会信用代码等）、短信签名、APP或网站或商标等名称、短信类型、短信发送授权书、企业责任人实名信息（法定代表人姓名、法定代表人身份证号、企业短信管理员姓名、管理员身份证号）等。

自用资质指申请短信资质时所提供的企业信息与当前登录的阿里云账户已认证的信息完全一致；他用资质指资质信息归属企业与账号认证企业不一致，需要提交授权委托书。

五、申请短信签名

短信签名是显示在短信内容开头的标识，例如【阿里云】。签名位于短信内容前的括号标识中，需与认证主体相关，并提交资质证明审核。

审核中的短信签名不支持撤回。短信签名创建后不允许修改，只能删除。短信签名删除后，不能再次使用该签名发送短信，请谨慎删除。一般情况下，短信签名提交后，阿里云预计在2个小时内审核完成（审核时间：工作日9:00~23:00，法定节日顺延），建议尽量在18:00前提交申请。

从2025年起，中国大陆新增短信签名必须完成运营商实名报备（5至10个工作日），请提前规划。

六、申请短信模板

短信模板即接收方收到短信的详细内容，包括变量和模板内容。模板内容需符合规范，变量格式为${variable}。例如：尊敬的${name}，您的验证码是${code}，请在${time}分钟内输入。

审核中的短信模板不支持撤回。短信模板创建后不允许修改，只能删除。模板审核时间约2至4小时。

七、通过API/SDK发送短信

调用短信服务API的整体流程涉及开发者应用、阿里云SDK、身份与权限管理（RAM）以及短信服务本身。核心逻辑是：开发者将阿里云SDK集成至应用中，并通过RAM为应用分配具有短信服务权限的访问凭证，应用使用该凭证调用阿里云短信服务的API发送请求，阿里云服务端完成鉴权与合规校验后，将消息交由短信网关处理，并通过运营商网络最终将短信送达目标用户手机。

阿里云短信服务SDK支持多种编程语言，包括Java、Go、C#、PHP、Node.js/TypeScript和Python。使用SDK集成短信服务可以提升开发效率，SDK内部处理了网络通信、请求格式化和响应解析等复杂细节，开发者只需专注于业务逻辑的实现。

7.1 Java SDK集成示例

首先在Maven项目的pom.xml文件中添加依赖：

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>dysmsapi20170525</artifactId>
    <version>2.0.24</version>
</dependency>

Java代码示例：

import com.aliyun.dysmsapi20170525.Client;
import com.aliyun.dysmsapi20170525.models.SendSmsRequest;
import com.aliyun.dysmsapi20170525.models.SendSmsResponse;
import com.aliyun.teaopenapi.models.Config;

public class SmsDemo {
    public static void main(String[] args) throws Exception {
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
            .setEndpoint("dysmsapi.aliyuncs.com");
        
        Client client = new Client(config);
        
        SendSmsRequest request = new SendSmsRequest()
            .setPhoneNumbers("13800000000")
            .setSignName("阿里云")
            .setTemplateCode("SMS_123456789")
            .setTemplateParam("{\"code\":\"123456\"}");
        
        SendSmsResponse response = client.sendSms(request);
        System.out.println("RequestId: " + response.getBody().getRequestId());
        System.out.println("Code: " + response.getBody().getCode());
        System.out.println("Message: " + response.getBody().getMessage());
    }
}

7.2 Python SDK集成示例

首先使用pip安装SDK：

pip install alibabacloud_dysmsapi20170525

Python代码示例：

import os
from alibabacloud_dysmsapi20170525.client import Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dysmsapi20170525 import models as dysmsapi_models

config = open_api_models.Config(
    access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    endpoint='dysmsapi.aliyuncs.com'
)

client = Client(config)

request = dysmsapi_models.SendSmsRequest(
    phone_numbers='13800000000',
    sign_name='阿里云',
    template_code='SMS_123456789',
    template_param='{"code":"123456"}'
)

response = client.send_sms(request)
print(f'RequestId: {response.body.request_id}')
print(f'Code: {response.body.code}')
print(f'Message: {response.body.message}')

7.3 Go SDK集成示例

首先安装Go依赖：

go get github.com/aliyun/alibaba-cloud-sdk-go/services/dysmsapi

Go代码示例：

package main

import (
    "fmt"
    "os"
    dysmsapi "github.com/aliyun/alibaba-cloud-sdk-go/services/dysmsapi"
)

func main() {
    client, err := dysmsapi.NewClientWithAccessKey(
        "cn-hangzhou",
        os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
        os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    )
    if err != nil {
        fmt.Println(err)
        return
    }

    request := dysmsapi.CreateSendSmsRequest()
    request.PhoneNumbers = "13800000000"
    request.SignName = "阿里云"
    request.TemplateCode = "SMS_123456789"
    request.TemplateParam = `{"code":"123456"}`

    response, err := client.SendSms(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response.RequestId)
}

7.4 PHP SDK集成示例

使用Composer安装SDK：

composer require alibabacloud/dysmsapi-20170525

PHP代码示例：

<?php
require_once 'vendor/autoload.php';

use AlibabaCloud\Client\AlibabaCloud;
use AlibabaCloud\Client\Exception\ClientException;
use AlibabaCloud\Client\Exception\ServerException;

AlibabaCloud::accessKeyClient(
    getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET')
)->regionId('cn-hangzhou')->asDefaultClient();

try {
    $result = AlibabaCloud::rpc()
        ->product('Dysmsapi')
        ->version('2017-05-25')
        ->action('SendSms')
        ->method('POST')
        ->options([
            'query' => [
                'PhoneNumbers' => '13800000000',
                'SignName' => '阿里云',
                'TemplateCode' => 'SMS_123456789',
                'TemplateParam' => '{"code":"123456"}',
            ],
        ])
        ->request();
    print_r($result->toArray());
} catch (ClientException $e) {
    echo $e->getErrorMessage() . PHP_EOL;
} catch (ServerException $e) {
    echo $e->getErrorMessage() . PHP_EOL;
}

7.5 Node.js/TypeScript SDK集成示例

使用npm安装SDK：

npm install @alicloud/dysmsapi20170525 -S

Node.js代码示例：

const { Client } = require('@alicloud/dysmsapi20170525');

const client = new Client({
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    regionId: 'cn-hangzhou',
    endpoint: 'dysmsapi.aliyuncs.com'
});

async function sendSms() {
    try {
        const request = {
            phoneNumbers: '13800000000',
            signName: '阿里云',
            templateCode: 'SMS_123456789',
            templateParam: JSON.stringify({ code: '123456' })
        };
        const response = await client.sendSms(request);
        console.log('RequestId:', response.body.requestId);
        console.log('Code:', response.body.code);
        console.log('Message:', response.body.message);
    } catch (error) {
        console.error(error);
    }
}

sendSms();

八、回执消息配置

回执消息是在使用API接口发送短信之后，通过配置轻量消息队列（原MNS）消费模式或HTTP批量推送模式，帮助开发者掌握短信的发送成功率。短信服务接收回执消息的模式有两种：

• 轻量消息队列（原MNS）消费模式：通过Queue模型来接收指定地域的短信回执消息
• HTTP批量推送模式：通过HTTP POST方式发送消息到指定的Web URL

配置回执消息的步骤：

• 在短信服务控制台的通用设置页面，单击接口API页签
• 在云通信消息接收区域，开启指定模式（轻量消息队列或HTTP批量推送）
• 填写接收地址，地址示例：http://push.example.com/contextpath/receive.do
• 单击保存

需要注意的是，如果出现网络异常、响应超时等情况，可能导致回执消息推送重复、回执消息获取失败等问题。回执消息无法保证幂等性，因此需要自行处理幂等性的问题。

九、常见错误码排查

调用短信服务API接口失败时会返回错误码，以下列出常见的错误码及解决方案：

• OK：成功
• INVALID_SENDERID：SenderID无效，请联系平台解决
• OUT_OF_SERVICE：国际短信业务停机，请联系平台解决
• ACCOUNT_NOT_EXISTS：账户信息不存在，请确认是否开通短信服务
• SMS_SIGN_NAME_ILLEGAL：签名不合法（不存在或被拉黑），请申请新的签名
• MOBILE_NUMBER_ILLEGAL：手机号码格式错误，请校验号码格式
• CONTENT_MISSING_PARAMETERS：模板变量缺少对应参数值，请传入正确的参数值
• AMOUNT_NOT_ENOUGH：资源包或额度不足，请购买套餐包或充值余额
• QPS_LIMIT_CONTROL：到达系统QPS发送限制，已达到单用户QPS上限
• RAM_PERMISSION_DENY：RAM校验失败，用户权限不足，请授权RAM调用接口权限
• PRODUCT_NOT_SUBSCRIBED：短信服务没开通，请在控制台开通短信服务
• FREQUENCY_LIMIT_DAY：到达单个号码每日发送频率限制（上限20条）

十、QPS限流与频率控制

国际短信服务的QPS（每秒请求次数）限额基于付费模式设定：

• 套餐包模式：单用户QPS限制为30次/秒
• 按量付费模式：单用户QPS限制为2000次/秒

同一主账号及其所有RAM用户共享上述QPS限额，通过API或控制台发送的请求均纳入QPS限额计算。单号码限频为1天20条。

十一、国际短信注意事项

发往国际地区的短信，需要确认短信发送目标地是否需要报备SenderID。发往国际地区和中国香港、中国澳门和中国台湾地区，调用SendMessageToGlobe接口；批量发送调用BatchSendMessageToGlobe接口。

部分国家有特殊要求：

• 印度：需要完成DLT注册
• 沙特阿拉伯：需要预注册SenderID
• 美国/加拿大：推荐使用当地号码（长码/短码）以提高到达率

十二、成本优化建议

短信服务使用全流程中，仅在发送短信时产生费用。建议根据业务需要选择最优的计费方案：

• 购买资源包：如果发送量较大，购买资源包比按量付费更划算
• 合理规划发送节奏：避免在高峰期集中发送导致QPS限流
• 监控账户余额：及时充值或续费资源包，避免因余额不足导致发送失败

十三、总结

阿里云短信服务的对接使用涉及账号准备、资质申请、签名申请、模板申请、API集成、回执配置等多个环节。本文从零开始完整拆解了整个接入链路，并提供了Java、Python、Go、PHP、Node.js五种主流开发语言的SDK集成示例。通过遵循安全最佳实践（使用RAM子账号、环境变量存储AccessKey）、合理配置回执消息、熟悉常见错误码的排查方法，开发者可以快速、安全、低成本地完成短信服务的对接使用。

常见问题问答

问：个人认证用户能否使用阿里云短信服务？
答：阿里云短信服务目前仅支持企业认证账号使用。个人认证用户功能受限，无法发送营销短信，且可能影响签名审核通过率。

问：短信签名和模板审核需要多长时间？
答：短信签名在工作时间提交最快24小时审核完成，短信模板审核约2至4小时。从2025年起，中国大陆新增短信签名还需额外完成运营商实名报备（5至10个工作日）。

问：调用SendSms接口返回OK但用户未收到短信怎么办？
答：返回OK仅表示请求成功，不代表短信已送达。需登录短信服务控制台，在业务统计 > 发送记录页面查看该条短信的运营商回执错误码，根据错误码定位具体失败原因。

问：如何配置接收短信的回执消息？
答：在短信服务控制台的通用设置页面，开启轻量消息队列（原MNS）消费模式或HTTP批量推送模式，填写回调URL地址后保存即可。

问：AccessKey应该放在代码中吗？
答：不应该。强烈建议使用环境变量存储AccessKey，禁止硬编码在工程代码中，否则可能导致AK泄露。

问：国际短信的QPS限制是多少？
答：套餐包模式下单用户QPS限制为30次/秒，按量付费模式下为2000次/秒。同一主账号及其所有RAM用户共享该限额。