更新时间：2025-11-19 16:28:21
| 准备事项 | 说明 |
|---|---|
| 完成企业认证+实名认证 | 根据运营商实名发送短信的要求，使用国内文本短信之前需要登录控制台完成企业认证 + 实名认证。否则无法报备签名以及使用。 |
| API账号和密码 | 调用短信接口需要用到的账号和密码，获取的方式可查看控制台操作指引。 |
| 加白请求ip | 需要在控制台的"产品配置"目录下绑定您的服务器公网出口IP，否则我方接口将会拦截您的请求致使短信提交失败。配置方式可查看控制台操作指引，绑定IP能够有效防止盗发。 |
| 短信签名 | 完成签名申请并审核通过后，获取签名名称，含签名标识的括号：【】，使用未审核通过的签名，接口会拦截并报错。 |
| 短信模板ID | 完成模板申请并审核通过后，获取模板完整内容(含变量大小)。使用未审核通过的内容，验证码账号会默认拦截并报错，其他类型账号不会拦截报错，但会进入人工审核，由审核人员决定是否下发。 |
| 短信类型 | 短信格式 | 短信内容示例 |
|---|---|---|
| 验证码短信 | 【短信签名】+ 正文(包含验证码文案) | 向用户手机发送： 【创蓝云智】您正在申请手机注册，验证码为：123456，5分钟内有效！ |
| 通知短信 | 【短信签名】+ 正文 | 向用户手机发送： 【创蓝云智】尊敬的客户，您购买的会员卡已于11月29日正式到期。如您要继续使用，请于11月29日前及时续费或重新购买。 |
| 会员营销短信 | 【短信签名】+ 正文 + 退订语 | 向用户手机发送： 【创蓝云智】双十一重磅来袭，晚20点抢600送600！详见www.chuanglan.com拒收请回复R。 |
- 请求方式：json 格式封装的字符串，采用 post 方式提交请求
- Content-Type：application/json
- 编码格式：utf-8
- 请求地址：
https://smssh.253.com/msg/sms/v2/tpl/send
复制成功public String makeSignature(String md5Password, String timestamp, String nonce) { String str = generateStr(md5Password, timestamp, nonce); return HmacUtils.hmacSha256Hex(md5Password, str.replaceAll("\\s+", "")); } /** * 签名待处理的字符串拼接 */ public static String generateStr(String md5Password, String timestamp, String nonce){ String[] array = new String[] { md5Password, timestamp, nonce}; StringBuffer sb = new StringBuffer(); // 字符串排序 Arrays.sort(array); for (int i = 0; i < 3; i++) { sb.append(array[i]); } return sb.toString(); }
| 参数名称 | 类型 | 是否必传 | 描述 | 示例 |
|---|---|---|---|---|
| X-QA-Hmac-Signature | String | 可选 | 使用上述加密鉴权时，传递makeSignature的结果，无需传递password。 不加密鉴权时，该Header填空字符串"",body里password必传。 | "nonce + md5Password(API密码的MD5的32位小写值)+ timestamp"(取决于排序结果) |
| 参数名称 | 类型 | 是否必传 | 描述 | 示例 |
|---|---|---|---|---|
| account | String | 是 | API 账号，登录控制台获取，获取方式请查阅控制台操作指引。 | "account":"N6000001" |
| password | String | 否 | API 密码，未开启加密鉴权时则为必传，登录控制台获取，获取方式请查阅控制台操作指引。 | "password":"123456" |
| nonce | String | 是 | 32位随机字符串 | "nonce":"2e6eceb5737b473284c930c8ef79090e" |
| timestamp | String | 是 | 秒级时间戳 | "timestamp":"1631865523" |
| phoneNumbers | String | 是 | 接收的手机号；多个手机号使用英文逗号间隔，一次不要超过 1000 个； | 批量群发"phoneNumbers":"15800000000,15300000000" |
| templateParamJson | String | 否 | 变量参数值，JSON数组格式，变量模板为必传。短信模板变量对应的实际值，多个手机号即传入多组 JSON对象，且传入每组对象的键名个数要与模板变量个数一致。 键名用param1，param2、param3、param4以此类增，param1对应第一个变量{s}，param2对应第二个。 - 示例： - 短信模板：尊敬的{s}，恭喜您成功充值{s}元。 - templateParamJson：[{\"param1\":\"张三\",\"param2\":\"13\"},{\"param1\":\"李四\",\"param2\":\"88\"}] 填充后的第一个手机号内容：尊敬的张三，恭喜您成功充值13元。 填充后的第二个手机号内容：尊敬的李四，恭喜您成功充值88元。 | "templateParamJson": "[ {\"param1\":\"张三\",\"param2\":\"13\"}, {\"param1\":\"李四\",\"param2\":\"88\"} ]" |
| templateId | String | 是 | 模版Id，模板跟单个API账号为绑定关系，不可混淆传入，可通过模板列表接口查询或登录控制台“模板管理”查看。 | "templateId":"1111111" |
| signature | String | 否 | 短信签名，如果之前报备的模板没有选择关联签名，则为必传，自己带上签名， 25年7月起最新的模板报备中会选择关联签名，则可以不用传递此参数。 | "signature":"【创蓝云智】" |
| report | String | 否 | 如您需要状态回执，则需要传"true",不传默认为"false"，则无法获取状态回执。 | "report":"true" |
| callbackUrl | String | 否 | 状态回执的回调地址，请传入完整带http协议头开头的地址，不传默认为空，请勿传入空格， 否则会造成地址推送错误。地址可通过接口入参传入，也可在控制台手动配置， 可查看控制台操作指引。 | "callbackUrl":"https://" |
| uid | String | 否 | 自定义参数，如订单号或短信发送记录流水号，最大支持256位，状态回执会回传，不传默认为空。 | "uid":"321abc" |
| extend | String | 否 | 下发短信号码扩展码，用于匹配上行回复，上行报告会回传。一般5位以内(只支持传数字)， 不传默认为空。 | "extend":"555" |
复制成功{ "account":"N6000001", "timestamp" :"1752143733", "nonce": "x4zfk0y5foqwx6cbnw3bfmimy98abqs1", "phoneNumbers":"17601337176,15100159057", "templateId":"1021143438", "templateParamJson":"[{\"param1\":\"张三\",\"param2\":\"13\"},{\"param1\":\"李四\",\"param2\":\"88\"}]", "signature":"【创蓝云智】", "report":"true", "callbackUrl":"", "uid":"test_001", "extend":"01" }
| 参数名称 | 类型 | 描述 | 示例 |
|---|---|---|---|
| code | String | 提交响应状态码，返回“0”表示提交成功（其他错误请参考提交响应码） | "code":"000000" |
| msgId | String | 消息 id（32 位纯数字） | "msgId":"25071516453300902203000007708373" |
| time | String | 响应时间 | "time":"20250715164533" |
| successNum | String | 提交成功数量，参数校验失败时不返回 | "successNum":"1" |
| failNum | String | 提交失败数量，参数校验失败时不返回 | "failNum":"0" |
| errorMsg | String | 提交响应状态码中文说明（提交成功返回空） | "errorMsg":"" |
复制成功{ "code": "000000", "failNum": "0", "successNum": "2", "msgId": "25071018345400902898000000000001", "time": "20250710183454", "errorMsg": "" }
| 状态码 | 描述 | 问题处理人 |
|---|---|---|
| 000000 | 提交成功 | 无 |
| 101 | 无此用户（account参数要传API账号不是登录后台的账号，如N111111；或API账号关停了需要联系官网客服解禁） | 技术支持 |
| 102 | 密码错（请确认密码是否一致正确，请直接复制避免手动输入错误） | 技术支持 |
| 103 | 提交过快（提交速度超过流速限制） | 技术支持 |
| 104 | 系统忙（因平台侧原因，暂时无法处理提交的短信） | 技术支持 |
| 105 | 敏感短信（短信内容包含敏感词） | 客服 |
| 106 | 消息长度错（>1036 或<=0） | 技术支持 |
| 107 | 包含错误的手机号码 | 技术支持 |
| 108 | 手机号码个数错（手机号包含了中文符号；手机号个数错了，群发>1000 或<=0） | 技术支持 |
| 109 | 无发送额度（当前使用的API账号下没有发送额度） | 商务 |
| 110 | 不在发送时间内（联系客服或商务解决) | 商务 |
| 111 | 超出该账户当月发送额度限制（联系客服或商务解决) | 商务 |
| 112 | 产品错误（通道出现异常，联系商务解决) | 商务 |
| 113 | 扩展码格式错（非数字或者长度不对） | 技术支持 |
| 114 | 可用参数组个数错误（msg参数的变量符号固定使用"{$var}"；变量符号在20个以内） | 技术支持 |
| 116 | 签名不合法或未带签名（短信签名需要报备通过后才能使用；重保签名不可用） | 客服 |
| 117 | IP 地址认证错（登录控制台在对应使用的API账号下加白ip） | 客服 |
| 118 | 用户没有相应的发送权限（账号被禁止发送，联系客服或商务解禁） | 客服 |
| 119 | 用户已过期 | 客服 |
| 120 | 违反防盗用策略(日发送限制，联系客服或商务解决) | 客服 |
| 123 | 发送类型错误（cmpp协议的账户不能使用https协议方式，请联系我方技术修改） | 技术支持 |
| 124 | 白模板匹配错误（接口传递的内容与报备的模板内容要完全一致，包括标点符号） | 客服 |
| 125 | 匹配驳回模板，提交失败（联系客服或商务解决） | 客服 |
| 127 | 定时发送时间格式错误（格式为 yyyyMMddHHmm） | 技术支持 |
| 128 | 内容编码失败 | 技术支持 |
| 129 | JSON 格式错误（header请求头是否生效：Content-Type：application/json；请求参数不是json格式） | 技术支持 |
| 130 | 请求参数错误（缺少必填参数；参数跟接口地址不匹配，例如变量参数请求普通短信接口地址） | 技术支持 |
| 132 | 消息长度错(>3500或<=0)，超过短信最大支持字数 | 技术支持 |
| 133 | 单一手机号错误 | 技术支持 |
| 134 | 违反防盗策略, 超过月发送限制（联系客服或商务解决) | 技术支持 |
| 135 | 超过同一手机号相同内容发送限制 | 技术支持 |
| 136 | 不可批量提交"验证码"短信 | 技术支持 |
| 139 | 超出安全发送时间（时间戳过期，时间戳时间跟请求接口的时间差异控制在30s以内） | 技术支持 |
| 140 | 短信内容解密错误（秘钥没有使用正确） | 技术支持 |
| 144 | 产品未上线限制日发送数量（签名报备选择的未上线会日限100条，联系客服调整） | 客服 |
| 145 | 验签失败（验签不过，请参考对应接口的DEMO加签代码示例） | 技术支持 |
| 152 | MATERIAL_EXIST_ERROR （模板不存在） | 客服 |
| 153 | MESSAGE_LY_ERROR 消息长度错（>2000或者≤0） | 技术支持 |
| 154 | 长短信拼接错误 | 技术支持 |
| 155 | AIM_SEND_FAIL 转发失败 | 技术支持 |
| 158 | 退订语不符合规范，退订语现在只支持“拒收请回复R”。 | 技术支持 |
| 159 | 触发反轰炸策略 | 技术支持 |