# Referência interativa da API (Scalar)

> A referência interativa da API do Bot do Afiliado fica em /docs/api/referencia/ (Scalar) e lê o contrato público /api/openapi.json, que não pede login; o /swagger antigo exige sessão do painel e responde 401 para o público.

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

A referência interativa da API do Bot do Afiliado fica em **[/docs/api/referencia/](/docs/api/referencia/)**, no **Scalar**, e lê o contrato público **`https://botdoafiliado.com/api/openapi.json`**. O contrato não pede login; testar um endpoint pede a sua **[API key](/docs/api/autenticacao/)**.

## Referência interativa da API

👉 **[Abrir a referência da API (Scalar) »](/docs/api/referencia/)**

A referência Scalar tem **busca** (atalho `Ctrl+K`), schemas de request/response, exemplos de código (cURL por padrão; troque para JavaScript, Python, PHP e outros no seletor) e **try it out** direto no navegador. A página monta o conteúdo no navegador: sem JavaScript, use o JSON abaixo.

### Atalhos por seção

| Seção | O que tem | Link direto |
|---|---|---|
| Conversão | `convert-links`, `convert` (legado) | [abrir »](/docs/api/referencia/#tag/conversao) |
| Produtos | `product`, `product/history`, `product/shipping`, `search-products`, `amazon-prices` | [abrir »](/docs/api/referencia/#tag/produtos) |
| Ofertas | `execute` (post pronto), `chat`, `templates` | [abrir »](/docs/api/referencia/#tag/ofertas) |
| Cupons | listar, cadastrar, desativar/reativar, categorias, ingestão | [abrir »](/docs/api/referencia/#tag/cupons) |

## O contrato OpenAPI

| O quê | Valor |
|---|---|
| Endereço | `https://botdoafiliado.com/api/openapi.json` |
| Login | nenhum |
| CORS | `access-control-allow-origin: *`, métodos `GET` e `OPTIONS` |
| Cache | `public, max-age=300` (5 minutos) |
| Autenticação declarada | `ApiKeyAuth`, header `X-API-Key` |

> 💡 Importe o contrato no **Postman/Insomnia** ou use-o para **gerar clientes** na sua linguagem (openapi-generator e afins).

## E o /swagger?

O `/swagger` e o `/swagger-data` são a documentação **interna** da API: só abrem com sessão do painel (ou a senha do ambiente) e respondem **401** para o público. Robôs e agentes de IA não devem usá-los: o `robots.txt` os fecha e o `llms.txt` aponta para a referência pública.

## Como usar

1. Abra a **[referência Scalar](/docs/api/referencia/)** para ver os schemas de request/response.
2. Autentique com a sua **[API key](/docs/api/autenticacao/)** (`X-API-Key`): na referência, use o campo **Auth** no topo para preenchê-la uma vez e testar qualquer endpoint.
3. Teste os endpoints **[convert-links](/docs/api/convert-links/)** e **[product](/docs/api/product/)**.

## Perguntas frequentes

### Onde fica a referência interativa (Scalar) da API REST do Bot do Afiliado?

Em /docs/api/referencia/ — a referência Scalar, com busca, schemas e try-it-out.

### Onde encontro o arquivo OpenAPI em JSON da API do Bot do Afiliado?

Em https://botdoafiliado.com/api/openapi.json. É público, sem login, e aceita chamada de qualquer origem (CORS aberto).

### Por que /swagger responde 401?

O /swagger e o /swagger-data são a documentação interna e pedem sessão do painel. A referência pública é /docs/api/referencia/, lendo o /api/openapi.json.

### Posso gerar um cliente da API a partir do OpenAPI?

Sim. Importe /api/openapi.json no Postman ou no Insomnia, ou use openapi-generator e afins. A autenticação declarada é o header X-API-Key.