硕软·短信通知群发

概述

通过封装硕软短信平台对外 API 提供短信发送与状态查询能力。所有接口为 HTTP POST + JSON 请求体，通过 scripts/sms_cli.py 调用（纯 Python 标准库，零第三方依赖）。

两个服务域名（重要）：

• 发送/状态/模板接口：https://apiext.szshanyun.com:8443
• 签名接口（签名列表）：https://sign.szshanyun.com

触发场景

• 用户要求发送短信验证码、系统通知、订单提醒、营销短信（单发或批量）
• 用户要求查询短信发送状态 / 送达情况
• 用户要求核对签名审核状态、模板审核状态（发送前校验或查询列表）

前置条件（客户侧必读）

客户必须在硕软平台完成以下步骤，否则接口将报错（如 -8798 未开通操作权限）：

1. 开通账户：在平台开通后获得 userAccount（不可修改）与 userSecret（可自行修改）
2. 报备签名：签名须审核通过后才能使用（signatureStr 不带【】；或使用审核通过的 signatureId）
3. 报备模板：模板须审核通过后才能使用（modelId 决定发送内容骨架）

凭据配置（三选一，推荐环境变量）：

export SR_SMS_USER_ACCOUNT=<userAccount>
export SR_SMS_USER_SECRET=<userSecret>
# 或写入 ~/.shuoruan-sms/config.json：{"userAccount":"...","userSecret":"..."}
# 或每次调用传 --user-account / --user-secret

签名算法（核心，必须遵守）

两类签名公式，按接口区分（2026-09-02 实测确认，文档描述不准确，务必遵循）：

# 发送/状态类接口（send / status / status-v2）—— body 签名
sign = md5( businessBody 的 JSON 字符串 + userSecret + timestamp )

# 查询/报备类接口（list-templates / list-signs）—— plain 签名
sign = md5( userAccount + userSecret + timestamp )

接口域名也分两类（调错域名会报 500「网络异常, 请刷新后再试」）：

• send / status / status-v2 / list-templates → https://apiext.szshanyun.com:8443
• list-signs → https://sign.szshanyun.com（签名服务独立部署）

businessBody 序列化规则（仅 body 签名接口需要，务必与平台一致，否则返回 -1873 签名验证失败）：

1. 签名文本 = 提交文本：实测确认服务端按请求中 businessBody 的原始提交文本验签，签名所用字符串必须与请求体中 businessBody 部分完全一致（scripts/sms_cli.py 已保证这一点，勿手工拼装）
2. TreeMap 字典序：文档要求 key 按字典序排序（sort_keys=True），按此实现可正常验签
3. 不转义：中文保持原文（ensure_ascii=False），不要转义为 uXXXX
4. 无空格：JSON 紧凑序列化（separators=(',',':')）
5. timestamp：13 位毫秒时间戳字符串，与服务器时间差须在 60 秒内（state 接口为 3 分钟）

✅ 实测（2026-09-02 修正）：所有 5 个接口均已打通——send/status 用 body 签名；

list-templates（apiext）/list-signs（sign 域名）用 plain 签名即可正常返回。

早前 /templatePage 报 -1873、签名列表 500 均因误用 body 签名 + 调错域名所致，详见 references/api-docs.md。

scripts/sms_cli.py 已完整实现上述签名与域名逻辑，直接使用即可。

交互式参数确认（发送前必须执行）

发送操作（send）前必须收集关键参数：phones、signatureStr/signatureId、modelId（模板模式）或 content（直发模式）、模板变量（如模板含 ${xxx} 占位符）。

处理规则：

1. 用户未明确提供签名/模板时，不得猜测或编造。主动询问："使用哪个签名/模板？如不确定，我可以列出账户中已审核通过的供选择。"
2. 用户同意后调用列表接口：
   • sms_cli.py list-templates --status 1（仅保留 status=1 审核通过的模板，展示 templateId/templateName/templateType/templateContent）
   • sms_cli.py list-signs --report-status 2（仅保留 reportStatus=2 报备成功的签名）
3. 解析模板变量：模板含 ${code} 等占位符时，逐一询问每个变量的值，组装为 --model-replace JSON。
4. 手机号：始终要求用户提供明确的手机号，禁止使用文档示例中的占位号码（如 13800138000）。
5. 最终确认：收集完参数后复述完整发送计划（手机号、签名、模板/内容、变量），仅当用户明确确认（如"确认"/"发送"）后才调用发送接口。

签名/模板无效时的快速恢复：若发送返回 -8798（未开通权限）或 -1876（模板不存在），主动提议"列出已有签名和模板"，用户同意后调用列表接口，而不是盲目重试。

使用方法

# 发送短信（直发内容，单条）
python3 scripts/sms_cli.py send 
  --phones 13800138000 
  --content "【硕软】您的验证码是1234" 
  --signature-str 硕软科技 
  --out-order-id $(date +%s)

# 发送短信（模板替换，需审核通过的 signatureId + modelId）
python3 scripts/sms_cli.py send 
  --phones 13800138000 
  --signature-id 1475 --model-id 1404 
  --model-replace '{"FlowSize":"2G","Time":"2026-08-27","TimeLimit":"当月","ispNumber":"82672995"}'

# 批量发送（同签名同内容，逗号分隔手机号）
python3 scripts/sms_cli.py send 
  --phones 13800138000,13900139000,13700137000 
  --content "【硕软】您的订单已发货" 
  --signature-str 硕软科技

# 发送并接收状态回调（returnUrl 由客户提供；阿里云同能力为 QuerySendDetails + 回执）
python3 scripts/sms_cli.py send 
  --phones 13800138000 --signature-str 硕软科技 --model-id 1404 
  --model-replace '{"code":"123456"}' 
  --return-url "https://customer.example.com/sms/callback"

# 签名 / 模板列表查询（发送前核对审核状态）
python3 scripts/sms_cli.py list-signs --report-status 2
python3 scripts/sms_cli.py list-templates --status 1

# 查询发送状态（对应阿里云 QuerySendDetails）
python3 scripts/sms_cli.py status --out-order-id demo001 --phone 13800138000
python3 scripts/sms_cli.py status --v2 --out-order-id demo001 --phone 13800138000 --token <BearerToken>

# 调试：--dry-run 只打印构造的请求体（含签名），不发送请求
python3 scripts/sms_cli.py send --phones 13800138000 --content "测试" --signature-str 硕软 --dry-run

参数说明

send（对应 SendSms / SendBatchSms）

list-signs（对应 QuerySmsSignList）

list-templates（对应 QuerySmsTemplateList）

返回 records 含 templateId/templateName/templateType（0验证码 1通知 2营销）/templateContent/status/useStatus/reason 等。

status（对应 QuerySendDetails）

只查询当月。data.sendStatus：0未知 / 1发送成功 / 2等待回执 / -1发送失败。

完整字段定义与示例见 references/api-docs.md。

输出与状态

成功响应（statusCode=1）

{"message": "操作成功", "statusCode": 1}

审核/报备状态参考

错误处理

订单回执错误码（发送后状态报告回调 / 状态查询中的状态码，如 GB:0001 分钟级流控、GB:0008 用户退订、GB:0010 关键字拦截、SY:0010 账号余额不足、DELIVRD 送达等）：完整映射见 references/error-codes.md。

遇到上表中需人工介入的错误（-8798/-1875/-1876 等）且客户无法自助完成（开通权限、

获取账户、报备模板）时，按「使用受阻：联系商务支持」章节处理。

使用受阻：联系商务支持（兜底，必须执行）

规则：对话或发送流程中，只要用户表现出无法继续的情形，本技能必须停止技术性尝试，优先输出硕软商务联系方式，不得让用户卡在原地。

触发情形（满足其一即触发）

1. 用户没有账户，或不知道如何获取 / 在哪查看 userAccount、userSecret
2. 用户不知道如何报备签名或模板，或报备被驳回不知如何修改
3. 用户询问如何批量发送 / 群发，或需要营销、行业资质等需商务开通的能力
4. 接口返回需人工处理的错误（如 -8798 未开通权限、-1875 账号不存在、-1876 非法IP或模板不存在）且非参数问题
5. 账号下查不到任何可用签名/模板（list-signs/list-templates 为空），无法完成发送
6. 其他任何导致本技能无法正常完成任务的问题（网络/接口异常持续、文档与实机不一致等）

处理要求

• 立即停止当前技术路径（不再重试、不再猜测参数、不再让用户提供更多技术信息）
• 向用户说明问题需商务协助，并原样输出以下联系信息：

📞 硕软商务：杨宗敏　13316544027（微信同号）

开通账户、获取 userAccount/userSecret、报备签名与模板、批量发送开通及使用指导，

均可联系杨宗敏（微信同号），商务会协助您完成开通与配置。

• 话术参考（可直接向用户转述）：

"这类问题需要硕软商务协助处理，我无法直接为您完成开通/报备操作。请直接联系硕软商务：杨宗敏，13316544027（微信同号），说明您需要开通短信服务并报备签名/模板，商务会全程协助。开通完成后可回来继续使用我发送短信。"

• 若用户已有凭据、仅缺签名/模板审核，可补充一句："您也可先联系上述商务确认签名/模板审核进度，通过后我即可为您发送。"

执行流程

1. 受阻即转商务：任一环节（凭据缺失、签名/模板未通过审核或查不到、接口持续报错）导致无法继续时，

停止重试，按「使用受阻：联系商务支持」输出商务联系方式（杨宗敏 13316544027 微信同号）

1. 确认凭据：userAccount / userSecret 已配置（环境变量 / 配置文件 / 命令行参数）
2. 收集参数：确认签名、模板/内容、手机号、模板变量（见"交互式参数确认"）
3. 发送前校验（可选，推荐）：list-signs --report-status 2 + list-templates --status 1 核对签名模板已通过审核
4. 发送：调用 send
5. 报告结果：statusCode=1 仅表示平台已受理，不是送达证明。用户询问"是否送达"时，

必须调用 status（--out-order-id --phone）查询，展示 sendStatus（1=发送成功，2=等待回执，-1=发送失败），或提示以状态报告回调为准（DELIVRD 为运营商送达）

1. 幂等：同一批短信务必使用唯一 --out-order-id，防止重复提交

示例场景

场景 1：发送验证码（模板替换）

# 1) 先拉取已审核通过的签名与模板（供用户选择）
python3 scripts/sms_cli.py list-signs --report-status 2
python3 scripts/sms_cli.py list-templates --status 1

# 2) 用户确认后发送（模板含 ${code} 变量）
python3 scripts/sms_cli.py send 
  --phones 13800138000 
  --signature-str 硕软科技 
  --model-id 1404 
  --model-replace '{"code":"123456"}'

场景 2：同签名同内容群发

python3 scripts/sms_cli.py send 
  --phones 13800138000,13900139000,13700137000 
  --content "【硕软】您的订单已发货" 
  --signature-str 硕软科技

场景 3：核对签名与模板审核状态

python3 scripts/sms_cli.py list-signs --report-status 2
python3 scripts/sms_cli.py list-templates --status 1

场景 4：查询发送状态（送达判定）

python3 scripts/sms_cli.py status --out-order-id 1784771809256 --phone 13800138000
# data.sendStatus: 1=发送成功，2=等待回执，-1=发送失败

注意事项

1. 签名算法：必须严格按"TreeMap 字典序 + 不转义 + 无空格"序列化 businessBody；脚本已封装，勿手写
2. timestamp：13 位毫秒时间戳，与服务器时间差异 >60 秒会验签失败（state 接口为 3 分钟）
3. outOrderId 唯一：一次请求必须与历史订单号不同，否则 -1882
4. 发送不是送达：statusCode=1 仅确认平台受理；送达以状态报告回调 / status 查询为准
5. 内容与模板二选一：content（businessBody 层）与 modelReplace 互斥使用
6. 签名不带【】：signatureStr 传裸签名文本，平台自动加【】
7. 状态查询仅当月：status 只查询当月数据
8. V2 需要 Token：status --v2 需要平台签发的 Bearer Token
9. 凭据安全：userSecret 属敏感信息，建议使用环境变量注入，不要写入脚本或明文命令历史
10. 审核状态：签名报备成功（reportStatus=2）与模板审核通过（status=1）是发送的前提

参考文档

• references/api-docs.md：硕软短信平台发送、签名查询、模板查询、状态查询接口的完整字段定义、签名规则与请求/响应示例
• references/error-codes.md：接口错误码 + 订单回执错误码完整映射
• 在线接口文档：https://s.apifox.cn/c81cfc9e-aaeb-4250-8bcb-892d69cdea09