Autenticação Formato do pedido Formato da resposta Códigos de erro Limites de pedidos Ambiente de teste Versão e alterações Ajuda

Visão Geral

A API da Buluthat permite integrar o seu software existente (CRM, ERP, comércio eletrónico, helpdesk) com a sua central na nuvem: click-to-call, controlo de chamadas, gestão de filas, lista negra, ficheiros de áudio, campanhas de chamadas automáticas, tarefas do assistente de voz e código de verificação por voz.

Todos os endpoints são HTTP simples; as respostas são JSON. Utiliza-se a partir de qualquer linguagem, com um cliente HTTP.

Endereço base: https://api.buluthat.com/api/

Autenticação

Todos os endpoints são iguais A chave de API utiliza. A chave no painel Conta e Apoio > Chaves de API é gerada na página, pelo responsável da conta; bt_ começa por e só é apresentada uma vez, no momento em que é gerada.

A chave é enviada no cabeçalho em cada pedido:

Authorization: Bearer bt_xxxxxxxx

Authorization se não for possível definir o cabeçalho X-Api-Key: bt_xxxxxxxx também é aceite. A chave no URL (?key=) está desativado nas chaves novas.

Cada chave está associada a uma única conta de cliente e acede apenas aos dados dessa conta. Na chave âmbito está definido:

Âmbito	Endpoints
`call`	Gestão de chamadas, filas, estados dos agentes
`autocall`	Chamadas automáticas (para compatibilidade com integrações antigas, abre também os endpoints do assistente de voz, do OTP por voz e de chamadas)
`voicebot`	Assistente de voz
`voice_otp`	Código de verificação por voz
`sms`	API de SMS

Pedido fora do âmbito 403 scope_denied, módulo desativado na sua conta 403 module_disabled devolve. Para a chave lista de IP autorizados, data de validade e assinatura HMAC de pedido obrigatória pode ser definido; todos Segurança da API na página.

Não utilize a chave no lado do navegador (JavaScript); chame sempre a partir do seu próprio servidor. Se suspeitar de fuga, no painel escolha "Renovar chave > Fechar a anterior de imediato" e a anterior fica logo inválida.

Formato do pedido

Operações de leitura GET, operações que alteram POST (nos ficheiros de áudio PUT/DELETE).
Corpo do POST application/json ou application/x-www-form-urlencoded pode ser.
Operação nos endpoints de integração action é escolhido com o parâmetro (?action=create_campaign).
Os carimbos de data/hora são da hora da Turquia (2026-09-18 10:12:03).
Números de telefone 05xxxxxxxxx, 5xxxxxxxxx ou 905xxxxxxxxx é aceite no formato; nas respostas devolve-se normalizado.

Formato da resposta

Os endpoints de integração (autocall, voicebot, voice_otp) devolvem sempre um envelope:

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

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

Os endpoints da central (begin_call, queues, blocked_numbers…) comunicam com código de estado HTTP: em caso de sucesso 200 OK e no corpo o resultado (matriz JSON ou texto simples), em caso de erro 4xx e no corpo uma mensagem de erro em turco.

Códigos de erro

HTTP	`code`	Significado
400	`validation_failed`	A validação do campo falhou; a mensagem explica o motivo
401	`missing_token` / `invalid_token` / `token_expired`	Sem chave, inválida ou expirada
401	`query_key_disabled` / `signature_*`	A chave foi enviada no URL ou a assinatura não pôde ser validada (Segurança da API)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	Módulo desativado, âmbito insuficiente ou IP não autorizado
404	`*_not_found`	O registo não existe ou pertence a outro cliente
405	`method_not_allowed`	Foi enviado um GET para uma operação que exige POST
422	(específico do endpoint)	Recusa por regra de negócio: quota, prazo, sem linha, etc.
413	`payload_too_large`	O corpo do pedido excede 5 MB
429	`rate_limited` / `ip_locked`	Limite de pedidos excedido ou IP temporariamente bloqueado por demasiadas tentativas falhadas
503	`db_unavailable`	Falha temporária do serviço; tente novamente daqui a pouco

Limites de pedidos

Limite	Predefinido
Por chave	120 pedidos por minuto (pode ser reduzido nas definições da chave)
Soma de todas as chaves da conta	600 pedidos por minuto
Estados dos agentes	e, além disso, 2 pedidos por minuto (para o estado em direto, prefira webhook)
Chamadas automáticas `add_leads`	5.000 registos num só pedido

Nas respostas X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset chegam os cabeçalhos. Em caso de excesso 429 Too Many Requests e Retry-After devolve o cabeçalho. Em cada resposta, o X-Request-Id partilhe o valor nos pedidos de apoio.

Ambiente de teste

Não existe sandbox separada; experimente na sua conta com uma extensão de teste e uma pequena campanha. As campanhas de chamadas automáticas status: "draft" criar com e results/summary pode chamar estes endpoints mesmo sem dados. No código de verificação por voz, envie para o seu próprio número; a tarifação segue as regras do seu pacote.

Versão e alterações

Os endpoints mantêm compatibilidade retroativa; acrescentam-se campos novos e o nome e o tipo dos campos existentes não mudam. Um campo que vá ser removido é anunciado no painel e nesta página com pelo menos 90 dias de antecedência.

Ajuda

Se ficar bloqueado durante a integração, abra no Centro de Apoio do painel um registo com o assunto "Integração / API"; anexe o seu pedido/resposta de exemplo e vemos em conjunto.

Segurança da API