接入方式总览

这一章是 Whaleal SMS 云平台的接入总入口：先选路径，再按五步跑通第一条短信。

三条接入路径

路径	谁适合	你要做什么	代码量
A. 控制台手动发信	验证通道、给运营做临时发送	登录控制台，选渠道和 Sender，填号码内容	0
B. 开放 API（推荐）	业务系统程序化发信	签发 API Key → 调一个 HTTP 接口	一次 HTTP 调用
C. 定时任务	批量 / 预约发送	控制台建任务，或用 API 提交	0 ~ 少量

三条路径共用同一套渠道、同一份日志、同一个限速。本文重点讲 B，因为绝大多数接入是程序化发信。

平台不提供 Java SDK 形式的客户端。它是纯 HTTP 接口 —— 这反而意味着 Java、Node.js、Python、Go、PHP 的接入方式完全一致，见开放 API。

接入前：账号

控制台地址：sms.whaleal.com，登录走 Whaleal IDP（idp.whaleal.com）统一身份，首次登录即建立租户，无需单独注册。

登录后你会看到左侧的功能区，本文涉及的主要有四个页面：

页面	路径	作用
BYOL 渠道	`/app/connections`	录入你的 CPaaS 凭据，管理 Sender 号码
API 密钥	`/app/api-keys`	签发密钥、绑定渠道、看路由链
开发者中心	`/app/developer`	配置状态回调、拿供应商回执地址、管理回调令牌
消息日志	`/app/logs`	查每条消息的最终状态（排障主入口）

五步接入

第 1 步：录入渠道（BYOL 渠道页）

进 /app/connections → 添加渠道，选择供应商并填入你自己账号的凭据：

供应商	凭据字段
Twilio	SID + Auth Token
Vonage	API Key + Secret
Infobip	API Key + Base URL

填完后还要在这个渠道下添加 Sender（发送号码 / 签名），一个渠道可以绑多个 Sender，平台会在它们之间做加权轮询 —— 调用方不需要感知号码切换。

同时设置两个路由参数，它们决定了这条渠道在聚合里的角色：

参数	含义
priority	失败容灾顺序。越小越优先，仅失败时生效，健康时不多发
weight	健康时的分发比例。不全相等时按权重比平滑轮询；全为 1 时退化为按 priority 顺序主备

验收判据：渠道状态显示为 ACTIVE。

卡点：凭据填错时渠道不会是 ACTIVE。平台侧凭据是加密存储、永不回显完整密钥的，所以填错只能重新录入，不能"看一眼改一个字符"—— 录入前先在供应商后台复制完整密钥。

第 2 步：签发 API 密钥（API 密钥页）

进 /app/api-keys → 签发密钥，两步完成：

基本信息 —— 填一个能辨认的名称，比如「生产环境-订单通知」
路由规则 —— 勾选这条密钥可以走哪些渠道

右侧会实时显示路由链预览（按渠道 priority 排序），你在这里就能看到这条密钥实际会怎么分发、失败会切到谁。

验收判据：签发后会弹出密钥明文。

⚠️ sk_ 密钥明文只展示这一次。平台只存哈希，关闭弹窗后无法再次查看。请立刻存进你的密钥管理系统；如果泄露，到密钥详情页禁用后重新签发。

卡点：不绑定任何渠道的密钥无法发信，调用会直接被拒（业务码 40000）。如果你在「路由规则」这一步一条都没勾，密钥是"签出来了但用不了"的 —— 密钥列表里会明确标出「未绑定渠道（不可发送）」。

第 3 步：发第一条短信

用 curl 打通（把密钥和号码换成你自己的）：

curl -X POST https://smsapi.whaleal.com/open/v1/sms/send \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "content": "Your verification code is 824193"
  }'

验收判据：返回 "code": "0000"，且 data.status 为 submitted。

{
  "code": "0000",
  "msg": "success",
  "data": {
    "messageId": "6a1f9c8e2b...",
    "status": "submitted",
    "provider": "twilio",
    "to": "+14155550123",
    "providerMessageId": "SM8f10c8...",
    "encoding": "GSM7",
    "segments": 1
  }
}

请你留意这几个字段，它们是后面每一条消息都要用到的：

messageId —— 查状态、对账、排障的唯一钥匙，业务侧请务必落库
provider —— 实际承运的渠道，多渠道聚合时你会想知道这次走了谁
providerMessageId —— 为 null 说明供应商未受理（这条不计费）
encoding / segments —— 本条实际生效的编码口径与计费条数

🔴 submitted 不等于已送达。发送接口是异步受理：返回 0000 只表示平台已把消息提交给供应商。要确认送达，靠状态回调，或用 messageId 查状态。

第 4 步：配置状态回调（开发者中心）

进 /app/developer，这里有两条不同的回调链路，别混：

链路	方向	填在哪
供应商回执地址	供应商 → 平台	由平台给出，你复制到 Twilio / Vonage / Infobip 后台的回执回调处
状态回调地址	平台 → 你的系统	你填自己的 URL，平台在消息到终态时 POST 通知你

验收判据：用自己的回调服务收到一次终态推送，且请求头带 X-Callback-Token。

完整处理方式（含 Spring Boot 示例、验签、幂等、重试语义）见状态回调接入。

第 5 步：上线前对账

curl https://smsapi.whaleal.com/open/v1/usage \
  -H "Authorization: Bearer sk_xxxxxxxx"

返回本月 messageCount（提交了几次）与 billedSegments（账单上有几条）。两个数必然不等 —— 长短信一条算多条。核对方式见套餐与配额。

接入自检清单

上线前逐条打勾：

下一步：开放 API 参考 · 状态回调接入

三条接入路径​

接入前：账号​

五步接入​

第 1 步：录入渠道（BYOL 渠道页）​

第 2 步：签发 API 密钥（API 密钥页）​

第 3 步：发第一条短信​

第 4 步：配置状态回调（开发者中心）​

第 5 步：上线前对账​

接入自检清单​