shaguabijia-app-server/docs/integrations/chuanglan/tpl-send.md

创蓝云智（253/蓝创云智）模板短信 v2 发送接口

官方文档：https://doc.chuanglan.com/document/HAQYSZKH9HT5Z50L 用途：手机号 + 验证码登录的验证码短信下发（本服务生成码 → 创蓝只负责发送，属自管码 Mode B，与极光同模式）。 本文件为接口调研摘要，供 app/integrations/sms/chuanglan.py 实现对照。以线上文档为准。

接口概览

项	值
请求地址	POST https://smssh.253.com/msg/sms/v2/tpl/send
Content-Type	application/json（UTF-8）
协议	HTTPS
鉴权	HMAC-SHA256 签名头 X-QA-Hmac-Signature（推荐）或 body 明文 password（二选一）

鉴权：两种方式（二选一，不可并用）

1. HMAC 签名头（推荐，密码不上行）：请求头带 X-QA-Hmac-Signature，body 不放 password。
2. 明文密码：body 放 password，不带签名头。

HMAC-SHA256 签名算法

1. md5Password = MD5(password) —— 32 位小写十六进制。
2. 取三个值 [md5Password, timestamp, nonce]，按字典序升序排序，无分隔符拼接，再 replaceAll("\\s+", "") 去除所有空白。
3. signature = HmacSHA256(key = md5Password, message = 上一步拼接串) —— 输出小写十六进制。
4. 放入请求头：X-QA-Hmac-Signature: <signature>。

注意 key 就是 md5Password 本身（32 位 hex 字符串），不是原始 password。timestamp / nonce 同时也是 body 字段，必须与签名里用的一致。

请求参数（body，JSON）

参数	类型	必填	说明
account	String	是	API 账号；验证码短信用 YZM 前缀账号（如 YZM0000001）
timestamp	String	是	Unix 秒级时间戳；60 秒内有效，过期报 139
nonce	String	是	32 位随机串（防重放）
phoneNumbers	String	是	手机号，逗号分隔最多 1000 个；YZM 验证码账号不支持批量，只能单号
templateId	String	是	模板 ID（控制台创建 / 模板接口查询）
templateParamJson	String	条件	模板变量，JSON 字符串；模板有 {s} 占位符时必填（见下）
password	String	条件	仅在不使用签名头时放 body
signature	String	条件	短信签名文案（如 【创蓝云智】）；模板未关联签名时必填。注意与鉴权头 X-QA-Hmac-Signature 是两回事
report	String	否	"true" 时接收状态回执
callbackUrl	String	否	回执回调完整 URL
uid	String	否	自定义标识（≤256 字符），回执原样返回
extend	String	否	数字扩展码（≤5 位），用于上行匹配

templateParamJson 格式与 {s} 占位

• 模板内容用 {s} 作占位符，例：您正在申请手机注册，验证码为：{s}，5分钟内有效！
• templateParamJson 是 JSON 数组，元素为对象，键按 param1、param2…递增；第 1 个 {s} ← param1，第 2 个 ← param2。
• 单条验证码（一个 {s} = 验证码）示例："[{\"param1\":\"123456\"}]"

响应格式

{
  "code": "000000",
  "msgId": "25071018345400902898000000000001",
  "time": "20250710183454",
  "successNum": "1",
  "failNum": "0",
  "errorMsg": ""
}

字段	说明
code	状态码，"000000" = 成功
msgId	消息 ID（32 位）
time	响应时间戳
successNum / failNum	提交成功 / 失败条数
errorMsg	错误描述（成功为空）

响应 / 错误码（节选）

code	含义	归属
000000	成功	—
101	账号不存在	客服
102	密码错误	客服
103	提交速度过快（超频）	客服
107	手机号码错误	客服
109	无发送量（余额/套餐不足）	销售
110	不在发送时段	销售
116	签名不合法 / 未带签名	服务
117	IP 未加白名单	服务
118	账号无发送权限	服务
124	模板内容不匹配	服务
129	JSON 格式错误	客服
135	相同手机号内容重复	客服
139	时间戳过期	客服
152	模板不存在	服务
158	退订文案不合规	客服

完整请求示例（单条验证码，明文密码方式省略 password 用签名头）

{
  "account": "YZM0000001",
  "timestamp": "1752143733",
  "nonce": "x4zfk0y5foqwx6cbnw3bfmimy98abqs1",
  "phoneNumbers": "17601337176",
  "templateId": "1021143438",
  "templateParamJson": "[{\"param1\":\"123456\"}]",
  "report": "true"
}

（HMAC 方式：另加请求头 X-QA-Hmac-Signature: <算法输出>，body 不含 password。）

接入要点

• IP 白名单：服务器出网 IP 必须在控制台加白，否则 117。
• 验证码账号（YZM）：无发送时段限制；单号发送、不支持批量。
• 时间戳 60s：timestamp 与本地时钟偏差过大会 139，注意服务器时间同步。
• 退订文案：仅支持 拒收请回复R，且必须在短信末尾（验证码短信一般无需）。
• 签名 vs 鉴权头：signature（body）= 短信开头的 【品牌】 文案；X-QA-Hmac-Signature（header）= 请求鉴权。二者含义完全不同，勿混。