---
title: "API e MCP do Mercader para agentes de IA"
description: "Documentação da API REST e do servidor MCP do Mercader: OAuth 2.1, tokens pessoais, endpoints, ferramentas, upload de imagens, limites e erros."
url: https://www.mercader.app/pt/developers
language: pt
---

# API e MCP para editar sua vitrine

> Conecte o Claude, o ChatGPT, o Cursor ou o seu próprio script à sua vitrine do Mercader. Eles podem ler e editar seu perfil, seus produtos, seus eventos e seus links, e cada mudança é publicada na hora.

- Criar um token no painel: https://app.mercader.app/admin?tab=agents
- Ler o guia passo a passo: https://www.mercader.app/pt/blog/gerencie-sua-vitrine-com-ia.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## Comece em um minuto

Escolha seu cliente. Com OAuth você não copia nenhum token: seu assistente abre a tela de permissões do Mercader e você aprova o acesso.

### Claude.ai ou ChatGPT

Adicione um conector personalizado e cole esta URL:

```
https://web.mercader.app/api/mcp/me
```

### Claude Code

```bash
claude mcp add --transport http mercader https://web.mercader.app/api/mcp/me
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mercader": {
      "url": "https://web.mercader.app/api/mcp/me"
    }
  }
}
```

### curl ou o seu próprio código

Crie um token pessoal no painel e envie-o como Bearer:

```bash
curl https://web.mercader.app/api/v1/me \
  -H "Authorization: Bearer mk_live_…"
```

## Autenticação

Todas as requisições levam o cabeçalho Authorization: Bearer <token>. Um token só dá acesso à vitrine de quem o criou.

### OAuth 2.1 (recomendado para assistentes)

- Registro dinâmico de clientes (RFC 7591) e código de autorização com PKCE S256. Só clientes públicos, sem segredo.
- Descoberta: o 401 do MCP inclui WWW-Authenticate com a URL dos metadados do recurso protegido.
- O token de acesso dura 1 hora e o de atualização 30 dias. Cada atualização troca os dois.
- Revogação (RFC 7009) em /oauth/revoke, ou pelo painel a qualquer momento.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### Tokens pessoais

- Crie-os no painel, em Admin › Assistentes de IA. Começam com mk_live_ e só aparecem uma vez.
- Não expiram: revogue-os pelo painel quando não precisar mais deles.
- Úteis para scripts, curl e clientes que não aceitam OAuth.

### Permissões (scopes)

| Permissão | O que faz |
| --- | --- |
| `profile:write` | Nome, apresentação, cor, idioma, moeda, logo, capa e links. |
| `catalog:write` | Produtos, eventos e feiras, e suas imagens. |

## API REST

JSON sobre HTTPS. Os campos que você não envia não mudam; uma string vazia apaga um campo opcional.

Base URL: `https://web.mercader.app/api/v1`

| Método | Rota | Permissão | O que faz |
| --- | --- | --- | --- |
| GET | `/me` | qualquer | Perfil, plano e limites, produtos, eventos e links, com seus ids. |
| PATCH | `/profile` | `profile:write` | Muda nome, apresentação, cor, idioma, país, moeda, logo ou capa. |
| GET | `/products` | qualquer | Lista os produtos. |
| POST | `/products` | `catalog:write` | Cria um produto (name e price obrigatórios). |
| PATCH | `/products/{id}` | `catalog:write` | Muda preço, foto, disponibilidade ou outros campos. |
| DELETE | `/products/{id}` | `catalog:write` | Apaga um produto. |
| GET | `/events` | qualquer | Lista os eventos e feiras. |
| POST | `/events` | `catalog:write` | Cria um evento (title e start_date em ISO 8601). |
| PATCH | `/events/{id}` | `catalog:write` | Muda um evento. |
| DELETE | `/events/{id}` | `catalog:write` | Apaga um evento. |
| GET | `/social-links` | qualquer | Lista os links sociais e de contato. |
| POST | `/social-links` | `profile:write` | Adiciona um link (Instagram, WhatsApp, Website, Email…). |
| PATCH | `/social-links/{id}` | `profile:write` | Muda um link. |
| DELETE | `/social-links/{id}` | `profile:write` | Apaga um link. |
| POST | `/uploads` | conforme o tipo | Devolve uma URL assinada para enviar uma imagem. |

### Exemplo: criar um produto

```bash
curl -X POST https://web.mercader.app/api/v1/products \
  -H "Authorization: Bearer mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Taza de gres", "price": 22, "description": "300 ml"}'
```

[Esquemas completos na especificação OpenAPI 3.1](https://web.mercader.app/api/v1/openapi.json)

## Enviar imagens

1. Peça um upload com kind (product, event, avatar ou header) e content_type (image/jpeg, image/png ou image/webp).
2. Envie os bytes da imagem com PUT para upload_url. A URL expira em 2 horas.
3. Use public_url como image_url do produto ou do evento, ou como avatar_url ou header_url do perfil.

## Servidor MCP

Streamable HTTP, sem estado. Mesmas operações, validação e limites da API REST.

```
https://web.mercader.app/api/mcp/me
```

| Ferramenta | O que faz |
| --- | --- |
| `get_my_storefront` | Estado atual da vitrine: perfil, URL pública, plano, limites e todos os itens com seus ids. |
| `update_profile` | Muda só os campos do perfil que recebe. O endereço (slug) não pode ser alterado. |
| `create_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_social_link` | Cria, muda ou apaga produtos, eventos e links. As ferramentas de exclusão são marcadas como destrutivas. |
| `create_image_upload` | Prepara o envio de uma imagem e devolve upload_url e public_url. |

### MCP público somente leitura

Para buscar em todas as vitrines publicadas, sem autenticação:

```
https://web.mercader.app/api/mcp
```

## Limites e erros

- 120 requisições por minuto por token. Acima disso, 429 com Retry-After.
- Os limites do seu plano valem como no painel: ao chegar ao máximo, 403 plan_limit.
- As respostas levam Cache-Control: no-store.

### Formato de erro

Todos os erros devolvem um JSON com um código estável e uma descrição legível:

```json
{
  "error": "plan_limit",
  "error_description": "…"
}
```

| Código | HTTP | Significado |
| --- | --- | --- |
| `invalid_input` | 400 | Falta um campo, sobra um ou o formato não é válido. |
| `invalid_token` | 401 | Token ausente, desconhecido, revogado ou expirado. |
| `insufficient_scope` | 403 | O token não tem a permissão que a operação pede. |
| `plan_limit` | 403 | O limite do plano foi atingido ou o teste terminou. |
| `not_found` | 404 | O item não existe na sua vitrine. |
| `no_profile` | 409 | A conta ainda não terminou o onboarding. |
| `rate_limited` | 429 | Requisições demais no último minuto. |

## Segurança e privacidade

- Guardamos só um hash de cada token. Se você perder um, crie outro.
- Um token não pode ler seus contatos, suas avaliações nem sua cobrança, nem mudar o endereço da sua vitrine.
- As mudanças são publicadas na hora para seus clientes: peça ao seu assistente que confirme antes de apagar.

## Ainda não tem vitrine?

Crie a sua e conecte seu assistente depois. O Mercader tem 14 dias de teste.

[Criar minha vitrine](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)