---
title: "Mercader-API und MCP für KI-Agenten"
description: "Dokumentation der REST-API und des MCP-Servers von Mercader: OAuth 2.1, persönliche Tokens, Endpunkte, Tools, Bild-Uploads, Limits und Fehler."
url: https://www.mercader.app/de/developers
language: de
---

# API und MCP für dein Schaufenster

> Verbinde Claude, ChatGPT, Cursor oder dein eigenes Skript mit deinem Mercader-Schaufenster. Sie können dein Profil, deine Produkte, Events und Links lesen und bearbeiten, und jede Änderung ist sofort online.

- Token im Dashboard erstellen: https://app.mercader.app/admin?tab=agents
- Schritt-für-Schritt-Anleitung lesen: https://www.mercader.app/de/blog/schaufenster-mit-ki-verwalten.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## In einer Minute startklar

Wähle deinen Client. Mit OAuth kopierst du kein Token: Dein Assistent öffnet die Berechtigungsseite von Mercader und du gibst den Zugriff frei.

### Claude.ai oder ChatGPT

Füge einen benutzerdefinierten Connector hinzu und füge diese URL ein:

```
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 oder eigener Code

Erstelle im Dashboard ein persönliches Token und sende es als Bearer:

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

## Authentifizierung

Jede Anfrage enthält den Header Authorization: Bearer <Token>. Ein Token gibt nur Zugriff auf das Schaufenster der Person, die es erstellt hat.

### OAuth 2.1 (empfohlen für Assistenten)

- Dynamische Client-Registrierung (RFC 7591) und Authorization Code mit PKCE S256. Nur öffentliche Clients, ohne Secret.
- Discovery: Die 401-Antwort des MCP enthält WWW-Authenticate mit der URL der Protected-Resource-Metadaten.
- Access-Tokens gelten 1 Stunde, Refresh-Tokens 30 Tage. Jeder Refresh erneuert beide.
- Widerruf (RFC 7009) über /oauth/revoke oder jederzeit im Dashboard.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### Persönliche Tokens

- Erstelle sie im Dashboard unter Admin › KI-Assistenten. Sie beginnen mit mk_live_ und werden nur einmal angezeigt.
- Sie laufen nicht ab: Widerrufe sie im Dashboard, wenn du sie nicht mehr brauchst.
- Praktisch für Skripte, curl und Clients ohne OAuth.

### Berechtigungen (Scopes)

| Berechtigung | Funktion |
| --- | --- |
| `profile:write` | Name, Beschreibung, Farbe, Sprache, Währung, Logo, Titelbild und Links. |
| `catalog:write` | Produkte, Events und Märkte sowie ihre Bilder. |

## REST-API

JSON über HTTPS. Felder, die du nicht sendest, bleiben unverändert; ein leerer String löscht ein optionales Feld.

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

| Methode | Pfad | Berechtigung | Funktion |
| --- | --- | --- | --- |
| GET | `/me` | beliebig | Profil, Tarif und Limits, Produkte, Events und Links mit ihren IDs. |
| PATCH | `/profile` | `profile:write` | Ändert Name, Beschreibung, Farbe, Sprache, Land, Währung, Logo oder Titelbild. |
| GET | `/products` | beliebig | Listet die Produkte. |
| POST | `/products` | `catalog:write` | Legt ein Produkt an (name und price sind Pflicht). |
| PATCH | `/products/{id}` | `catalog:write` | Ändert Preis, Foto, Verfügbarkeit oder andere Felder. |
| DELETE | `/products/{id}` | `catalog:write` | Löscht ein Produkt. |
| GET | `/events` | beliebig | Listet Events und Märkte. |
| POST | `/events` | `catalog:write` | Legt ein Event an (title und start_date in ISO 8601). |
| PATCH | `/events/{id}` | `catalog:write` | Ändert ein Event. |
| DELETE | `/events/{id}` | `catalog:write` | Löscht ein Event. |
| GET | `/social-links` | beliebig | Listet Social- und Kontaktlinks. |
| POST | `/social-links` | `profile:write` | Fügt einen Link hinzu (Instagram, WhatsApp, Website, Email…). |
| PATCH | `/social-links/{id}` | `profile:write` | Ändert einen Link. |
| DELETE | `/social-links/{id}` | `profile:write` | Löscht einen Link. |
| POST | `/uploads` | je nach Typ | Liefert eine signierte URL zum Hochladen eines Bildes. |

### Beispiel: Produkt anlegen

```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"}'
```

[Vollständige Schemas in der OpenAPI-3.1-Spezifikation](https://web.mercader.app/api/v1/openapi.json)

## Bilder hochladen

1. Fordere einen Upload mit kind (product, event, avatar oder header) und content_type (image/jpeg, image/png oder image/webp) an.
2. Sende die Bildbytes per PUT an upload_url. Die URL läuft nach 2 Stunden ab.
3. Verwende public_url als image_url eines Produkts oder Events oder als avatar_url bzw. header_url des Profils.

## MCP-Server

Streamable HTTP, zustandslos. Dieselben Operationen, Validierungen und Limits wie die REST-API.

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

| Tool | Funktion |
| --- | --- |
| `get_my_storefront` | Aktueller Stand des Schaufensters: Profil, öffentliche URL, Tarif, Limits und alle Einträge mit IDs. |
| `update_profile` | Ändert nur die übergebenen Profilfelder. Die Adresse (Slug) lässt sich nicht ändern. |
| `create_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_social_link` | Legt Produkte, Events und Links an, ändert oder löscht sie. Lösch-Tools sind als destruktiv markiert. |
| `create_image_upload` | Bereitet einen Bild-Upload vor und liefert upload_url und public_url. |

### Öffentlicher MCP (nur Lesen)

Zum Durchsuchen aller veröffentlichten Schaufenster, ohne Authentifizierung:

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

## Limits und Fehler

- 120 Anfragen pro Minute und Token. Darüber hinaus 429 mit Retry-After.
- Die Limits deines Tarifs gelten wie im Dashboard: Beim Maximum kommt 403 plan_limit.
- Antworten enthalten Cache-Control: no-store.

### Fehlerformat

Jeder Fehler liefert JSON mit einem stabilen Code und einer lesbaren Beschreibung:

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

| Code | HTTP | Bedeutung |
| --- | --- | --- |
| `invalid_input` | 400 | Ein Feld fehlt, ist unbekannt oder falsch formatiert. |
| `invalid_token` | 401 | Token fehlt, ist unbekannt, widerrufen oder abgelaufen. |
| `insufficient_scope` | 403 | Dem Token fehlt die nötige Berechtigung. |
| `plan_limit` | 403 | Das Tariflimit ist erreicht oder der Testzeitraum ist vorbei. |
| `not_found` | 404 | Der Eintrag existiert nicht in deinem Schaufenster. |
| `no_profile` | 409 | Das Konto hat das Onboarding noch nicht abgeschlossen. |
| `rate_limited` | 429 | Zu viele Anfragen in der letzten Minute. |

## Sicherheit und Datenschutz

- Wir speichern nur einen Hash jedes Tokens. Wenn du eines verlierst, erstelle ein neues.
- Ein Token kann weder deine Kontakte, Bewertungen oder Abrechnung lesen noch die Adresse deines Schaufensters ändern.
- Änderungen sind sofort für deine Kundschaft sichtbar: Lass deinen Assistenten vor dem Löschen nachfragen.

## Noch kein Schaufenster?

Erstelle deins und verbinde danach deinen Assistenten. Mercader bietet 14 Tage zum Testen.

[Mein Schaufenster erstellen](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)