API: converter links de afiliado (POST /convert-links)

Converte 1 ou vários links na mesma requisição, com processamento em paralelo e cache por item.

• Método: POST
• Path: /api/v1/convert-links
• Auth: header X-API-Key (obrigatório). Para uso no navegador/site, use uma Embed Key (travada por domínio) com /embed/v1/convert-links — veja Script do site.

Links de encurtadores com verificação automática Kutt/Afilimais também podem ser resolvidos antes da conversão, inclusive em domínio próprio. O link de destino passa pelo conversor de afiliado configurado para a loja.

Modo single (1 link)

{
  "url": "https://exemplo.com/produto",
  "telegram_user_id": 123
}

Resposta (200):

{
  "success": true,
  "url_original": "https://exemplo.com/produto",
  "url_resolvida": "https://exemplo.com/produto",
  "affiliate_url": "https://afiliado.com/...",
  "final_url": "https://encurtado.com/...",
  "site": "amazon",
  "provider": "amazon",
  "tracking_id": "track-xyz"
}

Modo batch (vários links)

{
  "urls": [
    "https://exemplo.com/produto-1",
    "https://exemplo.com/produto-2"
  ]
}

Resposta (200) — itens individuais, sem falhar o request inteiro:

{
  "success": true,
  "items": [
    { "ok": true, "url_original": "...", "affiliate_url": "...", "final_url": "...", "site": "awin", "provider": "awin" },
    { "ok": false, "url_original": "...", "affiliate_url": null, "final_url": null, "error": "..." }
  ]
}

Origem do link (opcional)

Diga para onde o link vai e cada destino ganha o seu link curto, com os cliques contados separados.

• chat_id: ID do grupo ou canal do Telegram onde o link vai ser postado (número, ou texto só com dígitos e -). Conversa privada com o bot é ignorada.
• origem: destino fora do Telegram, {"tipo": "...", "id": "..."}. O tipo é grupo, canal, site ou post; o id tem até 64 caracteres entre letras, números e _ : . - (o domínio do site, por exemplo). Se vier chat_id, ele vale.

{
  "urls": ["https://exemplo.com/produto"],
  "chat_id": -1001234567890
}

{
  "url": "https://exemplo.com/produto",
  "origem": { "tipo": "site", "id": "meusite.com.br" }
}

• Sem os dois campos (ou com null neles) e sem origem padrão na chave, nada muda.
• Origem padrão da chave: em API e IA MCP → Chaves de API, a coluna Origem padrão guarda um destino com os mesmos tipos e regras do origem. Ele vale quando o pedido não manda chat_id nem origem, como se mandasse essa origem: serve para a integração que só converte e não sabe dizer o destino. O que vier no pedido ganha dela, e um chat_id de conversa privada continua sem origem. No MCP conectado com essa chave, ela vale só no convert_links e no add_coupon com convert_url, que convertem por este endpoint; nas outras ferramentas, como create_offer_post, run_command e get_product, o link sai sem origem.
• A mesma URL para dois destinos gera dois links curtos. A exceção são os links que saem direto da loja, sem passar pelo encurtador (Shopee, AliExpress, Mercado Livre e Amazon pela integração da própria loja): esses são iguais em qualquer destino.
• tipo fora da lista ou id com outro caractere devolve 400.

Regras e boas práticas

• urls aceita de 1 a 150 itens; a ordem de entrada é preservada.
• Faça retry apenas dos itens com ok: false.
• Comece com lotes de 20 a 50 URLs conforme o seu timeout.
• final_url é a URL após a política de encurtamento (pode ser igual a affiliate_url).

Links que já pertencem ao afiliado

Links de produto Amazon já atribuídos à tag configurada para a conversão podem retornar o mesmo endereço com sucesso, inclusive quando reutilizados do cache. O tracking específico do usuário, quando configurado, tem prioridade. Sem comprovação da tag correta no destino Amazon, devolver a URL de origem continua gerando conversion_returned_source_url.

Exemplo (curl)

curl -X POST "https://botdoafiliado.com/api/v1/convert-links" \
  -H "content-type: application/json" \
  -H "X-API-Key: <SUA_API_KEY>" \
  -d '{"urls":["https://www.aliexpress.com/item/100500...","https://www.amazon.com.br/dp/..."]}'

Para dados de produto (título/preço/imagem) use /product.