API pública e widget de cupons

Os cupons do Recomendo saem em JSON aberto, no mesmo build que gera o site. Se você mantém outro site, um app ou um bot, dá para exibir os cupons das lojas parceiras sem copiar nada à mão — e sem correr o risco de publicar código vencido, porque a lista que a API entrega é exatamente a que está no ar aqui.

Cupom acaba, parceria não

Se o seu bloco só souber ler cupom, ele fica vazio no dia em que a loja está sem código — e isso é o caso comum, não a exceção: das lojas com parceria aprovada aqui, a maioria não tem cupom ativo num dia qualquer. Por isso a API separa as duas coisas.

Cupom é código com prazo. Sai da lista quando vence.
Parceria é a loja aprovada, com link rastreado que vale sempre.

O endpoint /api/v1/ofertas.json devolve os dois na mesma lista, cupom primeiro, cada item marcado com tipo (cupom ou parceria). É o que você quer num bloco fixo. O widget já usa esse endpoint por padrão.

Os endpoints

Tudo é GET, sem chave, sem limite de requisição e com CORS aberto: dá para chamar direto do navegador.

/api/v1/index.json — descoberta: o que existe, quando foi gerado e os totais
/api/v1/ofertas.json — cupons e parcerias na mesma lista, nunca vazia
/api/v1/parceiros.json — o catálogo de parceria, com cupons e tem_cupom em cada loja
/api/v1/destaques.json — um cupom por loja, os de prazo mais curto primeiro
/api/v1/cupons.json — todos os cupons ativos
/api/v1/lojas.json e /api/v1/lojas/{slug}.json — o endpoint de loja responde mesmo para loja sem cupom hoje: vem cupons: [] e o bloco parceiro com o link
/api/v1/categorias.json e /api/v1/categorias/{slug}.json
/api/v1/produtos.json — as páginas de produto com a vitrine de cada loja já resolvida; aqui a loja entra mesmo sem cupom, com melhor_cupom: null e o deeplink da vitrine

Os arquivos são reescritos a cada sincronização, duas vezes por dia, e o cache no edge é de dez minutos.

O jeito mais rápido: o widget

Uma linha no HTML e o bloco de cupons aparece onde a tag estiver:

<script src="https://recomendo.org/api/v1/widget.js"
        data-loja="kabum"
        data-limite="4"
        data-fonte="meusite"></script>

Sem cupom na loja, o widget troca sozinho pelo card de parceria — o bloco não fica vazio. Para exigir cupom e aceitar bloco vazio, use data-so-cupons="sim".

Os atributos: data-loja ou data-categoria (sem nenhum dos dois, vêm as ofertas gerais), data-limite, data-titulo, data-tema (claro ou escuro), data-cor para o botão, data-alvo com um seletor CSS quando o bloco não deve nascer ao lado do script, e data-fonte, explicado abaixo.

O widget desenha dentro de um shadow root: o CSS do seu site não entra e o dele não vaza. Em React ou Vue, importe o script uma vez e chame Recomendo.montar({ alvo, loja, limite, fonte }).

Consumindo direto

const r = await fetch("https://recomendo.org/api/v1/lojas/kabum.json");
const { cupons } = await r.json();
cupons.forEach(c => console.log(c.codigo, c.titulo, c.validade));

Cada parceria traz nome, categoria, site, resumo, as cores do tile, o logo hospedado pela rede e o link rastreado — mais cupons e tem_cupom, que dizem se vale a pena pedir os códigos dela.

Cada cupom traz titulo, descricao, termos, codigo, desconto, inicio, fim, validade em texto pronto, os sinalizadores expirando, sem_prazo, sem_codigo e exclusivo, além do link de afiliado e dos dados da loja (nome, categoria, site e as cores do tile).

Atribuição: use o clickref

O link vem sem identificação de origem. Nos links da Awin — os que contêm awin1.com/cread.php — acrescente &clickref=suaorigem e a venda aparecerá separada por projeto no relatório da rede. É o mesmo parâmetro que este site usa para saber qual página paga as contas. O data-fonte do widget faz isso sozinho.

Link de outra rede ou de programa de indicação direto precisa passar intacto: acrescentar parâmetro a um encurtador que não o espera quebra a atribuição em vez de melhorá-la. O widget já trata essa distinção.

As regras de uso

Publique o cupom como ele vem. O desconto é derivado do texto do anunciante; inventar um valor que o campo não diz é exatamente o que este site existe para não fazer.
Não republique cupom depois do fim. Se você guarda a resposta em cache, respeite a data — ou releia a cada seis horas, no máximo.
Os links são pagos: marque-os com rel="sponsored nofollow" e deixe claro para o leitor que há comissão. O widget já faz as duas coisas.

Dúvida, campo faltando ou uso em volume maior: contato@recomendo.org.