Como funciona a API de links de afiliado em lote?
A API recebe URLs e aplica os plugins, as credenciais e as rotas do seu bot. O endpoint principal é POST /api/v1/convert-links: envie urls para um lote de até 150 itens ou url para uma conversão individual. A chave enviada em X-API-Key identifica o bot que vai executar o trabalho.
No lote, a resposta preserva a ordem de entrada e traz ok em cada item. Um HTTP 200 com success: true não significa que todos os links foram convertidos. Seu sistema precisa conferir cada resultado, guardar os que deram certo e tratar os erros antes de tentar novamente. O contrato de conversão em lote mostra as duas formas de chamada e seus campos.
affiliate_url contém o link de afiliado gerado. final_url contém o endereço após a política de encurtamento e pode ser igual a ele. Essa diferença permite usar o endereço de saída adequado sem presumir que todas as lojas terão um link curto no mesmo domínio.
Qual endpoint atende cada etapa da integração?
Converter um endereço, consultar o produto e montar o texto da oferta são operações diferentes. Escolher a rota que atende à tarefa evita depender de campos que aquela resposta não promete entregar.
| Sua tarefa | Endpoint | O que considerar |
|---|---|---|
| Converter uma lista de links | POST /api/v1/convert-links |
Até 150 URLs, com resultado por item. |
| Consultar um produto por URL | POST /api/v1/product |
Retorna os dados disponíveis e o link de afiliado. |
| Montar o texto de uma oferta | POST /api/v1/execute |
Usa o formato do bot; a chamada não publica o texto. |
| Consultar cupons cadastrados | GET /api/v1/coupons |
Exige o módulo Cupons e usa paginação. |
| Ler formatos de mensagens | GET /api/v1/templates |
Serve para consultar os templates existentes. |
Há uma referência interativa da API com os contratos registrados em OpenAPI. A especificação pública fica em https://botdoafiliado.com/api/openapi.json, para consulta e importação em ferramentas de desenvolvimento. Informações como preço anterior, parcelas e estoque dependem do retorno da loja; o sistema que consome a API deve aceitar sua ausência.
Como escolher o nível de permissão da chave?
Uma chave Padrão atende à conversão e às consultas que devolvem link de afiliado. Leitura é destinada às consultas permitidas sem gerar esse link. Total acrescenta operações de gerenciamento, como alterar templates e manter cupons, respeitando também os módulos necessários.
É possível manter chaves separadas por integração e mudar o nível de cada uma sem substituir seu segredo. Isso permite, por exemplo, revogar o acesso de uma automação sem trocar a chave de outro sistema. O guia de autenticação e permissões relaciona os níveis aos endpoints. Respostas de falta de permissão pedem revisão da chave; limites de requisições pedem controle de ritmo e novas tentativas com espera.
Como converter links de um site sem expor a API key?
Chamadas com X-API-Key pertencem ao servidor da sua aplicação. Para o navegador, o módulo oferece o Script do site, que usa uma Embed Key própria e permite cadastrar os domínios autorizados. O script troca links de lojas na página, incluindo conteúdo carregado depois da abertura.
O atributo data-no-affiliate permite preservar um link específico. Também existe um endpoint de conversão para uso com a Embed Key. A configuração e os exemplos estão no guia do Script do site. Esse recurso atende a páginas que já contêm links; a Página de chat do plano base atende ao visitante que prefere colar um endereço e receber a resposta.
Como os eventos chegam ao n8n, Make ou Zapier?
Os webhooks de saída enviam JSON para uma URL HTTPS pública. Você escolhe entre os eventos disponíveis, como entrada ou saída de leads, mudanças em grupos e números, campanha sem grupo aberto e falha de envio. A integração depende de esses eventos ocorrerem nos recursos que sua organização utiliza.
As entregas reais passam por fila e pelo ciclo de envio de cinco minutos. O botão de teste envia na hora, portanto ele não representa o prazo dos eventos da operação. Cada entrega tem assinatura HMAC-SHA256 para validação no destino, histórico e novas tentativas quando há falha. A documentação de webhooks de saída explica o contrato de verificação e o tratamento das entregas.
API REST e MCP precisam de assinaturas diferentes?
As duas interfaces fazem parte do mesmo módulo Conexão IA e API. A REST atende a sistemas que enviam requisições estruturadas e processam as respostas por código. A Conexão IA e MCP leva tarefas do bot a clientes como ChatGPT e Claude, para pedidos feitos durante uma conversa.
Você pode usar ambas sem contratar duas vezes o módulo. Recursos adicionais mantêm suas próprias condições: consultar e gerenciar cupons exige Cupons, por exemplo. O canal de acesso muda a forma de trabalhar; as contas de afiliado e a configuração usadas na conversão continuam sendo as do bot.