# API: endpoint legado POST /convert

> O POST /api/v1/convert do Bot do Afiliado converte 1 link por chamada, exige chave de API de nível Padrão ou Total e continua no ar; o /convert-links aceita o mesmo corpo e até 150 links, por isso é o caminho recomendado.

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

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

## Request

```json
{
  "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](/docs/api/convert-links/#origem-do-link-opcional)**. |
| `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)

```json
{
  "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](/docs/api/erros-e-limites/)**.

## Migrar para /convert-links

1. Troque a URL do endpoint de `/api/v1/convert` para `/api/v1/convert-links`.
2. Continue enviando `url` (modo single): a resposta tem os mesmos campos.
3. Quando quiser otimizar, agrupe várias URLs em `urls` e itere `items[]`.

## Perguntas frequentes

### O endpoint legado POST /convert da API ainda funciona?

Sim. Ele continua no ar e converte 1 link por chamada. O /convert-links faz o mesmo com o mesmo corpo e aceita até 150 links.

### Preciso mudar o payload para migrar do /convert legado para o /convert-links?

Não, no modo single. Troque a URL do endpoint para /convert-links e continue enviando url.

### Por que o /convert responde 403 insufficient_scope?

A chave é de nível Leitura. Converter link exige nível Padrão (write) ou Total (admin); troque o nível na lista de chaves, sem rotacionar o segredo.

### O bot_id no corpo escolhe o bot?

Não. O bot é sempre o da chave de API; bot_id no corpo é ignorado. Para converter no navegador, use uma Embed Key com /embed/v1/convert-links.

### Para que serve o refresh no /convert?

Só para link do Mercado Livre: ignora o link guardado e gera outro na API do ML. Em link de outra loja, refresh devolve 400.