Para desenvolvedores e agentes

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 Ler o guia passo a passo

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

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

Cursor (~/.cursor/mcp.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:

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.

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.

https://web.mercader.app/.well-known/oauth-protected-resource
https://web.mercader.app/.well-known/oauth-authorization-server

Permissões (scopes)

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.

https://web.mercader.app/api/v1

API REST
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

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

Enviar imagens

Peça um upload com kind (product, event, avatar ou header) e content_type (image/jpeg, image/png ou image/webp).
Envie os bytes da imagem com PUT para upload_url. A URL expira em 2 horas.
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

Servidor MCP
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_productupdate_productdelete_productcreate_eventupdate_eventdelete_eventcreate_social_linkupdate_social_linkdelete_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:

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

Formato de erro
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