O POST /api/v1/convert converte um link por chamada no seu link de afiliado. Ele continua no ar para quem já integrou, mas o /convert-links aceita o mesmo corpo e até 150 links por chamada, então é o caminho para integração nova.
- Método:
POST - Path:
https://botdoafiliado.com/api/v1/convert - Auth: header
X-API-Key(obrigatório), chave de nível Padrão (write) ou Total (admin). Veja autenticação.
Request
{
"url": "https://exemplo.com/produto",
"telegram_user_id": 123
}| Campo | Obrigatório | O que faz |
|---|---|---|
url |
sim | O link completo a converter, com http:// ou https://. |
telegram_user_id |
não | Com o módulo Tracking por usuário, cada pessoa ganha a sua versão do link. Sem o módulo, todos recebem o mesmo link. |
chat_id / origem |
não | Destino do link, para medir o clique por grupo, canal ou site. Veja Origem do link. |
refresh |
não | Só Mercado Livre: gera um link novo na API do ML e grava por cima do guardado. Em outra loja, 400 com “refresh só vale para link do Mercado Livre.”. |
bot_id |
— | Ignorado: o bot é sempre o da chave. |
Response (200)
{
"success": true,
"url_original": "https://exemplo.com/produto",
"url_resolvida": "https://exemplo.com/produto",
"affiliate_url": "https://...",
"final_url": "https://...",
"site": "exemplo.com",
"provider": "awin"
}Use o final_url: é o link já com a política de encurtamento do bot aplicada (por exemplo amzn.to na Amazon e ofertou.ai nas lojas sem encurtador próprio). O affiliate_url é o link antes do encurtador.
Erros
| HTTP | Quando |
|---|---|
401 |
Sem X-API-Key ou chave inválida. A mensagem lembra que, no navegador, o caminho é a Embed Key. |
403 |
insufficient_scope: chave de nível Leitura. |
400 |
Corpo inválido, refresh fora do Mercado Livre ou loja sem integração ativa. O error vem em texto para mostrar ao usuário, como “Ainda não tenho uma integração ativa para esse site. Verifique se o plugin/rota está configurado no painel.”. |
A mesma URL convertida de novo devolve a mesma resposta: cada data center guarda o resultado por 60 segundos, além do cache do conversor. O refresh passa por cima dos dois. Lista completa em erros e limites.
Migrar para /convert-links
- Troque a URL do endpoint de
/api/v1/convertpara/api/v1/convert-links. - Continue enviando
url(modo single): a resposta tem os mesmos campos. - Quando quiser otimizar, agrupe várias URLs em
urlse itereitems[].