Authentifizierung Anfrageformat Antwortformat Fehlercodes Ratenbegrenzungen Testumgebung Version und Änderungen Hilfe

Überblick

Mit der Buluthat-API integrieren Sie Ihre bestehende Software (CRM, ERP, E-Commerce, Helpdesk) in Ihre Cloud-Telefonanlage: Click-to-call, Anrufsteuerung, Warteschlangenverwaltung, Sperrliste, Audiodateien, Auto-Call-Kampagnen, Aufgaben des Sprachassistenten und Sprach-Bestätigungscodes.

Alle Endpunkte laufen über reines HTTP; die Antworten sind JSON. Nutzbar aus jeder Sprache mit einem HTTP-Client.

Basisadresse: https://api.buluthat.com/api/

Authentifizierung

Alle Endpunkte gleich den API-Schlüssel verwendet. Den Schlüssel im Panel Konto und Support > API-Schlüssel auf der Seite, wird vom Kontobevollmächtigten erzeugt; bt_ beginnt mit und wird nur im Moment der Erzeugung einmal angezeigt.

Der Schlüssel wird bei jeder Anfrage im Header gesendet:

Authorization: Bearer bt_xxxxxxxx

Authorization wenn der Header nicht gesetzt werden kann X-Api-Key: bt_xxxxxxxx wird ebenfalls akzeptiert. Den Schlüssel in der URL (?key=) ist bei neuen Schlüsseln deaktiviert.

Jeder Schlüssel ist an genau ein Kundenkonto gebunden und greift nur auf dessen Daten zu. Beim Schlüssel Geltungsbereich ist definiert:

Geltungsbereich	Endpunkte
`call`	Anrufverwaltung, Warteschlangen, Agentenstatus
`autocall`	Auto-Call (öffnet aus Kompatibilitätsgründen mit älteren Integrationen auch die Endpunkte für Sprachassistent, Sprach-OTP und Anrufe)
`voicebot`	Sprachassistent
`voice_otp`	Sprach-Bestätigungscode
`sms`	SMS-API

Anfrage außerhalb des Geltungsbereichs 403 scope_denied, in Ihrem Konto deaktiviertes Modul 403 module_disabled kommt zurück. Dem Schlüssel Liste zugelassener IPs, Ablaufdatum und verpflichtende HMAC-Anfragesignatur können definiert werden; alle API-Sicherheit auf der Seite.

Verwenden Sie Ihren Schlüssel nicht im Browser (JavaScript); rufen Sie immer von Ihrem eigenen Server aus auf. Wenn Sie ein Leck vermuten, wählen Sie im Panel „Schlüssel erneuern > Alten sofort schließen“; der alte wird augenblicklich ungültig.

Anfrageformat

Lesevorgänge GET, ändernde Vorgänge POST (bei Audiodateien PUT/DELETE).
POST-Body application/json oder application/x-www-form-urlencoded möglich.
Vorgang bei Integrationsendpunkten action wird mit dem Parameter gewählt (?action=create_campaign).
Zeitstempel in türkischer Zeit (2026-09-18 10:12:03).
Telefonnummern 05xxxxxxxxx, 5xxxxxxxxx oder 905xxxxxxxxx wird im Format akzeptiert; in den Antworten kommt es normalisiert zurück.

Antwortformat

Integrationsendpunkte (autocall, voicebot, voice_otp) liefern immer einen Umschlag zurück:

{ "ok": true, "data": { } }

{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }

Die Telefonanlagen-Endpunkte (begin_call, queues, blocked_numbers …) sprechen über HTTP-Statuscodes: bei Erfolg 200 OK und das Ergebnis im Body (JSON-Array oder Klartext), bei Fehler 4xx und eine türkische Fehlermeldung im Body.

Fehlercodes

HTTP	`code`	Bedeutung
400	`validation_failed`	Feldvalidierung fehlgeschlagen; die Meldung nennt den Grund
401	`missing_token` / `invalid_token` / `token_expired`	Ist für den Schlüssel eine IP-Liste definiert, werden nur Anfragen von diesen Adressen durchgelassen
401	`query_key_disabled` / `signature_*`	Schlüssel kam in der URL oder die Signatur konnte nicht verifiziert werden (API-Sicherheit)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	Modul deaktiviert, Geltungsbereich unzureichend oder IP nicht zugelassen
404	`*_not_found`	Eintrag nicht vorhanden oder gehört einem anderen Kunden
405	`method_not_allowed`	Für einen POST-Vorgang kam GET an
422	(endpunktspezifisch)	Ablehnung wegen Geschäftsregel: Kontingent, Dauer, keine Leitung usw.
413	`payload_too_large`	Der Anfrage-Body überschreitet 5 MB
429	`rate_limited` / `ip_locked`	Ratenbegrenzung überschritten oder IP wegen zu vieler fehlerhafter Versuche vorübergehend gesperrt
503	`db_unavailable`	Vorübergehendes Dienstproblem; versuchen Sie es gleich noch einmal

Ratenbegrenzungen

Limit	Standard
Pro Schlüssel	120 Anfragen pro Minute (in den Schlüsseleinstellungen senkbar)
Summe aller Schlüssel des Kontos	600 Anfragen pro Minute
Agentenstatus	zusätzlich 2 Anfragen pro Minute (für den Live-Status bevorzugen Sie Webhooks)
Auto-Call `add_leads`	5.000 Einträge pro Anfrage

In den Antworten X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset Header kommen. Bei Überschreitung 429 Too Many Requests und Retry-After Header wird zurückgegeben. Der Header in jeder Antwort X-Request-Id Teilen Sie den Wert in Supportanfragen mit.

Testumgebung

Es gibt keine separate Sandbox; testen Sie in Ihrem Konto mit einer Test-Nebenstelle und einer kleinen Kampagne. Auto-Call-Kampagnen status: "draft" erzeugen mit und results/summary können Sie auch ohne Daten aufrufen. Senden Sie beim Sprach-Bestätigungscode an Ihre eigene Nummer; die Abrechnung erfolgt nach den Regeln Ihres Pakets.

Version und Änderungen

Endpunkte bleiben abwärtskompatibel; neue Felder kommen hinzu, Namen und Typen bestehender Felder ändern sich nicht. Ein Feld, das entfernt wird, wird mindestens 90 Tage vorher im Panel und auf dieser Seite angekündigt.

Hilfe

Wenn Sie bei der Integration nicht weiterkommen, eröffnen Sie im Support-Center des Panels einen Eintrag zum Thema „Integration / API“; fügen Sie Ihre Beispielanfrage und -antwort bei, wir schauen gemeinsam darauf.

API-Sicherheit