Voor ontwikkelaars en agents

API en MCP om je etalage te bewerken

Koppel Claude, ChatGPT, Cursor of je eigen script aan je Mercader-etalage. Ze kunnen je profiel, producten, evenementen en links lezen en bewerken, en elke wijziging staat meteen online.

Token aanmaken in het dashboard Lees de stapsgewijze handleiding

Binnen een minuut aan de slag

Kies je client. Met OAuth kopieer je geen token: je assistent opent het toestemmingsscherm van Mercader en jij keurt de toegang goed.

Claude.ai of ChatGPT

Voeg een aangepaste connector toe en plak deze 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 of je eigen code

Maak een persoonlijk token aan in het dashboard en stuur het mee als Bearer:

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

Authenticatie

Elk verzoek bevat de header Authorization: Bearer <token>. Een token geeft alleen toegang tot de etalage van wie het heeft aangemaakt.

OAuth 2.1 (aanbevolen voor assistenten)

Dynamische clientregistratie (RFC 7591) en authorization code met PKCE S256. Alleen publieke clients, zonder secret.
Discovery: het 401-antwoord van de MCP bevat WWW-Authenticate met de URL van de metadata van de beschermde resource.
Access tokens zijn 1 uur geldig en refresh tokens 30 dagen. Elke refresh vernieuwt ze allebei.
Intrekken (RFC 7009) via /oauth/revoke, of op elk moment in het dashboard.

Persoonlijke tokens

Maak ze aan in het dashboard onder Admin › AI-assistenten. Ze beginnen met mk_live_ en worden maar één keer getoond.
Ze verlopen niet: trek ze in via het dashboard als je ze niet meer gebruikt.
Handig voor scripts, curl en clients zonder OAuth.

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

Rechten (scopes)

Rechten (scopes)
Recht	Wat het doet
`profile:write`	Naam, introductie, kleur, taal, valuta, logo, omslagfoto en links.
`catalog:write`	Producten, evenementen en markten, en hun afbeeldingen.

REST-API

JSON via HTTPS. Velden die je niet meestuurt blijven ongewijzigd; een lege string wist een optioneel veld.

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

REST-API
Methode	Pad	Recht	Wat het doet
GET	`/me`	elk	Profiel, abonnement en limieten, producten, evenementen en links, met hun id's.
PATCH	`/profile`	`profile:write`	Wijzigt naam, introductie, kleur, taal, land, valuta, logo of omslagfoto.
GET	`/products`	elk	Toont de producten.
POST	`/products`	`catalog:write`	Maakt een product aan (name en price verplicht).
PATCH	`/products/{id}`	`catalog:write`	Wijzigt prijs, foto, beschikbaarheid of andere velden.
DELETE	`/products/{id}`	`catalog:write`	Verwijdert een product.
GET	`/events`	elk	Toont evenementen en markten.
POST	`/events`	`catalog:write`	Maakt een evenement aan (title en start_date in ISO 8601).
PATCH	`/events/{id}`	`catalog:write`	Wijzigt een evenement.
DELETE	`/events/{id}`	`catalog:write`	Verwijdert een evenement.
GET	`/social-links`	elk	Toont social- en contactlinks.
POST	`/social-links`	`profile:write`	Voegt een link toe (Instagram, WhatsApp, Website, Email…).
PATCH	`/social-links/{id}`	`profile:write`	Wijzigt een link.
DELETE	`/social-links/{id}`	`profile:write`	Verwijdert een link.
POST	`/uploads`	afhankelijk van type	Geeft een ondertekende URL om een afbeelding te uploaden.

Voorbeeld: een product aanmaken

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

Volledige schema's in de OpenAPI 3.1-specificatie

Afbeeldingen uploaden

Vraag een upload aan met kind (product, event, avatar of header) en content_type (image/jpeg, image/png of image/webp).
Stuur de bytes van de afbeelding met PUT naar upload_url. De URL verloopt na 2 uur.
Gebruik public_url als image_url van een product of evenement, of als avatar_url of header_url van het profiel.

MCP-server

Streamable HTTP, stateless. Dezelfde bewerkingen, validatie en limieten als de REST-API.

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

MCP-server
Tool	Wat het doet
`get_my_storefront`	Huidige stand van de etalage: profiel, publieke URL, abonnement, limieten en alle items met hun id's.
`update_profile`	Wijzigt alleen de profielvelden die het ontvangt. Het adres (slug) kan niet worden gewijzigd.
`create_productupdate_productdelete_productcreate_eventupdate_eventdelete_eventcreate_social_linkupdate_social_linkdelete_social_link`	Maakt producten, evenementen en links aan, wijzigt of verwijdert ze. Verwijdertools zijn gemarkeerd als destructief.
`create_image_upload`	Bereidt een upload van een afbeelding voor en geeft upload_url en public_url terug.

Publieke MCP (alleen lezen)

Om alle gepubliceerde etalages te doorzoeken, zonder authenticatie:

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

Limieten en fouten

120 verzoeken per minuut per token. Daarboven 429 met Retry-After.
De limieten van je abonnement gelden net als in het dashboard: op het maximum krijg je 403 plan_limit.
Antwoorden bevatten Cache-Control: no-store.

Foutformaat

Elke fout geeft JSON terug met een vaste code en een leesbare beschrijving:

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

Foutformaat
Code	HTTP	Betekenis
`invalid_input`	400	Een veld ontbreekt, is onbekend of heeft een ongeldig formaat.
`invalid_token`	401	Token ontbreekt, is onbekend, ingetrokken of verlopen.
`insufficient_scope`	403	Het token heeft niet het recht dat de bewerking vraagt.
`plan_limit`	403	De limiet van het abonnement is bereikt of de proefperiode is voorbij.
`not_found`	404	Het item bestaat niet in je etalage.
`no_profile`	409	Het account heeft de onboarding nog niet afgerond.
`rate_limited`	429	Te veel verzoeken in de afgelopen minuut.

Veiligheid en privacy

We bewaren alleen een hash van elk token. Kwijt? Maak een nieuw aan.
Een token kan je contacten, reviews en facturatie niet lezen en het adres van je etalage niet wijzigen.
Wijzigingen staan meteen online voor je klanten: laat je assistent bevestigen voordat er iets wordt verwijderd.

Nog geen etalage?

Maak de jouwe aan en koppel daarna je assistent. Mercader heeft een proefperiode van 14 dagen.

Mijn etalage maken