Pechincha.ai para desenvolvedoresPromoções do Brasil no seu produto.

Autenticação

Todas as respostas são JSON e todos os endpoints são de leitura. A base é https://api.pechincha.ai/api-partner.

Toda requisição precisa do header x-api-key com a sua chave de parceiro. Para obter uma chave, fale com a gente pela página comercial. Requisições sem chave válida retornam 401.

curl -H "x-api-key: pk_sua_chave_aqui" \
  "https://api.pechincha.ai/api-partner/promotions?search=tv&hide_expired=true"

Listar promoções

Retorna as promoções, 25 por página. Use hide_expired=true para ficar só com as ativas. Parâmetros de query, todos opcionais:

pagenumber

Página dos resultados, começando em 1. Cada página retorna 25 promoções.

searchstring

Busca textual no título e na descrição.

store_iduuid

Filtra por loja.

category_iduuid

Filtra por categoria.

category_idsuuid[]

Múltiplas categorias, separadas por vírgula. Tem precedência sobre category_id.

product_iduuid

Filtra promoções de um produto específico.

tag_iduuid

Filtra por tag.

typestring

COUPON retorna só promoções com código de cupom.

sortstring

Ordenação: created_at (padrão, mais recentes primeiro), price (menor primeiro), title, views, total_reactions, total_comments, total_shares.

hide_expiredboolean

Envie true para receber só promoções ativas. Padrão: false (as expiradas vêm junto, com is_expired: true).

price_minnumber

Preço mínimo.

price_maxnumber

Preço máximo.

Exemplo de resposta (resumida):

{
  "count": 1834,
  "page": 1,
  "data": [
    {
      "id": "9b2f4c81-77aa-4a2b-9c1e-0f3d2a1b5c6d",
      "slug": "smart-tv-50-4k",
      "title": "Smart TV 50\" 4K",
      "description": "Menor preço dos últimos 90 dias...",
      "coupon_code": null,
      "discount": 12.5,
      "price": 1999.9,
      "old_price": 2285.6,
      "type": "PROMOTION",
      "url": "https://pechincha.link/p/a3f9c02b1e",
      "images": ["https://..."],
      "is_active": true,
      "is_verified": true,
      "is_expired": false,
      "created_at": "2026-08-29T14:00:00.000Z",
      "total_views": 240,
      "total_shares": 12,
      "total_reactions": 31,
      "reactions": { "fire": 18, "loved": 9, "...": 0 },
      "tags": [{ "id": "...", "slug": "tv", "name": "TV" }],
      "product": { "id": "...", "slug": "...", "name": "...", "images": ["..."] },
      "store": { "id": "...", "slug": "magalu", "name": "Magalu", "avatar": "...", "is_verified": true },
      "category": { "id": "...", "slug": "eletronicos", "name": "Eletrônicos" }
    }
  ]
}

Produtos

Exemplo de resposta de /product/:productId/promotions:

{
  "count": 4,
  "data": [
    {
      "id": "9b2f4c81-...",
      "slug": "smart-tv-50-4k",
      "title": "Smart TV 50\" 4K",
      "price": 1999.9,
      "old_price": 2285.6,
      "coupon_code": null,
      "url": "https://pechincha.link/p/a3f9c02b1e",
      "is_expired": false,
      "created_at": "2026-08-29T14:00:00.000Z",
      "store": { "id": "...", "name": "Magalu", "slug": "magalu", "avatar": "...", "is_verified": true }
    }
  ]
}

Links de promoção

O campo url de toda promoção é um link curto no formato pechincha.link/p/:codigo. Ao ser acessado, ele exibe uma pré-visualização da oferta (Open Graph para WhatsApp e redes sociais) e redireciona automaticamente para a loja.

Use sempre esse link: não tente extrair ou reconstruir o link da loja. Se você tiver conta de afiliado própria (hoje, no Mercado Livre), podemos configurar a sua chave para que o url dessas promoções já venha com o seu link de afiliado.

Para atribuição, adicione o parâmetro ref com o seu identificador de parceiro e, opcionalmente, parâmetros utm_*:

https://pechincha.link/p/a3f9c02b1e?ref=seu-id&utm_source=newsletter

Limites e erros

O limite é de 300 requisições por minuto por IP. Acima disso a API responde 429. Use as páginas e o cache do seu lado para reduzir chamadas.

• 400Parâmetros inválidos.
• 401API key ausente, inválida ou revogada.
• 404Recurso não encontrado.
• 429Limite de requisições excedido. Aguarde e tente novamente.