短信 API 接入准备指南：鉴权、发送、回执与上行

鉴权与账户准备

开始短信 API 对接前，先明确业务场景、目标地区、接收人授权方式和消息类型。验证码、业务通知与营销短信的发送条件不同，不应共用一套未经核对的内容和重试策略。

签名鉴权的具体算法、签名字段顺序、时间戳格式和有效窗口，以项目确认的接口文档为准。不要照搬其他平台示例中的地址或密钥。服务端保存凭证，浏览器、APP 安装包、日志和公开代码中不放生产密钥。

余额查询可作为发送前检查的一部分，但余额充足不代表特定地区、号码或内容一定可以发送。还需确认计费单位、长短信分段、账户权限、测试额度和频率限制。测试环境与生产环境分别管理配置。

核对要点

• 列出获准使用的账户、环境和密钥轮换负责人。
• 核对鉴权失败、时间偏差、权限不足和余额不足时的处理。
• 为计费与业务记录建立可核对的时间范围和内部流水号。

单条发送、批量发送与多内容任务

短信发送应由业务系统生成内部消息标识，记录接收号码、模板版本、业务用途和提交时间。号码按服务支持的国家码格式校验；同一收件人的重复任务先在业务侧去重，不以接口返回超时作为再次发送的唯一依据。

批量发送多内容短信时，为每个接收人建立内容与业务记录的对应关系，检查变量是否缺失、编码是否变化以及长度是否导致分段。敏感变量不写入普通运行日志；营销任务还要处理退订、免打扰和发送时段。

请求被受理、网关处理完成和用户实际收到消息是不同阶段。重试应依据明确的错误分类：修正参数后才重提；短暂网络异常采用有上限的退避；结果未知时先查询已有任务，避免重复扣费或重复触达。

核对要点

• 分别测试单条、批量、不同内容和边界长度。
• 确认限流、部分成功、超时与重复请求的处理规则。
• 在真实小范围验收前，不直接扩大到完整接收人名单。

发送结果查询、状态报告与回调

查询短信发送结果时，优先使用提交后取得的消息标识，并保留内部业务号与服务返回号的映射。按时间段查询适合对账和补偿，但要确认时区、分页边界、状态枚举和数据保留时间，避免跨页漏单或重复计算。

主动推送状态报告可减少反复轮询。接收端应校验来源或签名，先可靠记录事件，再返回文档要求的确认。回调可能重复、延迟或乱序，同一消息的状态更新应具备幂等性，不让较旧事件覆盖已确认的新状态。

PB 状态报告等通道专项回调名称不能直接视为统一标准。若项目确实涉及这类报告，先取得字段含义、状态转移、重发规则和样例，再与业务状态进行映射。没有明确资料时，不自行推断“成功”代表终端送达。

核对要点

• 用已脱敏的回调样例核对字段、签名及应答。
• 测试重复回调、乱序回调、接收端重启和补查。
• 分别记录提交成功率、确认送达率和业务完成率。

上行短信查询、主动推送与业务归属

上行短信是接收人回复到服务号码的消息。接入前需确认所选地区、号码类型和通道是否支持回复，以及业务如何区分会话、客户和活动。不能仅凭手机号码就认定消息属于某个用户。

上行查询与上行记录主动推送应采用同一套去重和归档规则。核对发送方、接收方、时间、内容编码与唯一标识；回复可能比发送状态先到达，也可能在跨日或跨时区后才被处理。

对退订、拒绝联系和其他停止触达请求，建立可执行的处理流程。保留必要审计信息，同时限制原文访问和保存周期；普通咨询和故障排查不需要提供完整收件人列表或正在使用的验证码。

核对要点

• 确认上行是否可用以及号码的实际归属和使用期限。
• 测试推送与补查重叠时只处理一次。
• 为退订、敏感内容和无法归属的消息设置人工处理入口。

附件、彩信、RCS 与点击事件

附件上传、彩信发送与 RCS 发送需要单独核对支持条件，不应因为存在短信账户就假定全部能力可用。确认地区、运营商、终端、发送主体和内容审核要求；不支持时的回落方案也要在业务设计中明确。

上传附件前检查文件类型、尺寸、大小、保存期限和访问权限。彩信及 RCS 的内容组合、按钮和链接应经过真实终端测试，不能只在接口返回成功后就视为展示正常。发送失败时是否回落为短信、是否再次计费，都需事先约定。

点击记录主动推送反映链接或消息交互事件，不能单独证明用户身份、购买意愿或最终转化。确认事件来源、去重标识、时间窗口和隐私告知，并与业务侧转化记录分开统计。

核对要点

• 按项目资料验证附件限制及失效链接。
• 覆盖不支持终端、内容审核失败和回落场景。
• 将点击、回复、送达与业务转化分开解释。

联调、验收与上线监控

先在可控测试号码上完成正常流程，再覆盖错误凭证、无效号码、限流、余额不足、请求超时和回调不可达。测试用例应给出预期结果、责任方和可复现证据，而不只是“接口可以调用”。

上线前设置单日预算、频率上限、异常告警和暂停开关。保存配置版本和回滚步骤，变更模板、鉴权或回调地址后重新验证关键流程。出现问题时提供时间范围、内部消息号和脱敏错误，避免发送生产密钥或完整内容。

核对要点

• 验收业务用途、发送链路、状态闭环和退订处理。
• 明确故障联系人、告警阈值及账单核对周期。
• 先小流量观察，再按监控结果逐步扩大。