开通宝塔面板API网站前必须确认三件事：域名解析就绪、SSL证书策略明确、PHP版本与运行目录权限已预设；API需开启并绑定固定IP；需配置跨域头且type参数须用数字0/1/2。
宝塔面板API开通网站前必须确认的三件事
宝塔面板的 /site/create_site 接口本身不支持“完全零配置开通”，必须提前手动或脚本完成：域名解析就绪、SSL证书策略明确、PHP版本与运行目录权限已预设。WHMCS调用失败 80% 源于这三项没对齐。
- 宝塔需开启 API（
面板设置 → API接口 → 开启并设置密钥），且该密钥必须绑定固定 IP（WHMCS服务器出口IP），否则返回403 Forbidden - 宝塔默认关闭跨域，WHMCS发请求会卡在预检（OPTIONS），必须在宝塔配置文件中手动加
add_header 'Access-Control-Allow-Origin' '*';（仅调试用，生产环境建议限定域名） - 宝塔 API 的
type参数不是填 “php” 或 “static”，而是填数字：0（静态）、1（PHP）、2（反向代理）——填错直接返回500
WHMCS自定义钩子中调用宝塔API的关键写法
不能用 WHMCS 自带的 curl_init() 直接裸调，必须封装签名逻辑。宝塔 API 要求每个请求携带 request_token（由 md5(密钥 + 时间戳) 生成）和 request_time（秒级时间戳），超时 5 分钟即失效。
- 在 WHMCS
includes/hooks/bt_auto_create.php中写钩子，监听AfterModuleCreateAccount事件 -
request_time必须用time()，不能用date('U')或毫秒时间，否则验签失败 - POST body 必须是
application/x-www-form-urlencoded，不能传 JSON，否则返回invalid request - 示例关键字段：
data[webname]=example.com&data[domain]=example.com&data[type]=1&data[version]=80&data[ps]=whmcs-12345（version是 PHP 版本 ID，查/system/get_php_version接口获取）
自动创建后无法访问？检查宝塔的两个隐藏开关
即使 API 返回 {"status":true,"msg":"添加成功"}，网站仍可能 502 或 403，大概率是以下两个未显式开启：
- 宝塔后台「网站」列表里新站默认「未启动」，API 创建后不会自动启用，必须额外调用
/site/start_site，传id=数字ID（ID 需从创建响应的data.id字段提取） - 「防跨站攻击」开关默认开启，但 WHMCS 分配的用户目录（如
/www/wwwroot/client123/）若未加入白名单，PHP 会报open_basedir restriction。需调用/site/set_path接口更新path并同步写入open_basedir字段
HTTPS 自动部署的兼容性陷阱
宝塔的 /site/create_site 接口不支持同时申请 Let’s Encrypt 证书。想全自动 HTTPS，必须分两步走：
- 先创建 HTTP 站点（
type=1，不传ssl字段） - 再调用
/site/ssl接口，传id=站点ID&email=admin@example.com&domains[]=example.com，注意domains必须是数组格式，单域名也要写成domains[]=example.com - Let’s Encrypt 频控严格：同一域名 7 天内最多重试 5 次，WHMCS 钩子需加失败重试退避（如首次失败后等 60 秒再试），否则容易触发
urn:acme:error:rateLimited
最常被忽略的是：宝塔 SSL 接口返回成功，但证书实际可能还在异步生成中，立刻 reload Nginx 会失败。得轮询 /site/get_ssl 直到 data.status == 1 再执行 /site/reload_web。
