Visión general
La API de Buluthat le permite integrar su software actual (CRM, ERP, comercio electrónico, mesa de ayuda) con su central en la nube: clic para llamar, control de llamadas, gestión de colas, lista negra, archivos de audio, campañas de llamadas automáticas, tareas del asistente de voz y código de verificación por voz.
Todos los endpoints son HTTP plano; las respuestas son JSON. Se usa desde cualquier lenguaje con un cliente HTTP.
Dirección base: https://api.buluthat.com/api/
Autenticación
Todos los endpoints son iguales La clave de API utiliza. La clave en el panel Cuenta y Soporte > Claves de API desde la página, lo genera el responsable de la cuenta; bt_ comienza con y se muestra una sola vez en el momento en que se genera.
La clave se envía en cada solicitud en el encabezado:
Authorization: Bearer bt_xxxxxxxxAuthorization si no se puede establecer el encabezado X-Api-Key: bt_xxxxxxxx también se acepta. La clave en la URL (?key=) el envío está desactivado en las claves nuevas.
Cada clave está vinculada a una única cuenta de cliente y solo accede a los datos de esa cuenta. En la clave alcance está definido:
| Alcance | Endpoints |
|---|---|
call | Gestión de llamadas, colas, estados de agentes |
autocall | Llamadas automáticas (por compatibilidad con integraciones antiguas, también habilita los endpoints de asistente de voz, OTP de voz y llamadas) |
voicebot | Asistente de voz |
voice_otp | Código de verificación por voz |
sms | API de SMS |
Solicitud fuera del alcance 403 scope_denied, módulo desactivado en su cuenta 403 module_disabled devuelve. A la clave lista de IP permitidas, fecha de vencimiento y firma HMAC de solicitud obligatoria se pueden definir; todos Seguridad de la API en la página.
No use la clave en el navegador (JavaScript); llámela siempre desde su propio servidor. Si cree que se filtró, pulse en el panel "Renovar clave > Cerrar la anterior de inmediato" y la anterior quedará invalidada al instante.
Formato de solicitud
- Operaciones de lectura
GET, operaciones que modificanPOST(en los archivos de audioPUT/DELETE). - Cuerpo del POST
application/jsonoapplication/x-www-form-urlencodedpuede ser. - Operación en los endpoints de integración
actionse selecciona con el parámetro (?action=create_campaign). - Las marcas de tiempo son hora de Turquía (
2026-09-18 10:12:03). - Números de teléfono
05xxxxxxxxx,5xxxxxxxxxo905xxxxxxxxxse acepta en el formato; en las respuestas vuelve normalizado.
Formato de respuesta
Los endpoints de integración (autocall, voicebot, voice_otp) siempre devuelven un sobre:
{ "ok": true, "data": { } }{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }Los endpoints de la central (begin_call, queues, blocked_numbers…) responden con código de estado HTTP: en caso de éxito 200 OK y en el cuerpo, el resultado (matriz JSON o texto plano); en caso de error 4xx y en el cuerpo, un mensaje de error en turco.
Códigos de error
| HTTP | code | Significado |
|---|---|---|
| 400 | validation_failed | No se superó la validación del campo; el mensaje explica el motivo |
| 401 | missing_token / invalid_token / token_expired | Clave inexistente, no válida o vencida |
| 401 | query_key_disabled / signature_* | La clave llegó en la URL o no se pudo verificar la firma (Seguridad de la API) |
| 403 | module_disabled / scope_denied / ip_not_allowed | Módulo desactivado, alcance insuficiente o IP no permitida |
| 404 | *_not_found | No existe el registro o pertenece a otro cliente |
| 405 | method_not_allowed | Llegó un GET a una operación que requiere POST |
| 422 | (específico del endpoint) | Rechazo por regla de negocio: cuota, tiempo, sin línea, etc. |
| 413 | payload_too_large | El cuerpo de la solicitud supera 5 MB |
| 429 | rate_limited / ip_locked | Se superó el límite de velocidad o la IP está bloqueada temporalmente por demasiados intentos fallidos |
| 503 | db_unavailable | Problema temporal del servicio; inténtelo de nuevo en un momento |
Límites de velocidad
| Límite | Predeterminado |
|---|---|
| Por clave | 120 solicitudes por minuto (se puede reducir desde los ajustes de la clave) |
| Suma de todas las claves de la cuenta | 600 solicitudes por minuto |
| Estados de agentes | además, 2 solicitudes por minuto (para el estado en vivo, prefiera el webhook) |
Llamadas automáticas add_leads | 5.000 registros por solicitud |
En las respuestas X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset llegan los encabezados. Al superarlo 429 Too Many Requests y Retry-After devuelve el encabezado. En cada respuesta el X-Request-Id comparta el valor en las solicitudes de soporte.
Entorno de pruebas
No hay un sandbox aparte; pruebe en su cuenta con una extensión de prueba y una campaña pequeña. Las campañas de llamadas automáticas status: "draft" créelo con y results/summary puede llamar a los endpoints incluso sin datos. En el código de verificación por voz, envíelo a su propio número; la tarificación se aplica según las reglas de su paquete.
Versión y cambios
Los endpoints se mantienen compatibles hacia atrás; se agregan campos nuevos y no cambian el nombre ni el tipo de los existentes. Un campo que vaya a eliminarse se anuncia con al menos 90 días de antelación en el panel y en esta página.
Ayuda
Si se atasca durante la integración, abra un registro con el tema "Integración / API" en el Centro de Soporte del panel; adjunte su solicitud y respuesta de ejemplo y lo revisamos juntos.