# API REST do Bot do Afiliado: visão geral

> Visão geral da API REST do Bot do Afiliado — base URL, autenticação por API key, endpoints de conversão e produto, formatos e limites.

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

> **Esta seção é para programadores.** Para usar o bot no dia a dia (converter links, postar ofertas, cuidar dos grupos) você não precisa dela. Se você é afiliado e quer começar, vá para **[Comece por aqui](/docs/comecando/comece-por-aqui/)**.

A **API REST** permite converter links e obter dados de produto a partir de **qualquer sistema**. É a mesma engine usada pelo bot do Telegram.

> 📖 **Referência completa e interativa:** explore e teste **todos** os endpoints na **[referência Scalar da API »](/docs/api/referencia/)** — com busca, schemas de request/response e _try it out_ direto no navegador.

## Base URL

```
https://botdoafiliado.com/api/v1/
```

## Autenticação

Use o header **`X-API-Key`** com uma chave gerada no painel (formato `bk_...`). Requer o **módulo de API** ativo. Veja **[autenticação](/docs/api/autenticacao/)**.

```
X-API-Key: bk_xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Endpoints

Todos os endpoints abaixo estão detalhados (schemas, exemplos e _try it out_) na **[referência interativa](/docs/api/referencia/)**.

### Conversão — [ver na referência »](/docs/api/referencia/#tag/conversao)

| Endpoint | Método | O que faz |
|---|---|---|
| `/api/v1/convert-links` | POST | Converte **1 ou vários** links (até 150). Guia: **[convert-links](/docs/api/convert-links/)**. |
| `/api/v1/convert` | POST | Conversão unitária (legado). Guia: **[convert (legado)](/docs/api/convert-legado/)**. |

### Produtos — [ver na referência »](/docs/api/referencia/#tag/produtos)

| Endpoint | Método | O que faz |
|---|---|---|
| `/api/v1/product` | POST | Dados completos do produto (título, preço, preço "de", **estoque** quando o marketplace fornece) + link de afiliado + histórico de preço. Guia: **[product](/docs/api/product/)**. |
| `/api/v1/product/history` | GET | Só o histórico de preços de um produto. |
| `/api/v1/product/shipping` | POST | Frete de um produto AliExpress. |
| `/api/v1/search-products` | POST | Busca produtos por título no marketplace escolhido (`site`: shopee, aliexpress, amazon, magalu, kabum…). |
| `/api/v1/amazon-prices` | POST | Preços frescos de até 10 ASINs da Amazon de uma vez. |

### Ofertas — [ver na referência »](/docs/api/referencia/#tag/ofertas)

| Endpoint | Método | O que faz |
|---|---|---|
| `/api/v1/execute` | POST | Monta um **post de oferta pronto** (mesmo formato do bot) a partir de links, preços e cupom. |
| `/api/v1/chat` | POST | Processa uma mensagem como se fosse enviada ao bot. Comando administrativo (`/template`, `/feature`, `/broadcast`, `/metricas`) é recusado aqui; use o `/api/v1/execute` com chave de nível Total. |
| `/api/v1/templates` | GET/POST | Lê e edita os templates de mensagem do bot. |
| `/api/v1/promo-card` | POST | Gera a **arte de promo** (card 1080×1080 ou story 1080×1920) com foto, preços, cupom e gatilho — devolve o PNG (ou grava e devolve a URL com `store:true`). |
| `/api/v1/watermark` | POST | Aplica a **marca d'água** (logo e/ou texto salvos em Fotos e chamada) na foto do produto — devolve o PNG (ou grava e devolve a URL com `store:true`). Campos no corpo (`text`, `logo_url`, `position`, `opacity`, `size`) valem só para a chamada. |
| `/api/v1/showcase/items` | GET/POST | Lista e publica ofertas na **[vitrine pública](/docs/comecando/vitrine/)** do bot (`DELETE /api/v1/showcase/items/{id}` remove). |

As imagens da arte de promo precisam usar HTTPS nos CDNs de AliExpress, Shopee,
Mercado Livre, Amazon, Magalu ou Kabum, ou uma URL de mídia do próprio Bot do
Afiliado. Para imagens de outros sites, faça o upload no painel. A arte aceita
até 4 MiB por imagem; a foto original (`raw:true`), até 8 MiB. SVG não é aceito.

### Cupons — [ver na referência »](/docs/api/referencia/#tag/cupons)

| Endpoint | Método | O que faz |
|---|---|---|
| `/api/v1/coupons` | GET/POST | Lista e cadastra cupons do bot. |
| `/api/v1/coupons/{id}` | DELETE | Desativa um cupom. |
| `/api/v1/coupons/{id}/activate` | POST | Reativa um cupom. |
| `/api/v1/coupons/categories` | GET | Lista as categorias de cupom. |
| `/api/v1/coupons/ingest` | POST | Ingestão de cupons em massa (texto bruto → cupons). |

### Integração do NerdCupons

As rotas servidor-servidor `POST /api/v1/coupons/interactions/issue`,
`/consume` e `/stats` admitem interações com nonce de uso único, cotas persistentes
e isolamento pelo bot da chave autenticada. Exigem nível Padrão (`write`) ou
Total (`admin`) e módulo de cupons ativo; não são chamadas diretamente pelo navegador.
Não há alteração automática das permissões da chave.

A integração preserva os agregados históricos e separa revelar o cupom de registrar
o uso. Repetir a mesma confirmação não soma novamente. Se o serviço falhar, o cupom
continua disponível, mas o site informa que uso, voto ou avaliação não foi registrado.
Essas métricas são sinais públicos limitados, não contagens verificadas de pessoas.

## Formatos e limites

- Corpo e resposta em **JSON**.
- **Batch:** até **150 URLs** por requisição em `/convert-links`.
- Erros e limites detalhados em **[erros e limites](/docs/api/erros-e-limites/)**.
- Referência interativa em **[Scalar](/docs/api/referencia/)**.

## Próximos passos

1. Ative o **[módulo de API](/docs/planos/modulos/)**.
2. Gere uma **[API key](/docs/api/autenticacao/)**.
3. Faça sua primeira chamada em **[convert-links](/docs/api/convert-links/)**.

## Montar oferta com preço anterior e parcelas

O `POST /api/v1/execute` aceita os dados por URL no `input`. Use `system_action: true` com `oferta` ou `cupom` para montar o post com os formatos de oferta, mesmo se existir um comando personalizado com o mesmo nome.

```json
{
  "trigger": "oferta",
  "system_action": true,
  "format": "text",
  "input": {
    "urls": ["https://www.loja.com/produto"],
    "price_overrides": { "https://www.loja.com/produto": "199,90" },
    "de_overrides": { "https://www.loja.com/produto": "299,90" },
    "installments_overrides": {
      "https://www.loja.com/produto": { "count": 10, "amount": 19.99, "interest_free": true }
    }
  }
}
```

Sem override, usa os dados da loja quando disponíveis. Em `de_overrides`, uma string vazia remove o anterior; em `installments_overrides`, `null` remove as parcelas daquele produto. Parcelamento incompleto ou inválido devolve `invalid_installments`. `data.items[]` inclui `old_price`, `installments` e `image_url`, além dos campos existentes. Para o bloco aparecer no texto, use `{linhadopreco}` no formato do bot.

## Cupons por site

`GET /api/v1/coupons/categories` lista as lojas com `id`, `name`, `domain`, `slug`, `aliases` e `logoUrl`. `GET /api/v1/coupons` aceita `site_id` ou `site` (nome, slug ou domínio); os filtros legados `category_id`/`category` continuam aceitos. Cada cupom devolve `siteId` e `categoryId` iguais.

`POST /api/v1/coupons/ingest` usa os mesmos campos de loja. A escolha explícita tem prioridade; sem ela, o sistema tenta o mapeamento da URL. `source_url` pode informar a URL original para identificar a loja, mantendo o link de resgate mintado em `url`. Loja desconhecida exige cadastro no painel.

Em atualizações parciais, omitir descrição, URL, datas ou status preserva os valores anteriores. Texto vazio limpa descrição/URL/data. O cadastro continua exigindo código ou link de resgate. No MCP, `add_coupon` e `list_coupons` aceitam `site`/`site_id`; `convert_url:true` falha sem gravar quando não consegue gerar o link de afiliado.

## Lista de cupons por cursor

`GET /api/v1/coupons` também pagina por cursor: comece com `cursor=0` e repita com o `next_cursor` da resposta até ele vir `null`. Nesse modo a resposta não traz `total`, e os cupons saem na ordem da última atualização. Para manter uma cópia em dia, guarde a hora da última atualização que você viu e peça `updated_since` (segundos Unix) com `status=all`: vêm só os cupons que mudaram desde então, inclusive os apagados, com `deletedAt` preenchido. Sem `cursor` nem `updated_since`, `offset` e `total` continuam como antes.

## Imagens do promo-card

`POST /api/v1/promo-card` aceita imagens HTTPS dos CDNs de marketplaces compatíveis e da mídia própria do Bot. Para uma fonte externa, envie a imagem à mídia própria antes de usá-la. Composição: até 4 MiB por imagem; `raw:true`: até 8 MiB. SVG e endereços internos são recusados; redirects passam pela mesma validação.

## Interações do NerdCupons

A integração servidor-servidor usa `POST /api/v1/coupons/interactions/{issue,consume,stats}`, chave com escopo `write` ou `admin` e módulo de Cupons ativo. Emissão e consumo usam confirmação única por propósito e cupom/loja. A chave fica no servidor. A ativação exige a migração do backend antes do novo site; o histórico KV é preservado. Falha de gravação retorna erro, sem confirmar voto ou avaliação.

## Perguntas frequentes

### Qual módulo preciso ativar para usar a API REST do Bot do Afiliado?

Do módulo de API. Com ele ativo, você gera uma API key no painel e usa o header X-API-Key.

### Qual a base URL da API REST do Bot do Afiliado para converter links?

As rotas ficam em https://botdoafiliado.com/api/v1/. Cada endpoint está documentado nesta seção.

### Dá para chamar a API entre Cloudflare Workers sem sair para a internet pública?

Sim, via Service Binding (RPC). Veja a página RPC / Service Binding.