Authentification Format des requêtes Format de réponse Codes d'erreur Limites de débit Environnement de test Version et modifications Aide

Vue d'ensemble

L'API Buluthat vous permet d'intégrer vos logiciels existants (CRM, ERP, e-commerce, service desk) à votre standard cloud : clic pour appeler, contrôle d'appels, gestion des files, liste noire, fichiers audio, campagnes d'appels automatiques, missions de l'assistant vocal et code de vérification vocal.

Tous les points d'accès sont en HTTP simple ; les réponses sont en JSON. S'utilise depuis n'importe quel langage, avec un client HTTP.

Adresse de base : https://api.buluthat.com/api/

Authentification

Tous les points d'accès sont identiques la clé API utilise. La clé est dans le panneau Compte et Assistance > Clés API depuis la page, générée par le responsable du compte ; bt_ commence par et n'est affiché qu'une seule fois, au moment de sa génération.

La clé est envoyée dans l'en-tête à chaque requête :

Authorization: Bearer bt_xxxxxxxx

Authorization si l'en-tête ne peut pas être défini X-Api-Key: bt_xxxxxxxx est aussi accepté. La clé dans l'URL (?key=) est désactivé pour les nouvelles clés.

Chaque clé est liée à un seul compte client et n'accède qu'aux données de ce compte. Dans la clé portée est défini :

Portée	Points d'accès
`call`	Gestion des appels, files, statuts des agents
`autocall`	Appels automatiques (ouvre aussi les points d'accès de l'assistant vocal, de l'OTP vocal et des appels pour la compatibilité avec les anciennes intégrations)
`voicebot`	Assistant vocal
`voice_otp`	Code de vérification vocal
`sms`	API SMS

Requête hors portée 403 scope_denied, module désactivé dans votre compte 403 module_disabled renvoie. À la clé liste d'IP autorisées, date d'expiration et signature de requête HMAC obligatoire peut être défini ; tous Sécurité de l'API dans la page.

N'utilisez pas votre clé côté navigateur (JavaScript) ; appelez toujours depuis votre propre serveur. Si vous pensez qu'elle a fuité, cliquez dans le panneau sur « Renouveler la clé > Fermer l'ancienne immédiatement » ; l'ancienne devient invalide sur-le-champ.

Format des requêtes

Opérations de lecture GET, opérations modifiant POST (pour les fichiers audio PUT/DELETE).
Corps POST application/json ou application/x-www-form-urlencoded peut être.
Opération sur les points d'accès d'intégration action se choisit avec le paramètre (?action=create_campaign).
Les horodatages sont à l'heure de Turquie (2026-09-18 10:12:03).
Numéros de téléphone 05xxxxxxxxx, 5xxxxxxxxx ou 905xxxxxxxxx est accepté sous la forme ; renvoyé normalisé dans les réponses.

Format de réponse

Les points d'accès d'intégration (autocall, voicebot, voice_otp) renvoient toujours une enveloppe :

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

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

Les points d'accès du standard (begin_call, queues, blocked_numbers…) s'expriment par le code d'état HTTP : en cas de succès 200 OK et le résultat dans le corps (tableau JSON ou texte brut), en cas d'erreur 4xx et un message d'erreur en turc dans le corps.

Codes d'erreur

HTTP	`code`	Signification
400	`validation_failed`	La validation du champ a échoué ; le message en indique la cause
401	`missing_token` / `invalid_token` / `token_expired`	Clé absente, invalide ou expirée
401	`query_key_disabled` / `signature_*`	La clé est arrivée dans l'URL ou la signature n'a pas pu être vérifiée (Sécurité de l'API)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	Module désactivé, portée insuffisante ou IP non autorisée
404	`*_not_found`	Aucun enregistrement, ou appartient à un autre client
405	`method_not_allowed`	GET reçu pour une opération qui exige POST
422	(propre au point d'accès)	Refus pour règle métier : quota, durée, absence de ligne, etc.
413	`payload_too_large`	Le corps de la requête dépasse 5 Mo
429	`rate_limited` / `ip_locked`	Limite de débit dépassée ou IP temporairement verrouillée en raison de trop nombreuses tentatives erronées
503	`db_unavailable`	Problème de service temporaire ; réessayez dans un instant

Limites de débit

Limite	Par défaut
Par clé	120 requêtes par minute (peut être réduit dans les paramètres de la clé)
Total de toutes les clés du compte	600 requêtes par minute
Statuts des agents	ainsi que 2 requêtes par minute (pour l'état en direct, privilégiez le webhook)
Appels automatiques `add_leads`	5.000 enregistrements par requête

Dans les réponses X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset les en-têtes arrivent. En cas de dépassement 429 Too Many Requests et Retry-After l'en-tête est renvoyé. Dans chaque réponse, l'en-tête X-Request-Id communiquez la valeur dans vos demandes d'assistance.

Environnement de test

Il n'y a pas de bac à sable distinct ; essayez avec un poste de test et une petite campagne dans votre compte. Les campagnes d'appels automatiques status: "draft" générez avec et results/summary vous pouvez appeler les points d'accès même sans données. Pour le code de vérification vocal, envoyez vers votre propre numéro ; la facturation suit les règles de votre forfait.

Version et modifications

Les points d'accès sont maintenus rétrocompatibles ; de nouveaux champs s'ajoutent, le nom et le type des champs existants ne changent pas. Un champ voué à disparaître est annoncé au moins 90 jours à l'avance dans le panneau et sur cette page.

Aide

Si vous êtes bloqué pendant l'intégration, ouvrez dans le panneau, via le Centre d'assistance, un dossier au sujet « Intégration / API » ; joignez votre exemple de requête/réponse et nous regarderons ensemble.

Sécurité de l'API