Panoramica
L'API di Buluthat consente di integrare i Suoi software esistenti (CRM, ERP, e-commerce, help desk) con il centralino cloud: click-to-call, controllo chiamate, gestione code, lista nera, file audio, campagne di chiamata automatica, incarichi dell'assistente vocale e codice di verifica vocale.
Tutti gli endpoint usano HTTP semplice; le risposte sono in JSON. Si usano da qualsiasi linguaggio, con un client HTTP.
Indirizzo base: https://api.buluthat.com/api/
Autenticazione
Tutti gli endpoint uguali La chiave API utilizza. La chiave nel pannello Account e Assistenza > Chiavi API dalla pagina, viene generata dal referente dell'account; bt_ inizia con e viene mostrata una sola volta, al momento della generazione.
La chiave viene inviata nell'intestazione a ogni richiesta:
Authorization: Bearer bt_xxxxxxxxAuthorization se non è possibile impostare l'intestazione X-Api-Key: bt_xxxxxxxx è accettato anche. La chiave nell'URL (?key=) è disattivato per le nuove chiavi.
Ogni chiave è legata a un solo account cliente e accede solo ai dati di quell'account. Nella chiave ambito è definito:
| Ambito | Endpoint |
|---|---|
call | Gestione chiamate, code, stati degli operatori |
autocall | Chiamata automatica (per compatibilità con le integrazioni esistenti apre anche gli endpoint dell'assistente vocale, dell'OTP vocale e delle chiamate) |
voicebot | Assistente vocale |
voice_otp | Codice di verifica vocale |
sms | API SMS |
Richiesta fuori ambito 403 scope_denied, modulo disattivato nell'account 403 module_disabled restituisce. Alla chiave elenco di IP autorizzati, data di scadenza e firma HMAC della richiesta obbligatoria si può definire; tutti Sicurezza API nella pagina.
Non usi la chiave lato browser (JavaScript); la chiami sempre dal Suo server. Se sospetta una fuga, dal pannello scelga "Rigenera la chiave > Chiudi subito la vecchia": la vecchia diventa invalida all'istante.
Formato della richiesta
- Operazioni di lettura
GET, operazioni che modificanoPOST(nei file audioPUT/DELETE). - Corpo del POST
application/jsonoppureapplication/x-www-form-urlencodedpuò essere. - Operazione sugli endpoint di integrazione
actionsi seleziona con il parametro (?action=create_campaign). - I timestamp sono in ora turca (
2026-09-18 10:12:03). - Numeri di telefono
05xxxxxxxxx,5xxxxxxxxxoppure905xxxxxxxxxè accettato nei formati; nelle risposte torna normalizzato.
Formato della risposta
Gli endpoint di integrazione (autocall, voicebot, voice_otp) restituiscono sempre una busta:
{ "ok": true, "data": { } }{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }Gli endpoint del centralino (begin_call, queues, blocked_numbers…) comunicano con il codice di stato HTTP: in caso di successo 200 OK e nel corpo il risultato (array JSON o testo semplice), in caso di errore 4xx e nel corpo un messaggio di errore in turco.
Codici di errore
| HTTP | code | Significato |
|---|---|---|
| 400 | validation_failed | Convalida del campo non superata; il messaggio ne indica il motivo |
| 401 | missing_token / invalid_token / token_expired | Chiave assente, non valida o scaduta |
| 401 | query_key_disabled / signature_* | La chiave è arrivata nell'URL oppure la firma non ha potuto essere verificata (Sicurezza API) |
| 403 | module_disabled / scope_denied / ip_not_allowed | Modulo disattivato, ambito insufficiente o IP non autorizzato |
| 404 | *_not_found | Il record non esiste o appartiene a un altro cliente |
| 405 | method_not_allowed | È arrivato un GET per un'operazione che richiede POST |
| 422 | (specifico dell'endpoint) | Rifiuto per regola di business: quota, durata, nessuna linea, ecc. |
| 413 | payload_too_large | Il corpo della richiesta supera 5 MB |
| 429 | rate_limited / ip_locked | Limite di frequenza superato oppure IP bloccato temporaneamente per troppi tentativi errati |
| 503 | db_unavailable | Problema temporaneo del servizio; riprovi tra poco |
Limiti di frequenza
| Limite | Predefinito |
|---|---|
| Per chiave | 120 richieste al minuto (riducibile dalle impostazioni della chiave) |
| Somma di tutte le chiavi dell'account | 600 richieste al minuto |
| Stati degli operatori | inoltre 2 richieste al minuto (per lo stato in tempo reale preferite il webhook) |
Chiamata automatica add_leads | 5.000 record per richiesta |
Nelle risposte X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset arrivano le intestazioni. In caso di superamento 429 Too Many Requests e Retry-After viene restituita l'intestazione. In ogni risposta X-Request-Id condividete il valore nelle richieste di assistenza.
Ambiente di test
Non esiste una sandbox separata; provi nel Suo account con un interno di prova e una piccola campagna. Le campagne di chiamata automatica status: "draft" creare con e results/summary potete chiamare gli endpoint anche senza dati. Per il codice di verifica vocale inviate al Vostro numero; la tariffazione segue le regole del Suo pacchetto.
Versione e modifiche
Gli endpoint sono mantenuti retrocompatibili; si aggiungono nuovi campi, nome e tipo dei campi esistenti non cambiano. Un campo che verrà rimosso viene annunciato almeno 90 giorni prima nel pannello e in questa pagina.
Aiuto
Se vi bloccate durante l'integrazione, aprite dal Centro Assistenza nel pannello una richiesta con oggetto "Integrazione / API"; allegate la richiesta/risposta di esempio, la esaminiamo insieme.