三网短信发送接口技术解析：接入流程、参数设计与返回结构

一、技术简介

三网短信服务接口是一种基于 HTTP/HTTPS 的短消息发送能力，覆盖中国移动、中国联通、中国电信三网号码以及虚拟运营商号段，用于向终端手机号下发文本短信。该能力通过阿里云云市场 API 网关统一暴露，调用方以 APPCODE 方式完成身份认证后即可发起请求。

从技术视角看，它解决的是「业务系统 → 运营商短信网关」之间的消息投递问题：开发者无需分别与各家运营商对接，只需面向统一的网关地址提交手机号与内容，由网关完成三网路由与下发。典型用途包括注册/登录验证码、业务状态通知、触发类消息与公共事务提醒。

二、能力概览

下表列出接口开放的主要能力，便于在接入前做技术选型。

三、适用场景

• 身份校验：在用户注册、登录、敏感操作环节下发动态验证码，核对手机号与操作人一致性。
• 业务通知：订单生成、物流更新、缴费提醒等状态变更时主动推送，保证用户及时获知。
• 触发消息：系统异常、任务完成、阈值告警等事件驱动型短信，由业务流程自动触发。
• 公共事务提醒：政务、社区、校园等场景的批量告知，按号段批量提交。

上述场景描述的是技术数据流（业务系统产生事件 → 调用接口 → 网关投递 → 终端接收），不涉及业务收益或量化效果的表述。

四、接入流程

4.1 前置准备

1. 在阿里云云市场完成商品订购，获取调用所需的 APPCODE。
2. 完成企业实名认证（该接口仅对企业用户开放）。
3. 在控制台创建并报备短信签名，必要时创建短信模板。

4.2 请求参数

发送短信接口以 GET 方式调用，主要参数通过 Query 传递：

4.3 调用地址与鉴权

• 请求地址：https://duanxi.market.alicloudapi.com/sendSms
• 请求方式：GET
• 返回类型：JSON
• 鉴权方式：请求头 Authorization: APPCODE <appcode>

调用地址以商品页给出的接入地址为准；APPCODE 为该接口网关的标准认证密钥，请勿与 AppKey 混淆。

五、调用示例与返回结构

5.1 Java 示例

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

public class SmsDemo {
   
    public static void main(String[] args) throws Exception {
   
        String host = "https://duanxi.market.alicloudapi.com";
        String path = "/sendSms";
        String appcode = "<appcode>";
        String mobile = "13800000000";
        String content = URLEncoder.encode("name**:张三@@code**:1234", "UTF-8");

        String url = host + path + "?mobile=" + mobile + "&content=" + content;
        HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("Authorization", "APPCODE " + appcode);

        BufferedReader br = new BufferedReader(
            new InputStreamReader(conn.getInputStream(), "UTF-8"));
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) sb.append(line);
        br.close();
        System.out.println(sb.toString());
    }
}

5.2 PHP 示例

<?php
$host = "https://duanxi.market.alicloudapi.com";
$path = "/sendSms";
$appcode = "<appcode>";
$mobile = "13800000000";
$content = urlencode("name**:张三@@code**:1234");

$url = $host . $path . "?mobile=" . $mobile . "&content=" . $content;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: APPCODE " . $appcode));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;
?>

5.3 Python 示例

import urllib.request
import urllib.parse

host = "https://duanxi.market.alicloudapi.com"
path = "/sendSms"
appcode = "<appcode>"
params = {
   
    "mobile": "13800000000",
    "content": "name**:张三@@code**:1234",
}
query = urllib.parse.urlencode(params)
url = host + path + "?" + query

req = urllib.request.Request(url)
req.add_header("Authorization", "APPCODE " + appcode)
with urllib.request.urlopen(req, timeout=10) as resp:
    print(resp.read().decode("utf-8"))

5.4 Node.js 示例

const https = require("https");
const appcode = "<appcode>";
const params = new URLSearchParams({
   
  mobile: "13800000000",
  content: "name**:张三@@code**:1234",
});
const url = `https://duanxi.market.alicloudapi.com/sendSms?${
     params.toString()}`;

https.get(url, {
    headers: {
    Authorization: `APPCODE ${
     appcode}` } }, (res) => {
   
  let data = "";
  res.on("data", (c) => (data += c));
  res.on("end", () => console.log(data));
});

5.5 返回结构

接口以 JSON 返回调用结果。以下为典型结构示例，实际字段以接口实时返回为准：

{
   
  "code": 0,
  "msg": "提交成功",
  "data": {
   
    "taskId": "SMS20260918xxxxxxxx",
    "mobile": "138****0000",
    "fee": 1
  }
}

字段说明：

六、在线调试实录

在商品页的 API 调试面板中，选择「发送短信」操作后，可按如下步骤完成一次技术走查：

1. 在 Query 区域填入 mobile（必填，11 位手机号）。
2. 在 content 中填入模板变量串，例如 name**:张三@@code**:1234；若使用已创建模板，则填入 tNum 或 tNumAlias。
3. 在请求头填入 Authorization: APPCODE <appcode>。
4. 点击「发起请求」，观察返回 JSON 中的 code 与 data.taskId。
5. 以 taskId 在「短信发送历史」中核对下发状态。

调试过程中若返回非 200 HTTP 状态码，本次调用不计入次数扣减（仅 200 成功响应才扣减配额）。

七、接口调用限制与规范

• 配额与限流：单账户存在 QPS 上限与每日调用配额，具体数值以控制台实时配置为准；高频调用建议在客户端做队列与限流。
• 认证要求：仅对企业用户开放，使用前需完成企业实名认证。
• 编码规范：content 字段涉及中文时必须采用 UTF-8 编码，部分 HTTP 客户端或语言已默认编码，需避免二次编码导致乱码。
• 次数扣减规则：仅当网关返回 HTTP 200 时扣减调用次数，非 200 不扣费。
• 内容合规：短信正文与签名须符合通信管理相关规定，签名需提前报备；下发内容不得包含违规信息。
• 号码格式：mobile 须为合法 11 位国内手机号，虚拟运营商号段同样在覆盖范围内。

八、能力边界与免责声明

支持范围

• 国内三网（移动 / 联通 / 电信）及虚拟运营商号段的文本短信下发。
• 验证码、通知、触发三类消息。
• 签名与模板的创建、修改、查询、删除等管理操作。

不支持范围

• 国际及港澳台短信下发。
• 富媒体（彩信 / 语音 / 卡片消息）等非文本短信。
• 号段外的特殊通道或定制化私有网关接入。

免责声明

短信是否最终送达受运营商网络、终端状态、用户退订与内容合规等多因素影响，接口返回成功表示「已提交网关」，不代表终端一定收到。接口数据仅供参考，不对基于短信触达的任何业务决策或损失承担责任。

九、错误码与排查指南

十、常见问题 FAQ

Q1：发送短信必须创建模板吗？
不一定。直接传入 content 文本即可下发；若需复用规范化内容并做变量替换，可先在控制台创建模板，再以 tNum 或 tNumAlias 引用。

Q2：content 的变量怎么写？
支持两种写法：键值对 name**:张三@@code**:1234（多组以 @@ 分隔），或 JSON {"itfName":"验证码识别","num":"50"}，模板正文以 [变量名] 占位。

Q3：返回成功但用户没收到短信？
接口成功仅表示已提交网关。送达受运营商网络、终端关机、用户退订等因素影响，可用 taskId 在发送历史中核对状态。

Q4：支持并发批量发送吗？
支持较高并发的批量提交，但受账户 QPS 与每日配额约束，建议在客户端做队列与限流，避免触发网关限流。

Q5：调用次数什么情况下会扣减？
仅当网关返回 HTTP 200 时扣减调用次数，非 200 响应不计入调用次数。

Q6：支持哪些号段？
覆盖国内移动、联通、电信三网及虚拟运营商号段；国际及港澳台不在支持范围。

十一、内容小结

三网短信发送接口通过阿里云云市场 API 网关以 APPCODE 鉴权暴露，核心操作为 GET /sendSms，以 mobile 指定接收号、content 承载正文（支持键值对或 JSON 变量模板），并以 tNum / tNumAlias 引用已创建模板。接入前需完成企业认证与签名报备，调用时注意 UTF-8 编码与限流，结果以 taskId 在对账与历史查询中核对。发送结果表示「已提交」，终端送达受多重因素影响，工程上应配合重试、限流与状态核对以保证可靠性。