1. 首页
  2. 秒信通MiCPaaS
  3. 🗊 国内短信
  4. 🗊 API接口
  5. 🗎 接入前准备
菜单
本页目录

API 接入前准备与说明

一、接入前置资质准备（必备）

1. 企业资质材料

  1. 营业执照清晰扫描件（有效期内，经营范围含对应业务）

  2. 法人身份证正反面、法人实名联系方式

  3. 加盖公章的《短信业务接入承诺书》（秒信通客服人员提供模板）

  4. 行业特殊资质（按需提供）

    • 金融类：金融许可证、放贷资质、支付牌照

    • 教育类：办学许可证

    • 医疗类：医疗机构执业许可证

    • 电商 / 电商贷款：平台经营资质

2. 短信业务合规资质

  1. 短信签名备案材料

    • 签名授权证明：商标证、品牌授权书、官网版权、店铺资质其一

    • 签名名称规范：企业简称 / 品牌名 / APP / 小程序名称，禁止通用无辨识度签名

  2. 短信模板备案

    • 区分验证码、通知短信、营销短信三类模板，分开报备

    • 营销短信必须携带"拒收请回复R"，未携带不予审核通过

  3. 实名报备：发送主体、接收方场景、发送用途完整备案

3. 接口调用账号资源

  1. 平台商户账号（完成企业实名认证）

  2. 接口身份凭证：

    • AppID / SP_ID

    • AppSecret 密钥（妥善保管，禁止明文存放、泄露）

  3. 接口余额 / 套餐包：预充值短信条数，余额不足无法下发

二、技术接入环境准备

1. 网络环境要求

  1. 服务器可正常访问平台 API 域名

  2. 出口 IP 固定：提供服务器公网 IP 加入平台白名单，未加白无法调用接口

  3. 端口放行：443（HTTPS）、80（HTTP 备用），关闭拦截 API 域名防火墙策略

  4. 不支持内网、代理、动态 IP 频繁切换调用，易触发风控拦截

2. 开发语言与工具支持

全语言兼容，提供示例代码：Java、PHP、Python、Go、C#、Node.js、PHP

所需基础工具：

  • HTTP/HTTPS 请求库

  • MD5/HMAC-SHA256 加密工具（签名校验必备）

  • URL 编码工具（参数排序、拼接签名）

  • JSON 解析工具（请求入参、返回报文解析）

3. 测试资源准备

  1. 测试专用签名、测试模板（秒信通赠送免费测试条数）

  2. 测试手机号：支持本机接收测试短信，部分运营商虚拟号无法接收

  3. 沙箱环境：模拟下发、回执、上行，无真实短信扣费，用于联调

三、接口通用规范说明（接入必读）

1. 请求协议

  • 推荐：HTTPS POST（加密传输，安全防篡改）

  • 编码格式：统一 UTF-8

  • 数据格式：请求 / 响应均为 JSON

  • 超时时间：建议客户端设置 3~5s，超时需重试机制（限制重试次数）

2. 安全签名机制（核心）

  1. 所有接口请求必须携带签名，无签名 / 错误签名直接返回 403 拒绝访问

  2. 签名规则简述：

    1. 所有业务参数按 ASCII 升序排序

    2. 参数键值拼接 + AppSecret 密钥

    3. MD5/HMAC-SHA256 加密生成 sign 签名

  3. 安全规范：

    • Secret 禁止前端硬编码、客户端泄露

    • 密钥泄露立即联系平台重置，避免盗刷短信

    • 禁止将签名缓存长期复用，每次请求重新生成

3. 号码规范

  1. 国内手机号：11 位纯数字，支持批量提交

  2. 不支持固话、400、虚拟运营商小号、黑名单号码

  3. 营销短信需过滤退订用户库，已退订号码禁止再次推送

4. 短信长度计费规则

  1. 普通短信：≤70 字，计 1 条

  2. 长短信：71~134 字计 2 条，每 67 字递增 1 条，含签名、标点、空格全部计入字符

  3. 签名、【】符号占用字符，模板设计时控制长度降低成本

四、业务功能说明

1. 接口能力清单

  1. 单条 / 批量短信下发接口（验证码 / 通知 / 营销）

  2. 模板短信下发（推荐，审核通过模板下发更快、风控更低）

  3. 发送状态回执接口（主动回调 / 主动查询两种模式）

  4. 上行短信获取接口（用户回复 T / 其他内容拉取）

  5. 账户余额查询、套餐余量查询

  6. 签名、模板提交 / 审核查询接口

  7. 黑名单、退订名单查询接口

2. 回执说明

  1. 两种获取方式：

    • 主动查询：调用回执查询接口拉取发送结果

    • 被动回调：配置我方回调地址，短信送达 / 失败实时推送

  2. 回执状态：成功送达、停机、空号、拒收、运营商拦截、模板违规等

  3. 回执保存：建议本地存储至少 7 天，用于对账、客诉核查

五、风控与合规重要说明（接入红线）

  1. 禁止发送内容

    • 涉黄、赌、毒、诈骗、暴力、政治敏感内容

    • 虚假贷款、刷单、博彩、催收恐吓、违规医美

    • 未经用户授权营销短信、未加退订标识营销短信

  2. 发送频率限制

    • 验证码：单手机号单日上限 10 条，防刷机制

    • 营销短信：单用户单日≤3 条，晚间 20:00 - 次日 8:00 禁止推送营销

  3. 用户退订规则

    用户回复 T/Td/ 退订自动加入黑名单，永久停止营销推送，不可绕过

六、对账、扣费与售后说明

  1. 扣费逻辑：提交成功即扣减条数，无论是否送达（运营商通道占用即计费）

  2. 对账文件：每日凌晨生成前一日发送明细，支持 API 拉取 / 后台下载

  3. 退款规则：通道故障、平台侧问题可登记退费；用户拒收、空号、拦截不予退费

  4. 售后对接：技术对接群、工单系统，紧急故障 7×12 小时响应

七、接入整体流程总览

  1. 提交企业资质 → 账号实名认证

  2. 报备短信签名、短信模板，等待审核

  3. 技术获取 AppID、AppSecret，服务器 IP 加白

  4. 沙箱测试环境联调：下发、回执、签名校验

  5. 测试通过切换正式环境，充值套餐

  6. 上线后对接回执回调，搭建异常重试、日志记录机制

  7. 日常合规发送，每日核对发送对账数据

八、开发注意事项

  1. 日志记录：完整记录请求参数、返回码、时间戳、手机号，便于排障

  2. 重试机制：接口超时仅重试 1-2 次，间隔≥1s，防止高频调用被限流

  3. 限流处理：平台单商户 QPS 有上限，大批量发送需做队列分流

  4. 数据脱敏：存储手机号做中间 4 位掩码，禁止明文对外输出

  5. 版本兼容：接口字段迭代向下兼容，新增字段不影响原有业务

上一篇 🗊 API接口
下一篇 🗎 签名管理