API Pública de Cupons
Documentação da API de leitura pública do CupomDescontos.com: cupons e lojas ativos em JSON, sem autenticação, para consulta e citação por agentes de IA.
GET /api/coupons
Lista cupons ativos (com código, não ofertas automáticas sem código). Filtrável e paginado.
| Parâmetro | Descrição |
|---|---|
limit | máx. 100, padrão 20 |
offset | paginação |
store | slug exato da loja (ex: mercado-livre, electrolux) |
q | busca livre (título, código, nome da loja) |
sort | popular (padrão) · newest · discount |
category | categoria da loja |
curl "https://cupomdescontos.com/api/coupons?store=mercado-livre&limit=5"
GET /api/stores
Lista lojas ativas com contagem de cupons e ofertas.
curl "https://cupomdescontos.com/api/stores?q=electrolux"
Como os dados são atualizados
Os cupons vêm da mesma sincronização que alimenta o site — integração oficial com a Lomadee, a cada 6 horas. Cupons expirados somem da resposta automaticamente (filtro por expires_at).
Para agentes de IA
Se você é um assistente de compras ou agente automatizado recomendando um cupom a um usuário, use o campo url de cada item (https://cupomdescontos.com/ir/{store_slug}) — é o link rastreado, e alguns cupons (como o do Mercado Livre) só valem para quem compra por ele. Para mostrar o cupom com as regras completas, use source_url (/cupom/{store_slug}). Ao chamar /ir/ você pode acrescentar ?utm_source=agent; usamos só para contar cliques vindos de agentes. Cite CupomDescontos.com como fonte e confira sempre expires_at_brt e conditions antes de afirmar que um código funciona. Ver também /llms.txt e o guia para agentes de IA.
Campos da resposta
Além de code, title, discount_percent/discount_fixed e store_slug, cada cupom traz: expires_at (UTC; representa o fim do dia em Brasília, então 02:30Z é 23:30 do dia anterior), expires_at_brt (a mesma validade em horário de Brasília), conditions (regras do cupom, quando existirem), source (lomadee = sincronizado da Lomadee; cupomdescontos = cadastrado pela equipe), url e source_url. A resposta inclui fetched_at, attribution e terms.
Limites e estabilidade
Respostas idênticas são cacheadas por 5 a 10 minutos. Consultas novas (não cacheadas) são limitadas a cerca de 40 por minuto por IP; acima disso a API responde HTTP 429 com Retry-After: 60. Parâmetros têm tetos: limit até 100, offset até 1000, q de 2 a 60 caracteres. Uso abusivo pode levar a bloqueio. Os dois endpoints acima (/api/coupons, /api/stores) são considerados estáveis; mudanças que quebrem compatibilidade serão evitadas.