Skip to main content
注册
首页/文档中心/开发者中心/国内短信 API

国内短信 API

v2接口 v2

短信宝 v2 API 提供简洁的 JSON 格式接口，支持短信发送、余额查询等核心功能。接口统一使用 JSON 返回格式，便于业务系统按状态码、描述信息和 data 数据统一处理。

查看短信发送接口查看余额查询接口查看接口 v1

接口概览

项目说明
接口域名https://api.smsbao.com
返回格式统一 JSON 格式，包含 code、msg、data 字段。
接口特点支持任务 ID 跟踪、统一错误处理、简洁易用的接口设计。
参数编码所有参数使用 UTF-8 编码，短信内容建议进行 URL Encode。
  • 用户可访问 https://www.smsbao.com/ 自助注册账号、充值。
  • 建议先在短信宝后台报备短信模板，审核通过后再进行正式发送。
  • 群发短信可能进入人工审核；测试时建议先使用单个号码，便于确认接收速度和返回结果。

短信发送接口

GET https://api.smsbao.com/api/v2/sms
?username=USERNAME
&secret=SECRET
&to=PHONE
&content=CONTENT
&product=PRODUCT
参数名类型必填说明
usernameString是短信宝用户名。
secretString是短信宝密钥。
toString是手机号码；多个号码使用英文逗号分隔。
contentString是短信内容，建议使用 UTF-8 URL Encode。
productString否产品类型；不传时使用默认产品。

请求示例

curl -X GET "https://api.smsbao.com/api/v2/sms?username=your_username&secret=your_secret&to=13800138000,13800138001&content=%E3%80%90%E7%9F%AD%E4%BF%A1%E5%AE%9D%E3%80%91%E6%82%A8%E7%9A%84%E9%AA%8C%E8%AF%81%E7%A0%81%E6%98%AF1234%EF%BC%8C5%E5%88%86%E9%92%9F%E5%86%85%E6%9C%89%E6%95%88%E3%80%82"

返回示例

{
"code": 0,
"msg": "短信发送成功",
"data": {
  "taskId": "202401011200001"
}
}

余额查询接口

GET https://api.smsbao.com/api/v2/balance
?username=USERNAME
&secret=SECRET
&product=PRODUCT
参数名类型必填说明
usernameString是短信宝用户名。
secretString是短信宝密钥。
productString否产品类型；不传时使用默认产品。

请求示例

curl -X GET "https://api.smsbao.com/api/v2/balance?username=your_username&secret=your_secret"

返回示例

{
"code": 0,
"msg": "查询成功",
"data": {
  "balance": 1000.50
}
}

统一返回格式

所有 v2 接口均返回统一 JSON 格式：

{
"code": 0,
"msg": "描述信息",
"data": {}
}
字段说明
code状态码；0 表示成功，非 0 表示失败。
msg状态描述或错误描述。
data接口返回数据，具体结构因接口而异；失败时可能为 null。

状态码说明

状态码说明
0成功。
30请求参数不全。
40账号或密码错误。
41余额不足。
42账号已过期。
43IP 地址限制。
44账号已被禁用。
51内容含有敏感词。
52手机号码格式不正确。
53没有可用的短信产品。
54试用账号无权调用此接口。
55错误的账号。
70模板格式不正确。
71验签失败。

错误处理

错误返回示例

{
"code": 40,
"msg": "账号或密码错误",
"data": null
}
  • 先检查 HTTP 状态码是否为 200。
  • 解析 JSON 响应，读取 code、msg 和 data 字段。
  • code 为 0 表示接口处理成功；非 0 时按状态码和 msg 进行排查。
  • 对网络异常、超时等临时错误，可按业务场景进行有限次数重试。

短信接收推送 API

短信宝会通过客户提供的 URL，实时推送用户回复短信。客户需要提供一个可接收 HTTP GET 请求的 URL，并在短信宝后台配置。

参数名类型必填说明
mString是发送方手机号。
cString是用户回复的短信内容，采用 UTF-8 URL 编码。
sString否扩展号。
  • 访问方式：GET，短信宝推送到客户系统。
  • 客户系统处理成功后请返回字符串 0，其他返回值会被认为处理失败。
  • 若接口 1 小时内累计调用 10 次都获取不到正确返回值，将暂停推送 1 小时。

短信状态报告推送 API

短信宝会通过客户提供的 URL，实时推送短信发送状态报告。客户需要提供一个可接收 HTTP GET 请求的 URL，并在短信宝后台配置。

参数名类型必填说明
tString是短信发送时短信宝反馈的任务 ID。
mString是接收方手机号码。
sString是状态；1 表示短信已送达，-1 表示短信下发失败。
dString是状态详情。
  • 访问方式：GET，短信宝推送到客户系统。
  • 客户系统处理成功后请返回字符串 0，其他返回值会被认为处理失败。
  • 若接口 1 小时内累计调用 10 次都获取不到正确返回值，将暂停推送 1 小时。

内部状态报告代码

状态码说明
LO:0103余额不足。
LO:0800没有合适的通道可用。
LO:0801网关转发短信提交失败。
LO:0802网关连接异常。
LO:0803号码不正确。
LO:0804敏感字。
LO:0805黑名单。
LO:0806敏感字。
LO:0807通道不支持长短信。
LO:0808产品代码不正确或国际余额不足。
LO:0809相同号码发送间隔时间低于限制值。
LO:0810相同号码一天接收次数超过限制值。
LO:0900审核否决。

开发建议与注意事项

  • 建议设置请求超时时间为 30 秒。
  • 对于网络异常等临时错误，建议实现重试机制，最大重试次数不超过 3 次。
  • 所有参数使用 UTF-8 编码，短信内容建议进行 URL Encode。
  • 单条短信内容建议不超过 64 个字符，长短信建议不要超过 320 个字符。
  • 验证码短信建议在手机验证环节增加图片验证码，避免被恶意攻击。
  • 接口调用频率建议不要超过 1 次 / 分钟。
  • 接口要求提前在短信宝后台添加短信模板；提交短信时系统会自动匹配审核通过的模板，匹配成功后才能发送。

技术支持