概览
Buluthat API 让您将现有软件（CRM、ERP、电商、客服系统）与云总机集成：点击拨号、呼叫控制、队列管理、黑名单、语音文件、自动外呼活动、语音助手任务和语音验证码。
所有接口均为普通 HTTP；响应为 JSON。可使用任何语言，通过 HTTP 客户端调用。
基础地址： https://api.buluthat.com/api/
身份验证
所有接口一致 API 密钥 使用。密钥在面板中 账户与支持 > API 密钥 页面，由账户授权人生成； bt_ 以此开头，且仅在生成时显示一次。
密钥在每次请求的请求头中发送：
Authorization: Bearer bt_xxxxxxxxAuthorization 如果无法设置请求头 X-Api-Key: bt_xxxxxxxx 也被接受。密钥在 URL 中（?key=）对新密钥已关闭。
每个密钥只绑定一个客户账户，且只能访问该账户的数据。在密钥中 权限范围 已定义：
| 权限范围 | 接口 |
|---|---|
call | 通话管理、队列、坐席状态 |
autocall | 自动外呼（为兼容旧版集成，也会开放语音助手、语音 OTP 和呼叫接口） |
voicebot | 语音助手 |
voice_otp | 语音验证码 |
sms | SMS API |
超出权限范围的请求 403 scope_denied，账户中已关闭的模块 403 module_disabled 返回。对密钥 IP 白名单, 到期日期 和 强制 HMAC 请求签名 可定义；全部 API 安全 页面中。
请勿在浏览器端（JavaScript）使用密钥；始终从您自己的服务器调用。若怀疑泄露，请在面板中选择“轮换密钥 > 立即关闭旧密钥”，旧密钥立即失效。
请求格式
- 读取操作
GET，会更改数据的操作POST（语音文件中PUT/DELETE). - POST 正文
application/json或application/x-www-form-urlencoded可能。 - 集成接口中的操作
action通过参数选择（?action=create_campaign). - 时间戳为土耳其时间（
2026-09-18 10:12:03). - 电话号码
05xxxxxxxxx,5xxxxxxxxx或905xxxxxxxxx格式接受；响应中返回规范化形式。
响应格式
集成接口（autocall、voicebot、voice_otp）总是返回封装结构：
{ "ok": true, "data": { } }{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }总机接口（begin_call、queues、blocked_numbers……）通过 HTTP 状态码通信：成功时 200 OK 且正文中为结果（JSON 数组或纯文本），出错时 4xx 且正文中为土耳其语错误消息。
错误码
| HTTP | code | 含义 |
|---|---|---|
| 400 | validation_failed | 区域验证未通过；消息会说明原因 |
| 401 | missing_token / invalid_token / token_expired | 密钥无效、缺失或已过期 |
| 401 | query_key_disabled / signature_* | 密钥出现在 URL 中，或签名无法验证（API 安全) |
| 403 | module_disabled / scope_denied / ip_not_allowed | 模块未开通、权限不足或 IP 不在白名单中 |
| 404 | *_not_found | 记录不存在或属于其他客户 |
| 405 | method_not_allowed | 对需要 POST 的操作使用了 GET |
| 422 | （接口专属） | 业务规则拒绝：配额、时长、无线路等。 |
| 413 | payload_too_large | 请求正文超过 5 MB |
| 429 | rate_limited / ip_locked | 已超出速率限制，或 IP 因多次错误尝试被临时锁定 |
| 503 | db_unavailable | 临时服务故障；请稍后重试 |
速率限制
| 限制 | 默认 |
|---|---|
| 每个密钥 | 每分钟 120 次请求（可在密钥设置中调低） |
| 账户所有密钥的合计 | 每分钟 600 次请求 |
| 坐席状态 | 另外每分钟 2 次请求（实时状态建议使用 Webhook） |
自动外呼 add_leads | 单次请求 5.000 条记录 |
在响应中 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 请求头会返回。超出时 429 Too Many Requests 和 Retry-After 请求头返回。每个响应中的 X-Request-Id 请在支持工单中提供该值。
测试环境
没有独立的沙盒；请在您的账户中使用一个测试分机和小规模活动进行试用。自动外呼活动 status: "draft" 生成后 results/summary 您无需等待数据就可以调用这些接口。语音验证码请向您自己的号码发送；计费按您的套餐规则进行。
版本与变更
接口保持向后兼容；只会新增字段，现有字段的名称和类型不会改变。即将移除的字段至少提前 90 天在面板和本页公告。
帮助
在集成过程中遇到问题，请在面板内的帮助中心以“集成 / API”为主题创建工单；附上示例请求/响应，我们一起排查。