
## 一、接口基础信息与核心规范

### 1.1 接口核心属性

营销短信批量提交接口的核心交互规则需严格遵循以下规范，这是保障接口调用成功的基础：

- **请求方法**：仅支持**POST**方法，不兼容 GET 传参方式，避免因请求方式不符导致调用失败。

- **字符编码**：统一要求为**UTF-8**，所有请求参数（包括手机号、短信内容、签名等）均需按此编码传输，防止出现中文乱码问题。

### 1.2 核心依赖参数前置说明

接口调用前需完成基础参数配置，其中 APIID 与 APIKEY 是身份验证的核心凭证，需从用户中心的【文本短信】-【会员营销短信】-【产品总览】页面获取。若参数配置错误，后续所有请求都会直接返回身份验证失败的响应，这也是开发者集成初期最常见的错误来源。

## 二、请求参数详细定义与校验规则

### 2.1 请求头参数（Header）

请求头仅需配置 1 个固定参数，用于声明数据格式：

表格

|参数名称|参数值描述|示例|类型|必填|
|:-:|:-:|:-:|:-:|:-:|
|Content-Type|内容类型，固定值|application/json|string|是|

### 2.2 请求体核心参数（Body）

请求体为 JSON 格式，包含身份验证、短信内容、发送控制等多类参数，各参数校验规则如下：
表格
|参数名称|参数值描述|示例|类型|必填|核心校验规则|
|:-:|:-:|:-:|:-:|:-:|:-:|
|api_id|API 身份标识|sms-yx-xxxxxxxx|string|是|与用户中心获取的 APIID 完全一致，长度固定|
|signature|请求验证加密签名|xxxxxxxxx|string|是|按指定规则生成，32 位小写 MD5 值，防止参数篡改|
|timestamp|东八时区 10 位时间戳|1623643787|int|是|与当前时间相差不超过 ±60S，超时则判定为无效请求|
|request_id|请求方唯一 ID|xxxxxxxxxxxx|string|是|建议用 UUID 生成，2 小时内重复会被系统去重，防止重复攻击|
|product_id|产品功能 ID|1001|int|是|固定为营销短信专属产品 ID，不可随意修改|
|phone|手机号数组|["136****8888","138****9999"]|array|是|最多支持 1 万个号码，格式为标准 11 位手机号|
|sign_name|短信签名|xxxxxxxx|string|是（template_id 为空时）|需与平台备案签名一致，否则短信会被拦截|
|content|短信内容|尊敬的会员您好：，您的订单号是：{order_no}，拒收请回复 R|string|是（template_id 为空时）|与签名、模板合规，变量需与 template_var 对应|
|template_id|模板 ID|1|int|否|与 content 二选一必填，填写后 content 参数失效|
|template_var|模板变量值|{"张三{order_no}":"202009041156181103"}|object|否|仅变量模板必填，需为标准 JSON 格式，变量名与模板一致|
|send_time|定时发送时间|2020-08-26 16:08:14|string|否|为空则立即发送，需为东八时区合法时间格式|

### 2.3 签名生成核心规则

**signature**参数的生成是接口安全验证的关键，必须严格遵循以下步骤：

1. 提取公共参数（api_id、api_key、request_id、timestamp）；

2. 将参数按**ASCII 码从小到大**排序，拼接为`key=value&key=value`格式（如`api_id=xxxx&api_key=xxxx&request_id=xxxx&timestamp=xxxx`）；

3. 对拼接后的字符串进行**MD5 加密**，生成 32 位小写字符串，即为最终的 signature 值。

## 三、接口响应规则与返回码解析

### 3.1 响应数据结构

接口响应为标准 JSON 格式，包含状态码、消息描述和业务 ID，核心字段定义如下：
表格
|参数名称|参数值描述|示例|类型|必返|
|:-:|:-:|:-:|:-:|:-:|
|code|状态码|OK/ParamError|string|是||
|message|消息描述|请求成功 / 参数错误|string|是||
|task_id|下发批次 ID|123/0|string|否|回执查询、问题排查的核心标识|

### 3.2 全量返回码含义与排查方案

不同返回码对应不同的错误类型，开发者可根据返回码快速定位问题，以下为高频返回码及解决方案：
表格
|code|含义|排查方向|
|:-:|:-:|:-:|
|OK|请求成功|无需排查，短信进入下发队列|
|ParamError|参数错误|检查参数格式、必填项是否缺失、值是否合规|
|AccessKeyIDNotExist|APIID 不存在|核对 api_id 是否与用户中心一致，是否已获取对应权限|
|UserIDNotExist|用户 ID 不存在|确认账号状态正常，是否完成企业实名认证|
|AmountError|余额不足|充值短信余额，确保余额满足本次批量发送需求|
|TimestampError|时间错误|同步本地服务器时间，确保 timestamp 在 ±60S 范围内|
|ProductIDNotExist|产品 ID 不存在|确认 product_id 为 1001，是否开通营销短信功能|
|SignError|签名错误|检查 signature 生成规则是否正确，参数排序、MD5 加密是否无误|
|SignExpired|签名过期|重新生成 signature，确保 timestamp 未超时|
|BalanceNotEnough|余额不足|及时充值，避免因余额不足导致发送中断|
|SystemError|系统异常|稍后重试，或联系技术支持排查服务端问题|

## 四、实战代码示例与配置要点

### 4.1 PHP 生成动态密码（签名）示例

以下代码展示了按规则生成 signature 的核心逻辑
php
运行
```
<?php
$api_id = 'sms-yx-xxxxxxxx'; // 营销短信APIID
$api_key = 'xxxxxxxxxxxxxxxx'; // 营销短信APIKEY
$request_id = uniqid(); // 生成唯一请求ID，推荐用UUID
$timestamp = time(); // 获取当前10位时间戳（东八时区）

// 按ASCII码排序拼接参数
$param_str = "api_id={$api_id}&api_key={$api_key}&request_id={$request_id}&timestamp={$timestamp}";

// 生成MD5签名（32位小写）
$signature = md5($param_str);

// 输出签名结果
echo "生成的signature：{$signature}";
?>
```

### 4.2 完整请求示例（PHP）

结合参数校验与签名生成，实现完整的营销短信批量发送请求：
php
运行
```
<?php
// 核心配置
$api_id = 'sms-yx-xxxxxxxx';
$api_key = 'xxxxxxxxxxxxxxxx';
$request_id = uniqid();
$timestamp = time();
$signature = md5("api_id={$api_id}&api_key={$api_key}&request_id={$request_id}&timestamp={$timestamp}");

// 请求参数组装
$request_data = [
    'api_id' => $api_id,
    'signature' => $signature,
    'timestamp' => $timestamp,
    'request_id' => $request_id,
    'product_id' => 1001,
    'phone' => ["136****8888", "138****9999"], // 批量手机号数组
    'sign_name' => '企业官方签名',
    'content' => '【企业官方签名】您的会员权益已更新，登录APP查看详情，回复T退订',
    'template_id' => '', // 无需模板则留空，填写则content失效
    'template_var' => new stdClass(), // 非变量模板传空对象
    'send_time' => '' // 立即发送留空，定时发送填"2020-08-26 16:08:14"
];

// 初始化CURL请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_data, JSON_UNESCAPED_UNICODE));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 生产环境建议开启SSL验证
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

// 执行请求并获取响应
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// 处理响应结果
if ($http_code == 200) {
    $result = json_decode($response, true);
    if ($result['code'] == 'OK') {
        echo "发送成功，批次ID：{$result['task_id']}";
    } else {
        echo "发送失败，错误码：{$result['code']}，错误信息：{$result['message']}";
    }
} else {
    echo "请求异常，HTTP状态码：{$http_code}";
}
?>
```

## 五、开发实战技巧与异常排查

### 5.1 高频开发技巧

1. **参数校验前置**：调用接口前，先对手机号格式、签名长度、时间戳范围进行本地校验，减少无效请求，提升接口调用效率。

2. **请求 ID 复用策略**：可将 request_id 与业务订单号关联，便于后续通过 request_id 追溯短信发送记录，快速定位问题。

3. **批量发送优化**：单次请求手机号数量建议控制在 5000 以内，避免因数据量过大导致请求超时，可分批次发送。

4. **异常重试机制**：针对 SystemError、Timeout 等临时异常，设置 3 次重试策略，重试间隔从 1 秒逐步递增至 5 秒，降低请求失败率。

### 5.2 常见异常排查清单

1. **中文乱码**：检查请求头是否指定 UTF-8 编码，参数传输前是否进行 URL 编码或 JSON 转义。

2. **签名验证失败**：核对参数排序是否按 ASCII 码、MD5 加密是否为小写、api_key 与 api_id 是否匹配。

3. **短信被拦截**：确认签名已在平台备案、短信内容未包含违规关键词、手机号未处于黑名单。

4. **定时发送失败**：检查 send_time 格式是否为 “YYYY-MM-DD HH:MM:SS”，时间是否早于当前时间。

营销短信批量提交接口的核心交互规则需严格遵循以下规范，这是保障接口调用成功的基础：

营销短信接口 API 参考手册：面向开发者的字段定义、返回码及接口文档

在企业数字化运营中，营销短信是触达用户、传递活动信息的核心渠道，而**营销短信接口 API**则是实现系统与短信服务高效对接的关键桥梁。本文档面向前端、后端及全栈技术开发者，全面拆解营销短信接口的字段定义、请求响应规则、返回码含义及实战配置要点，帮助开发者快速完成接口集成，解决批量短信发送、参数校验、异常排查等核心开发痛点。

云计算

营销短信批量提交接口规范详解，包含POST请求方法、UTF-8编码要求、API身份验证、签名生成规则等核心参数配置。提供PHP代码示例，解析高频返回码及解决方案，帮助开发者快速集成营销短信功能，确保批量发送成功率。

身份验证

数据结构

服务器

短信

JSON

2026采购季 | AI焕新·智启新局

人脸核身+人脸识别特惠活动0.6折起


faceid

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

营销短信接口 API 参考手册：面向开发者的字段定义、返回码及接口文档-腾讯云开发者社区-腾讯云

营销短信接口 API 参考手册：面向开发者的字段定义、返回码及接口文档

营销短信接口 API 参考手册：面向开发者的字段定义、返回码及接口文档

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐