短信验证码 API 怎么接入？10 分钟上手

接入短信验证码，其实就 5 步：注册 → 买额度 → 生成 API Key → 调接口 → 配回执。下面按顺序走，附 curl 和 PHP 的可用代码。

一、准备：注册、买额度、拿 API Key

1. 在 注册页 注册账号并登录控制台；
2. 到 额度充值 买一个短信套餐（额度下单即时到账）；
3. 控制台 →「API Key」→ 生成一个 sms 类型的 Key。生成的 Key 只显示一次，请立刻保存。

二、调用发送接口

一个接口搞定：POST /api/sms/send，请求头带 Authorization: Bearer {API_KEY}，请求体是 JSON。

curl 示例

curl -X POST https://jh.fzywl.cn/api/sms/send \
  -H "Authorization: Bearer 你的API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 你的业务订单号" \
  -d '{"phone":"13800138000","content":"123456"}'

PHP 示例

$ch = curl_init('https://jh.fzywl.cn/api/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer 你的API_KEY',
        'Content-Type: application/json',
        'X-Request-Id: 你的业务订单号',   // 幂等用，建议带
    ],
    CURLOPT_POSTFIELDS     => json_encode(['phone' => '13800138000', 'content' => '123456']),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
// $res['code'] === 0 表示受理成功

返回长什么样

{"code":0,"msg":"success","data":{"call_id":123,"status":"success","deducted":true}}

call_id 是本次调用的流水号，出问题时把它发给客服，能直接查上游返回。

三、一定要带的 X-Request-Id（幂等）

网络抖动时你的程序可能重试。带上 X-Request-Id（比如你的订单号），同一 ID 的重复请求只会发送一次、也只扣一次费，第二次直接返回上次结果。

四、配置发送结果回执（推荐）

短信是异步的——接口返回成功只代表"已提交"，不代表"已送达"。给 Key 配一个 callback_url，每次调用的最终结果会 POST 给你（带 HMAC 签名），不用轮询；失败了还会自动重试。

配置位置：控制台 →「API Key」→ 对应 Key → 回调设置。接回执前建议先看 开发文档 里的验签说明。

五、常见错误码

code	含义	怎么办
401	API Key 无效 / 没带	检查 Authorization 头和 Key 是否正确、是否被禁用
402	额度不足	去 额度充值 补额度
403	Key 与产品类型不匹配 / IP 不在白名单	确认用的是 sms 类型 Key，并把服务器 IP 加白
429	触发限流	Key 默认 20/分、200/时、800/天；同号默认 3/分、10/时、20/天，控制台可调

完整错误码见 错误码表，也可以用 在线测试工具 先发一条真实短信验证。

小结

• 一个接口：POST /api/sms/send，Bearer 鉴权；
• 带 X-Request-Id 防重复扣费；
• 接回执才知道到底送达没有；
• 短信模板需要先报备审核（见 模板被拒的常见原因）。