Uwierzytelnianie Format żądania Format odpowiedzi Kody błędów Limity zapytań Środowisko testowe Wersje i zmiany Pomoc

Przegląd

API Buluthat pozwala zintegrować Twoje oprogramowanie (CRM, ERP, e-commerce, help desk) z chmurową centralą: click-to-call, sterowanie połączeniami, zarządzanie kolejkami, czarna lista, pliki audio, kampanie automatycznych połączeń, zadania asystenta głosowego i głosowy kod weryfikacyjny.

Wszystkie punkty końcowe działają przez czysty HTTP; odpowiedzi są w JSON. Używane z dowolnego języka, klientem HTTP.

Adres bazowy: https://api.buluthat.com/api/

Uwierzytelnianie

Wszystkie punkty końcowe takie same klucz API używa. Klucz w panelu Konto i wsparcie > Klucze API ze strony, generowane przez osobę upoważnioną konta; bt_ zaczyna się od i jest pokazywany tylko w chwili wygenerowania, jednorazowo.

Klucz jest wysyłany w nagłówku w każdym żądaniu:

Authorization: Bearer bt_xxxxxxxx

Authorization jeśli nie można ustawić nagłówka X-Api-Key: bt_xxxxxxxx także jest akceptowane. Klucz w adresie URL (?key=) w nowych kluczach jest wyłączone.

Każdy klucz jest powiązany z jednym kontem klienta i ma dostęp wyłącznie do danych tego konta. W kluczu zakres jest zdefiniowane:

Zakres	Punkty końcowe
`call`	Zarządzanie połączeniami, kolejki, statusy konsultantów
`autocall`	Automatyczne połączenia (dla zgodności ze starszymi integracjami otwiera także punkty końcowe asystenta głosowego, głosowego OTP i połączeń)
`voicebot`	Asystent głosowy
`voice_otp`	Głosowy kod weryfikacyjny
`sms`	API SMS

Żądanie spoza zakresu 403 scope_denied, moduł wyłączony na koncie 403 module_disabled zwraca. Do klucza lista dozwolonych IP, data ważności i obowiązkowy podpis HMAC żądania można zdefiniować; wszystkie Bezpieczeństwo API na stronie.

Nie używaj klucza po stronie przeglądarki (JavaScript); zawsze wywołuj go z własnego serwera. Jeśli sądzisz, że wyciekł, w panelu wybierz „Odnów klucz > Zamknij stary natychmiast” — stary klucz natychmiast przestanie działać.

Format żądania

Operacje odczytu GET, operacje zmieniające POST (w plikach audio PUT/DELETE).
Treść POST application/json lub application/x-www-form-urlencoded może być.
Operacja w punktach końcowych integracji action wybierane parametrem (?action=create_campaign).
Znaczniki czasu są podawane w czasie tureckim (2026-09-18 10:12:03).
Numery telefonów 05xxxxxxxxx, 5xxxxxxxxx lub 905xxxxxxxxx akceptowane w formacie; w odpowiedziach zwracane w postaci znormalizowanej.

Format odpowiedzi

Punkty końcowe integracji (autocall, voicebot, voice_otp) zawsze zwracają kopertę:

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

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

Punkty końcowe centrali (begin_call, queues, blocked_numbers…) komunikują się kodem statusu HTTP: przy powodzeniu 200 OK oraz wynik w treści (tablica JSON lub czysty tekst), przy błędzie 4xx oraz komunikat o błędzie po turecku w treści.

Kody błędów

HTTP	`code`	Znaczenie
400	`validation_failed`	Walidacja pola nie powiodła się; komunikat podaje przyczynę
401	`missing_token` / `invalid_token` / `token_expired`	Brak klucza, jest nieprawidłowy lub wygasł
401	`query_key_disabled` / `signature_*`	Klucz przyszedł w adresie URL lub nie udało się zweryfikować podpisu (Bezpieczeństwo API)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	Moduł wyłączony, zakres niewystarczający lub IP niedozwolone
404	`*_not_found`	Brak rekordu lub należy do innego klienta
405	`method_not_allowed`	Przyszło GET dla operacji wymagającej POST
422	(specyficzne dla punktu końcowego)	Odmowa wynikająca z reguł biznesowych: limit, czas, brak linii itp.
413	`payload_too_large`	Treść żądania przekracza 5 MB
429	`rate_limited` / `ip_locked`	Limit zapytań przekroczony lub adres IP tymczasowo zablokowany z powodu zbyt wielu błędnych prób
503	`db_unavailable`	Chwilowy problem z usługą; spróbuj ponownie za chwilę

Limity zapytań

Limit	Domyślnie
Na klucz	120 żądań na minutę (można obniżyć w ustawieniach klucza)
Łącznie wszystkich kluczy konta	600 żądań na minutę
Statusy konsultantów	dodatkowo 2 żądań na minutę (dla statusu na żywo preferuj webhook)
Automatyczne połączenia `add_leads`	5.000 rekordów w jednym żądaniu

W odpowiedziach X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset nagłówki przychodzą. Przy przekroczeniu 429 Too Many Requests i Retry-After zwraca nagłówek. W każdej odpowiedzi X-Request-Id udostępnij wartość w zgłoszeniach do wsparcia.

Środowisko testowe

Nie ma osobnego sandboxa; wypróbuj na koncie z numerem wewnętrznym testowym i małą kampanią. Kampanie automatycznych połączeń status: "draft" utwórz przez i results/summary te punkty końcowe możesz wywołać nawet bez danych. W głosowym kodzie weryfikacyjnym wyślij na swój numer; rozliczanie następuje według reguł Twojego pakietu.

Wersje i zmiany

Punkty końcowe są utrzymywane z zachowaniem wstecznej zgodności; dodawane są nowe pola, nazwa i typ istniejących pól się nie zmieniają. Pole do usunięcia jest ogłaszane w panelu i na tej stronie co najmniej 90 dni wcześniej.

Pomoc

Jeśli utkniesz podczas integracji, w Centrum Pomocy w panelu załóż zgłoszenie z tematem „Integracja / API”; dołącz przykładowe żądanie/odpowiedź, spojrzymy razem.

Bezpieczeństwo API