A API usa chaves de API geradas no painel. Cada chave tem o formato bk_<prefixo>.<segredo> e é enviada no header X-API-Key. O recurso exige o módulo Conexão IA e API ativo.
Como chegar
Menu → Configurar → API e IA (MCP). A tela tem três abas: Chaves de API, Script do site e IA (MCP).
Acima das abas fica o ID do bot, com o botão de copiar. Use onde a integração pedir bot_id. A chave de API já identifica o bot sozinha, então o ID só serve em integração que peça o ID explícito.
Gerar uma chave
- Ative o módulo Conexão IA e API.
- Em API e IA (MCP), abra a aba Chaves de API.
- No card Criar chave de API, dê um nome (opcional), escolha o nível de permissão e clique em Criar.
- Copie a chave completa no card que aparece (“Chave criada no nível … (copie agora)”). Se precisar dela de novo, use Mostrar na linha da chave (só o dono e os admins da organização, e só em chaves criadas a partir de 16/10/2026).
O botão Conectar IA (MCP) → do card da chave criada leva à aba IA (MCP), já com a chave nos comandos. Veja O que é o MCP.
A lista de chaves
| Coluna | O que mostra |
|---|---|
| Nome | O nome da chave, quando foi criada e quando foi usada pela última vez (“nunca usada”, “usada há 2 h”). Chave revogada ganha o selo Revogada. |
| Chave | O prefixo da chave e o botão Mostrar, que abre a chave inteira (com Ocultar e copiar). Em chave criada antes de 16/10/2026, o painel avisa que não dá para mostrar de novo. |
| Nível | Seletor com Leitura, Padrão e Total. Trocar vale na chamada seguinte. |
| Origem padrão | O destino que vale quando a chamada não diz onde o link vai. Definir ou Trocar abre o tipo (Grupo, Canal, Site ou Post) e o id. |
| Última coluna (sem título) | Revogar e Excluir. |
Você pode ter várias chaves, uma por integração ou sistema, e revogar cada uma separadamente.
Origem padrão
A Origem padrão vale quando a chamada à API não manda chat_id nem origem: é como se mandasse esta origem. Serve para a integração que só converte e não sabe dizer o destino. Grupo e canal do Telegram usam o id do chat (ex.: -1001234567890); site usa o domínio (ex.: meusite.com.br); post usa um nome curto (ex.: black-friday). O id tem até 64 caracteres, só letras, números e _ : . -. O que vier no pedido ganha da origem padrão. Detalhes em convert-links.
Usar nas chamadas
curl -X POST "https://botdoafiliado.com/api/v1/convert-links" \
-H "content-type: application/json" \
-H "X-API-Key: bk_xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{"url":"https://www.aliexpress.com/item/100500..."}'Níveis de permissão
Cada chave é criada com um nível, escolhido no painel. Ele limita o que aquela chave pode fazer na API (e nas ferramentas MCP, que passam pelos mesmos endpoints):
| Nível | Vale para | Endpoints |
|---|---|---|
Leitura (read) |
Consulta que não devolve link de afiliado nem gasta cota do marketplace | /api/v1/coupons (GET), /coupons/categories, /templates (GET), /showcase/items (GET), /bot, /userbot/config (GET), /userbot/history, /userbot/preview-rules |
Padrão (write) |
Leitura + operação do dia a dia | tudo de Leitura + /convert, /convert-links, /product, /product/shipping, /product/history, /execute, /chat, /search-products, /amazon-prices, /promo-card, /watermark, /showcase/items (POST e DELETE) |
Total (admin) |
Tudo, incluindo importar e apagar cupom, editar os textos do bot e configurar o Puxador | tudo de Padrão + /coupons/ingest, /coupons/ingest-plugins, /coupons/{id} (DELETE), /coupons/{id}/activate, /templates (POST), /userbot/config (POST) |
Os endpoints /userbot/* são os do Puxador.
Todo endpoint que devolve link de afiliado é Padrão, mesmo parecendo consulta: /product, /search-products e /amazon-prices geram ou entregam link com a sua tag, que é exatamente o que uma chave de Leitura não deve fazer. Leitura fica com o que só informa: frete, histórico de preço, cupons e templates já cadastrados.
Ao conectar a IA por MCP com login (OAuth), sem colar chave, o nível vem do seu papel na organização: dono e admin → Total, postador → Padrão.
Uma chamada acima do nível da chave responde 403 com insufficient_scope:
{ "success": false, "error": "insufficient_scope" }O nível é escolhido na criação e pode ser trocado depois: na lista de chaves, a coluna Nível é um seletor. Trocar não rotaciona o segredo: a mesma chave continua valendo, com o novo nível já na chamada seguinte. Chaves criadas antes desta mudança continuam em Total até você rebaixá-las.
Use o menor nível que resolve: a chave que só lê preço no seu site não precisa poder apagar cupom.
Revogar ou excluir
Na aba Chaves de API, cada chave tem duas ações:
- Revogar: desativa a chave (efeito imediato), mas mantém o registro na lista (útil para auditoria e histórico). Não dá para reativá-la. Integrações que usam a chave (MCP, API, IA) param na hora.
- Excluir: remove a chave de vez da lista. Chaves já revogadas também podem ser excluídas para limpar a lista.
Segurança
- A chave completa não fica armazenada em texto puro: a API confere a chave por um hash, e a cópia que o Mostrar abre fica cifrada. Na lista, o painel mostra só o prefixo, e cada Mostrar fica no log de auditoria.
- Crie a chave no menor nível que atende à integração (ver Níveis de permissão).
- Revogue ou exclua chaves comprometidas na aba Chaves de API (efeito imediato).
- Nunca exponha a chave no front-end; use-a apenas no servidor.
Próximo: faça sua primeira conversão em convert-links.