---
title: "Mercader-API en MCP voor AI-agents"
description: "Documentatie van de REST-API en MCP-server van Mercader: OAuth 2.1, persoonlijke tokens, endpoints, tools, afbeeldingen uploaden, limieten en fouten."
url: https://www.mercader.app/nl/developers
language: nl
---

# 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: https://app.mercader.app/admin?tab=agents
- Lees de stapsgewijze handleiding: https://www.mercader.app/nl/blog/beheer-je-etalage-met-ai.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## 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

```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 of je eigen code

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

```bash
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.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### 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.

### 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.

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

| 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

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

[Volledige schema's in de OpenAPI 3.1-specificatie](https://web.mercader.app/api/v1/openapi.json)

## Afbeeldingen uploaden

1. Vraag een upload aan met kind (product, event, avatar of header) en content_type (image/jpeg, image/png of image/webp).
2. Stuur de bytes van de afbeelding met PUT naar upload_url. De URL verloopt na 2 uur.
3. 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
```

| 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_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_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:

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

| 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](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)