短信接口快速接入

这是一条面向第一次接入的最短路径：先准备账号和 API 信息，再选择接口 v1 或接口 v2，随后准备签名模板并发送测试短信，最后在业务系统中处理返回结果、记录日志并完成上线前检查。

选择接口版本接口 v1接口 v2

接入目标

• 完成账号、接口信息、签名模板、测试手机号和测试内容准备。
• 明确当前业务使用接口 v1 还是接口 v2，避免参数名和返回格式混用。
• 先通过控制台发送一条测试短信，确认账号和内容链路可用。
• 再在业务系统中完成 API 调用、返回值处理、日志记录和失败排查。

准备工作

准备项	需要确认的内容	为什么重要
账号权限	可以登录控制台，并能查看 API 信息、发送测试、查询记录。	避免开发联调时被权限或账号状态卡住。
接口版本	确认使用 v1 文本返回接口，还是 v2 JSON 返回接口。	两个版本的参数名、返回格式和错误码含义不同。
API 信息	接口账号、接口密钥、请求地址、请求方式、字符编码。	这是后端调用短信接口的基础参数。
短信签名	签名名称、主体资料、业务场景是否一致。	签名不规范会影响模板审核和正式发送。
短信模板	固定文案、变量位置、验证码有效期或通知内容。	模板决定短信内容能否稳定复用。
业务日志	记录请求参数摘要、返回码、业务订单号和用户手机号脱敏信息。	上线后排查失败和重复发送问题。

选择接口版本

版本	请求地址	参数	返回结果	建议
v1	https://api.smsbao.com/sms	u、p、m、c、g	文本返回码，0 表示提交成功。	已接入 v1 的系统继续使用。
v2	https://api.smsbao.com/api/v2/sms	username、secret、to、content、product	JSON，code 为 0 表示成功。	新系统优先使用，便于统一处理 code、msg、data。

快速接入步骤

步骤	操作	完成标准
1. 登录控制台	注册或登录短信宝账号，进入控制台。	能正常查看账号信息和发送相关功能。
2. 获取 API 信息	找到接口账号、接口密钥和 API 文档页面。	后端拿到联调所需的基础参数。
3. 选择 v1 / v2	按业务系统约定选择接口版本，并固定返回处理逻辑。	代码中不会混用 v1 的文本返回和 v2 的 JSON 返回。
4. 准备签名与模板	根据验证码、通知或营销场景准备签名和模板内容。	测试短信内容与正式业务内容方向一致。
5. 控制台测试	在控制台填写手机号和短信内容，发送一条测试短信。	能在发送记录中看到提交结果。
6. 调用 API	按对应版本文档拼装请求参数，处理接口返回值。	业务系统能提交短信请求并记录返回结果。
7. 对照错误码排查	如果接口返回错误码，查看对应版本的错误码说明。	错误能够被开发侧快速定位并修正。
8. 上线前检查	检查余额、模板、频控、日志、状态报告和客服排查路径。	正式流量接入前风险可控。

API 联调检查

• 请求地址、请求方式、参数名和编码方式必须和所选版本一致。
• 账号和密钥不要写在前端代码中，建议放在服务端配置或密钥管理中。
• 接口 v1 判断文本返回码；接口 v2 解析 JSON 后判断 code 字段。
• 验证码类短信建议设置业务侧频控，避免重复发送、刷接口或被用户连续触发。
• 不要只依赖“接口提交成功”判断用户已收到短信，最终结果要结合发送记录或状态报告。

下一步

国内短信 API v1进入 v1 参数、返回值和示例说明。国内短信 API v2进入 v2 JSON 接口和状态码说明。代码示例按语言复制 v1 或 v2 调用样例。错误码说明按接口版本建立失败排查和处理动作。状态报告 / 发送记录 API把发送结果接回业务系统。