用途:帮助在现有项目中编写 Spug 短信接入代码,覆盖短信发送、短信状态查询和短信历史查询;仅实现实际需要的能力,不扩展邮件等其他通道。
主要能力:支持模板短信发送与动态模板变量;发送接口同时支持 POST 和 GET,默认使用 POST https://push.spug.cc/sms/{template_code} 并发送 JSON;可查询发送状态与历史记录。
使用方式:先检查项目语言、HTTP 客户端、配置方式和测试习惯,再读取 references/api.md,优先复用现有依赖与代码模式。将模板编码或受信任的模板 URL 与查询 token 放入环境变量或项目现有密钥系统,不写入源码、示例、日志或提交内容;不要接收业务请求传入的任意 URL。默认发送函数接收并始终发送 to、name、code、number;仅当项目维护“模板 → 所需变量”配置时才按模板元数据选择字段。发送前校验:to 中每个手机号 11 位数字,name 为 1–10 位中文、英文字母或数字,code 为 4–6 位英文字母或数字,number 为数字或中文数字表示的有效时长;多个手机号用英文逗号分隔,单次最多 5 个。发送接口返回 code: 200 后保存 request_id,需要最终结果时再调用状态查询接口。查询状态与历史使用独立 token,不要误用模板编码;历史查询固定传入 type: "sms",只处理最近 30 个自然日内的记录。
限制:GET 参数必须交给 HTTP 客户端编码,不得手工拼接;手机号、验证码等敏感动态值会进入 URL,不得记录完整 URL,日志中也不得输出含模板编码的完整请求 URL。对待发送、发送中或审核中状态使用间隔查询,避免紧密轮询。使用项目现有测试工具模拟 HTTP 响应,至少覆盖成功响应和接口错误,测试不得真实发送短信。除非项目已有批处理约定,否则不要额外实现队列、重试器或 SDK 封装层。除非用户明确要求,不要执行真实发送请求。