Für Entwickler und Agenten

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 Schritt-für-Schritt-Anleitung lesen

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

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

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

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.

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.

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

Berechtigungen (Scopes)

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.

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

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

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

Bilder hochladen

Fordere einen Upload mit kind (product, event, avatar oder header) und content_type (image/jpeg, image/png oder image/webp) an.
Sende die Bildbytes per PUT an upload_url. Die URL läuft nach 2 Stunden ab.
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

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

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

Fehlerformat
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