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

> Endpoint para converter um ou vários links de afiliado em uma requisição (batch de até 150). Parâmetros, exemplos de request e response e boas práticas.

- URL: https://botdoafiliado.com/docs/api/convert-links/
- Publicado em: 2026-05-29
- Atualizado em: 2026-05-29
- Índice da documentação para IA: https://botdoafiliado.com/llms.txt

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](/docs/api/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)

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

Resposta (200):

```json
{
  "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)

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

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

```json
{
  "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.

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

```json
{
  "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)

```bash
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](/docs/api/product/)**.

## Perguntas frequentes

### Quantas URLs posso enviar por requisição no endpoint /convert-links em lote?

Até 150 no modo batch (campo urls). No modo single, envie url.

### No modo batch do /convert-links, se uma URL falhar a requisição inteira falha?

Não, no modo batch. Cada item tem seu próprio ok/erro; o request não falha por causa de um item.

### Preciso enviar bot_id no /convert-links ou a X-API-Key já identifica o bot?

Não. O bot é sempre identificado pela X-API-Key (o campo bot_id, se enviado, é ignorado). A X-API-Key passou a ser obrigatória neste endpoint. Para uso direto no navegador/site, use uma Embed Key (travada por domínio) com /embed/v1/convert-links.