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.
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 » — 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.
X-API-Key: bk_xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxEndpoints
Todos os endpoints abaixo estão detalhados (schemas, exemplos e try it out) na referência interativa.
Conversão — ver na referência »
| Endpoint | Método | O que faz |
|---|---|---|
/api/v1/convert-links |
POST | Converte 1 ou vários links (até 150). Guia: convert-links. |
/api/v1/convert |
POST | Conversão unitária (legado). Guia: convert (legado). |
Produtos — ver na referência »
| 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. |
/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 »
| 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 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 »
| 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.
- Referência interativa em Scalar.
Próximos passos
- Ative o módulo de API.
- Gere uma API key.
- Faça sua primeira chamada em 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.
{
"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.