# API para Parceiros do Pechincha.ai

Catálogo de promoções e produtos do Pechincha.ai em JSON. Todos os endpoints são de leitura (GET).

Base URL: `https://api.pechincha.ai/api-partner`

Especificação OpenAPI: https://pechincha.ai/openapi.json

## Autenticação

Toda requisição precisa do header `x-api-key` com a sua chave de parceiro (peça em https://pechincha.ai/comercial). Requisições sem chave válida retornam `401`.

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

## Listar promoções

`GET /promotions`

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

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `page` | number | Página dos resultados, começando em 1. Cada página retorna 25 promoções. |
| `search` | string | Busca textual no título e na descrição. |
| `store_id` | uuid | Filtra por loja. |
| `category_id` | uuid | Filtra por categoria. |
| `category_ids` | uuid[] | Múltiplas categorias, separadas por vírgula. Tem precedência sobre category_id. |
| `product_id` | uuid | Filtra promoções de um produto específico. |
| `tag_id` | uuid | Filtra por tag. |
| `type` | string | COUPON retorna só promoções com código de cupom. |
| `sort` | string | Ordenação: created_at (padrão, mais recentes primeiro), price (menor primeiro), title, views, total_reactions, total_comments, total_shares. |
| `hide_expired` | boolean | Envie true para receber só promoções ativas. Padrão: false (as expiradas vêm junto, com is_expired: true). |
| `price_min` | number | Preço mínimo. |
| `price_max` | number | Preço máximo. |

Exemplo de resposta (resumida):

```json
{
  "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

- `GET /product/:productId`: detalhes do produto
- `GET /product/slug/:productSlug`: detalhes por slug
- `GET /product/:productId/promotions`: comparação de preços entre lojas
- `GET /product/:productId/price-history`: histórico de preços
- `GET /product/:productId/related`: produtos relacionados

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

```json
{
  "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.

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

## Servidor MCP para agentes de IA

Servidor MCP público, somente leitura e sem chave (Streamable HTTP): `https://pechincha.ai/mcp`. Passo a passo para Claude, ChatGPT, Grok e Gemini em https://pechincha.ai/ia.

No Claude Code, instale o plugin oficial (código aberto em https://github.com/pechincha-ai/pechincha-claude-plugin). No terminal:

```
claude plugin marketplace add pechincha-ai/pechincha-claude-plugin && claude plugin install pechincha@pechincha
```

No Gemini CLI, no Cursor, no VS Code e em clientes com o mesmo formato de configuração:

```
# Gemini CLI
gemini mcp add --transport http pechincha https://pechincha.ai/mcp

# Cursor / VS Code (mcp.json)
{
  "mcpServers": {
    "pechincha": { "url": "https://pechincha.ai/mcp" }
  }
}
```