---
title: "API y MCP de Mercader para agentes de IA"
description: "Documentación de la API REST y del servidor MCP de Mercader: OAuth 2.1, tokens personales, endpoints, herramientas, subida de imágenes, límites y errores."
url: https://www.mercader.app/es/developers
language: es
---

# API y MCP para editar tu escaparate

> Conecta Claude, ChatGPT, Cursor o tu propio script a tu escaparate de Mercader. Pueden leer y editar tu perfil, tus productos, tus eventos y tus enlaces, y cada cambio se publica al momento.

- Crear un token en el panel: https://app.mercader.app/admin?tab=agents
- Leer la guía paso a paso: https://www.mercader.app/es/blog/gestiona-tu-escaparate-con-ia.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## Empieza en un minuto

Elige tu cliente. Con OAuth no copias ningún token: tu asistente abre la pantalla de permisos de Mercader y tú apruebas el acceso.

### Claude.ai o ChatGPT

Añade un conector personalizado y pega 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 o tu propio código

Crea un token personal en el panel y envíalo como Bearer:

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

## Autenticación

Todas las peticiones llevan la cabecera Authorization: Bearer <token>. Un token solo da acceso al escaparate de la persona que lo creó.

### OAuth 2.1 (recomendado para asistentes)

- Registro dinámico de clientes (RFC 7591) y código de autorización con PKCE S256. Solo clientes públicos, sin secreto.
- Descubrimiento: el 401 del MCP incluye WWW-Authenticate con la URL de los metadatos del recurso protegido.
- El token de acceso dura 1 hora y el de refresco 30 días. Cada refresco rota los dos.
- Revocación (RFC 7009) en /oauth/revoke, o desde el panel en cualquier momento.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### Tokens personales

- Créalos en el panel, en Admin › Asistentes de IA. Empiezan por mk_live_ y solo se muestran una vez.
- No caducan: revócalos desde el panel cuando ya no los uses.
- Útiles para scripts, curl y clientes que no admiten OAuth.

### Permisos (scopes)

| Permiso | Qué hace |
| --- | --- |
| `profile:write` | Nombre, presentación, color, idioma, moneda, logo, portada y enlaces. |
| `catalog:write` | Productos, eventos y ferias, y sus imágenes. |

## API REST

JSON sobre HTTPS. Los campos que no envías no cambian; una cadena vacía borra un campo opcional.

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

| Método | Ruta | Permiso | Qué hace |
| --- | --- | --- | --- |
| GET | `/me` | cualquiera | Perfil, plan y límites, productos, eventos y enlaces, con sus id. |
| PATCH | `/profile` | `profile:write` | Cambia nombre, presentación, color, idioma, país, moneda, logo o portada. |
| GET | `/products` | cualquiera | Lista los productos. |
| POST | `/products` | `catalog:write` | Crea un producto (name y price obligatorios). |
| PATCH | `/products/{id}` | `catalog:write` | Cambia precio, foto, disponibilidad u otros campos. |
| DELETE | `/products/{id}` | `catalog:write` | Borra un producto. |
| GET | `/events` | cualquiera | Lista los eventos y ferias. |
| POST | `/events` | `catalog:write` | Crea un evento (title y start_date en ISO 8601). |
| PATCH | `/events/{id}` | `catalog:write` | Cambia un evento. |
| DELETE | `/events/{id}` | `catalog:write` | Borra un evento. |
| GET | `/social-links` | cualquiera | Lista los enlaces sociales y de contacto. |
| POST | `/social-links` | `profile:write` | Añade un enlace (Instagram, WhatsApp, Website, Email…). |
| PATCH | `/social-links/{id}` | `profile:write` | Cambia un enlace. |
| DELETE | `/social-links/{id}` | `profile:write` | Borra un enlace. |
| POST | `/uploads` | según el tipo | Devuelve una URL firmada para subir una imagen. |

### Ejemplo: crear un producto

```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 en la especificación OpenAPI 3.1](https://web.mercader.app/api/v1/openapi.json)

## Subir imágenes

1. Pide una subida con kind (product, event, avatar o header) y content_type (image/jpeg, image/png o image/webp).
2. Envía los bytes de la imagen con PUT a upload_url. La URL caduca en 2 horas.
3. Usa public_url como image_url del producto o del evento, o como avatar_url o header_url del perfil.

## Servidor MCP

Streamable HTTP, sin estado. Mismas operaciones, validación y límites que la API REST.

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

| Herramienta | Qué hace |
| --- | --- |
| `get_my_storefront` | Estado actual del escaparate: perfil, URL pública, plan, límites y todos los elementos con sus id. |
| `update_profile` | Cambia solo los campos del perfil que recibe. La dirección (slug) no se puede cambiar. |
| `create_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_social_link` | Crea, cambia o borra productos, eventos y enlaces. Las herramientas de borrado están marcadas como destructivas. |
| `create_image_upload` | Prepara la subida de una imagen y devuelve upload_url y public_url. |

### MCP público de solo lectura

Para buscar en todos los escaparates publicados, sin autenticación:

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

## Límites y errores

- 120 peticiones por minuto y token. Al superarlo, 429 con Retry-After.
- Los límites de tu plan se aplican igual que en el panel: al llegar al máximo, 403 plan_limit.
- Las respuestas llevan Cache-Control: no-store.

### Formato de error

Todos los errores devuelven un JSON con un código estable y una descripción legible:

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

| Código | HTTP | Significado |
| --- | --- | --- |
| `invalid_input` | 400 | Falta un campo, sobra uno o tiene un formato no válido. |
| `invalid_token` | 401 | Token ausente, desconocido, revocado o caducado. |
| `insufficient_scope` | 403 | El token no tiene el permiso que pide la operación. |
| `plan_limit` | 403 | Se ha alcanzado el límite del plan o la prueba ha terminado. |
| `not_found` | 404 | El elemento no existe en tu escaparate. |
| `no_profile` | 409 | La cuenta aún no ha terminado el onboarding. |
| `rate_limited` | 429 | Demasiadas peticiones en el último minuto. |

## Seguridad y privacidad

- Guardamos solo un hash de cada token. Si lo pierdes, crea otro.
- Un token no puede leer tus contactos, tus reseñas ni tu facturación, ni cambiar la dirección de tu escaparate.
- Los cambios se publican al momento para tus clientes: pide a tu asistente que confirme antes de borrar.

## ¿Todavía no tienes escaparate?

Crea el tuyo y conecta tu asistente después. Mercader tiene 14 días de prueba.

[Crear mi escaparate](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)