API文档

案例0.5：带 from_domain 发送短信（推荐服务器端对接）

<?php
/**
 * 带 from_domain 的短信发送示例（适配白名单）
 * 适合：服务器端 curl / SDK / 跨域后端对接
 * from_domain 直接用 $_SERVER['HTTP_HOST'] 即可
 */
function sendSmsWithDomain($apiBase, $apiToken, $phone, $fromDomain, $signatureId, $templateId, $options = []) {
    $url = $apiBase . '/api/member/sms-send?api_token=' . urlencode($apiToken);
    $data = array_merge([
        'phone'        => $phone,
        'scene'        => 'api',
        'code_length'  => 4,
        'valid_time'   => 300,
        'signature_id' => $signatureId,   // ★ 必传：签名ID
        'template_id'  => $templateId,    // ★ 必传：模板ID
        'from_domain'  => $fromDomain,    // ★ 关键：加上这一行，白名单设置了这个值也必须传
    ], $options);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    // 所有业务错误都是 HTTP 200，通过 body.code 字段判断（避免被 SDK 误判成"网络异常"）
    if ($httpCode !== 200) {
        return ['success' => false, 'msg' => 'HTTP网络错误: ' . $httpCode];
    }
    $result = json_decode($response, true);
    if (!is_array($result)) {
        return ['success' => false, 'msg' => '响应非JSON: ' . $response];
    }
    $result['success'] = ($result['code'] === 0);
    return $result;
}

// 调用示例：白名单配了 就直接用 $_SERVER['HTTP_HOST'] 传值
$apiBase      = $_SERVER['HTTP_HOST'];       // API域名
$apiToken     = '你的会员API_TOKEN';
$fromDomain   = '$_SERVER['HTTP_HOST']';                // ★ 填当前调用方的域名推荐直接使用变量 $_SERVER['HTTP_HOST']
$signatureId  = 1;                              // ★ 必传：签名ID（通过接口查询可用签名获取）
$templateId   = 1;                              // ★ 必传：模板ID（通过接口查询可用模板获取）
$phone        = '13800138000';

$result = sendSmsWithDomain($apiBase, $apiToken, $phone, $fromDomain, $signatureId, $templateId);
if ($result['success']) {
    echo "发送成功，验证码：" . $result['data']['verify_code'] . "\n";
    echo "扣费方式：" . $result['data']['cost_type'] . "\n";
} else {
    // msg 字段就是明确的错误信息（域名非白名单 / 条数不足 / SDK报错 等）
    echo "发送失败：[" . $result['code'] . "] " . $result['msg'] . "\n";
}
?>

案例0：先查询可用的签名和模板

<?php
/**
 * 先调用此接口获取可用的签名ID和模板ID
 * 建议在系统初始化时调用一次，结果可缓存到本地
 */
function getSmsResources($apiBase, $apiToken) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiBase . '/api/member/sms-resources?api_token=' . urlencode($apiToken));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    $response = curl_exec($ch);
    curl_close($ch);

    $result = json_decode($response, true);
    if ($result['code'] !== 0) {
        throw new Exception('获取资源失败: ' . $result['msg']);
    }
    return $result['data'];  // ['signatures' => [...], 'templates' => [...]]
}

// 调用并打印
$resources = getSmsResources('https://www.wndog.com', '你的API_TOKEN');
echo "可用的签名:\n";
foreach ($resources['signatures'] as $sig) {
    echo "  ID={$sig['id']}  名称={$sig['name']}\n";
}
echo "可用的模板:\n";
foreach ($resources['templates'] as $tpl) {
    echo "  ID={$tpl['id']}  场景={$tpl['scene_label']}  CODE={$tpl['template_code']}\n";
}
?>

案例1：使用cURL直接调用（推荐）

<?php
/**
 * 万能狗短信API调用示例
 */

// ====== 配置 ======
$apiBase     = 'https://www.wndog.com';     // 万能狗域名
$apiToken    = '你的会员API_TOKEN';         // 会员中心 → API Token
$phone       = '13800138000';              // 接收短信的手机号
$signatureId = 1;                           // ★ 必传：签名ID（通过查询可用签名接口获取）
$templateId  = 1;                           // ★ 必传：模板ID（通过查询可用模板接口获取）

// ====== 方式一：JSON传参（推荐） ======
function sendSms($apiBase, $apiToken, $phone, $signatureId, $templateId, $options = []) {
    $url = $apiBase . '/api/member/sms-send?api_token=' . urlencode($apiToken);

    $data = array_merge([
        'phone'        => $phone,
        'scene'        => 'api',
        'code_length'  => 4,
        'valid_time'   => 300,
        'signature_id' => $signatureId,   // ★ 必传：签名ID
        'template_id'  => $templateId,    // ★ 必传：模板ID
    ], $options);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        return ['success' => false, 'msg' => 'HTTP错误: ' . $httpCode];
    }
    return json_decode($response, true);
}

// ====== 方式二：表单传参 ======
function sendSmsByForm($apiBase, $apiToken, $phone, $signatureId, $templateId) {
    $url = $apiBase . '/api/member/sms-send?api_token=' . urlencode($apiToken);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(['phone' => $phone, 'scene' => 'api', 'signature_id' => $signatureId, 'template_id' => $templateId]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// ====== 方式三：使用GuzzleHttp（需composer安装guzzlehttp/guzzle） ======
function sendSmsByGuzzle($apiBase, $apiToken, $phone, $signatureId, $templateId) {
    $client = new \GuzzleHttp\Client();
    $response = $client->post($apiBase . '/api/member/sms-send', [
        'query'   => ['api_token' => $apiToken],
        'json'    => ['phone' => $phone, 'scene' => 'api', 'signature_id' => $signatureId, 'template_id' => $templateId],
        'timeout' => 30,
    ]);
    return json_decode($response->getBody(), true);
}

// ====== 调用示例 ======
$signatureId = 1;   // ★ 必传：签名ID（通过查询可用签名接口获取）
$templateId  = 1;   // ★ 必传：模板ID（通过查询可用模板接口获取）

$result = sendSms($apiBase, $apiToken, $phone, $signatureId, $templateId);

if ($result && $result['code'] === 0) {
    echo "发送成功！\n";
    echo "验证码: " . $result['data']['verify_code'] . "\n";
    echo "扣费方式: " . $result['data']['cost_type'] . "\n";
    echo "短信条数剩余: " . $result['data']['sms_count_remaining'] . "\n";
    echo "余额剩余: " . $result['data']['balance_remaining'] . "\n";
} else {
    echo "发送失败: " . ($result['msg'] ?? '未知错误') . "\n";
    echo "错误码: " . ($result['code'] ?? 'N/A') . "\n";
}
?>

案例2：登录验证码场景（使用login模板）

<?php
// 发送登录验证码
$phone = $_POST['phone'] ?? '';
$signatureId = 1;   // ★ 必传：签名ID
$templateId  = 1;   // ★ 必传：模板ID（对应login场景的模板）

$result = sendSms('https://www.wndog.com', '你的API_TOKEN', $phone, $signatureId, $templateId, [
    'scene'        => 'login',
    'code_length'  => 6,
    'valid_time'   => 600,   // 10分钟有效
]);

if ($result['code'] === 0) {
    // ★★★ 关键点 ★★★
    // 必须使用接口返回的 verify_code（这是接口实际下发的验证码，与用户手机收到的一致）
    // 不要自己用 mt_rand() 等函数生成，否则会与用户收到的对不上
    $_SESSION['sms_code']    = $result['data']['verify_code'];  // 用接口返回的！
    $_SESSION['sms_expire']  = time() + 600;
    $_SESSION['sms_phone']   = $phone;
    echo json_encode(['success' => true, 'msg' => '验证码已发送']);
} else {
    echo json_encode(['success' => false, 'msg' => $result['msg']]);
}
?>

案例3：批量发送（循环调用）

<?php
// 批量发送短信（注意：每个手机号都单独调用一次API）
$phones = ['13800138000', '13900139000', '13700137000'];
$success = 0;
$failed  = [];

foreach ($phones as $phone) {
    $result = sendSms('https://www.wndog.com', '你的API_TOKEN', $phone);
    if ($result['code'] === 0) {
        $success++;
    } else {
        $failed[$phone] = $result['msg'];
    }
    sleep(1);  // 间隔1秒，避免频率限制
}

echo "成功: $success, 失败: " . count($failed) . "\n";
print_r($failed);
?>

案例4：查询发送记录

<?php
// 查询最近的发送记录
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.wndog.com/api/member/sms-logs?api_token=你的API_TOKEN&page=1&page_size=20&status=1');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] === 0) {
    echo "总共发送: " . $result['data']['total'] . " 条\n";
    foreach ($result['data']['list'] as $log) {
        echo "[" . $log['created_at'] . "] " . $log['phone'] . " - " .
             ($log['cost_type'] === 'sms_count' ? "扣短信条数" : "扣余额¥" . $log['cost_amount']) . "\n";
    }
}
?>

6. 错误码定义

7. 安全措施

常见问题

Q: 如何开启短信功能？

A: 登录会员中心 → 设置 → 短信服务，打开短信开关。

Q: 为什么业务错误（403/429/500）返回的 HTTP 状态码是 200？

A: 因为 fetch / axios / 大部分自研 SDK 会把 HTTP 非 200 的响应直接抛进 catch，统一显示"网络异常"，把真实的 msg（域名非白名单、条数不足、阿里云签名报错等）完全吞掉，导致用户根本不知道错在哪。
所以本系统所有业务错误都用 HTTP 200 返回，真实错误码放在 JSON code 字段里，错误原因在 msg 字段里，客户端只要判断 body.code === 0 就是成功，否则直接显示 body.msg，不会再出现"网络异常"三个字。

Q: 短信包用完了怎么办？

A: 可以在会员中心 → 增值服务中购买短信包，也可以不购买直接从余额扣费（按单条短信价格扣除）。

Q: 发送失败会扣费吗？

A: 不会。系统使用事务处理，发送失败时已扣除的条数或余额会自动退还。如果是阿里云SDK错误，msg 字段会直接附带 SDK 真实错误信息（如 RAM权限不足、签名未过审、模板变量不对），方便排查。