---
title: "API et MCP de Mercader pour les agents IA"
description: "Documentation de l'API REST et du serveur MCP de Mercader : OAuth 2.1, jetons personnels, endpoints, outils, envoi d'images, limites et erreurs."
url: https://www.mercader.app/fr/developers
language: fr
---

# API et MCP pour modifier votre vitrine

> Connectez Claude, ChatGPT, Cursor ou votre propre script à votre vitrine Mercader. Ils peuvent lire et modifier votre profil, vos produits, vos événements et vos liens, et chaque modification est publiée immédiatement.

- Créer un jeton dans le tableau de bord: https://app.mercader.app/admin?tab=agents
- Lire le guide pas à pas: https://www.mercader.app/fr/blog/gerer-votre-vitrine-avec-l-ia.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## Démarrez en une minute

Choisissez votre client. Avec OAuth, vous ne copiez aucun jeton : votre assistant ouvre l'écran d'autorisation de Mercader et vous approuvez l'accès.

### Claude.ai ou ChatGPT

Ajoutez un connecteur personnalisé et collez cette 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 ou votre propre code

Créez un jeton personnel dans le tableau de bord et envoyez-le comme Bearer :

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

## Authentification

Chaque requête porte l'en-tête Authorization: Bearer <jeton>. Un jeton ne donne accès qu'à la vitrine de la personne qui l'a créé.

### OAuth 2.1 (recommandé pour les assistants)

- Enregistrement dynamique des clients (RFC 7591) et code d'autorisation avec PKCE S256. Clients publics uniquement, sans secret.
- Découverte : la réponse 401 du MCP inclut WWW-Authenticate avec l'URL des métadonnées de la ressource protégée.
- Le jeton d'accès dure 1 heure et le jeton de rafraîchissement 30 jours. Chaque rafraîchissement renouvelle les deux.
- Révocation (RFC 7009) sur /oauth/revoke, ou depuis le tableau de bord à tout moment.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### Jetons personnels

- Créez-les dans le tableau de bord, sous Admin › Assistants IA. Ils commencent par mk_live_ et ne s'affichent qu'une fois.
- Ils n'expirent pas : révoquez-les depuis le tableau de bord quand vous ne les utilisez plus.
- Pratiques pour les scripts, curl et les clients sans OAuth.

### Autorisations (scopes)

| Autorisation | Ce qu'il fait |
| --- | --- |
| `profile:write` | Nom, présentation, couleur, langue, devise, logo, couverture et liens. |
| `catalog:write` | Produits, événements et marchés, et leurs images. |

## API REST

JSON sur HTTPS. Les champs que vous n'envoyez pas ne changent pas ; une chaîne vide efface un champ facultatif.

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

| Méthode | Chemin | Autorisation | Ce qu'il fait |
| --- | --- | --- | --- |
| GET | `/me` | tous | Profil, formule et limites, produits, événements et liens, avec leurs id. |
| PATCH | `/profile` | `profile:write` | Modifie le nom, la présentation, la couleur, la langue, le pays, la devise, le logo ou la couverture. |
| GET | `/products` | tous | Liste les produits. |
| POST | `/products` | `catalog:write` | Crée un produit (name et price obligatoires). |
| PATCH | `/products/{id}` | `catalog:write` | Modifie le prix, la photo, la disponibilité ou d'autres champs. |
| DELETE | `/products/{id}` | `catalog:write` | Supprime un produit. |
| GET | `/events` | tous | Liste les événements et les marchés. |
| POST | `/events` | `catalog:write` | Crée un événement (title et start_date en ISO 8601). |
| PATCH | `/events/{id}` | `catalog:write` | Modifie un événement. |
| DELETE | `/events/{id}` | `catalog:write` | Supprime un événement. |
| GET | `/social-links` | tous | Liste les liens sociaux et de contact. |
| POST | `/social-links` | `profile:write` | Ajoute un lien (Instagram, WhatsApp, Website, Email…). |
| PATCH | `/social-links/{id}` | `profile:write` | Modifie un lien. |
| DELETE | `/social-links/{id}` | `profile:write` | Supprime un lien. |
| POST | `/uploads` | selon le type | Renvoie une URL signée pour envoyer une image. |

### Exemple : créer un produit

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

[Schémas complets dans la spécification OpenAPI 3.1](https://web.mercader.app/api/v1/openapi.json)

## Envoyer des images

1. Demandez un envoi avec kind (product, event, avatar ou header) et content_type (image/jpeg, image/png ou image/webp).
2. Envoyez les octets de l'image en PUT vers upload_url. L'URL expire au bout de 2 heures.
3. Utilisez public_url comme image_url du produit ou de l'événement, ou comme avatar_url ou header_url du profil.

## Serveur MCP

Streamable HTTP, sans état. Mêmes opérations, validation et limites que l'API REST.

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

| Outil | Ce qu'il fait |
| --- | --- |
| `get_my_storefront` | État actuel de la vitrine : profil, URL publique, formule, limites et tous les éléments avec leurs id. |
| `update_profile` | Modifie uniquement les champs du profil reçus. L'adresse (slug) ne peut pas être modifiée. |
| `create_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_social_link` | Crée, modifie ou supprime des produits, des événements et des liens. Les outils de suppression sont marqués comme destructifs. |
| `create_image_upload` | Prépare l'envoi d'une image et renvoie upload_url et public_url. |

### MCP public en lecture seule

Pour chercher dans toutes les vitrines publiées, sans authentification :

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

## Limites et erreurs

- 120 requêtes par minute et par jeton. Au-delà, 429 avec Retry-After.
- Les limites de votre formule s'appliquent comme dans le tableau de bord : au maximum, 403 plan_limit.
- Les réponses portent Cache-Control: no-store.

### Format des erreurs

Chaque erreur renvoie un JSON avec un code stable et une description lisible :

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

| Code | HTTP | Signification |
| --- | --- | --- |
| `invalid_input` | 400 | Un champ manque, est inconnu ou a un format non valide. |
| `invalid_token` | 401 | Jeton absent, inconnu, révoqué ou expiré. |
| `insufficient_scope` | 403 | Le jeton n'a pas l'autorisation demandée par l'opération. |
| `plan_limit` | 403 | La limite de la formule est atteinte ou l'essai est terminé. |
| `not_found` | 404 | L'élément n'existe pas dans votre vitrine. |
| `no_profile` | 409 | Le compte n'a pas encore terminé l'onboarding. |
| `rate_limited` | 429 | Trop de requêtes au cours de la dernière minute. |

## Sécurité et confidentialité

- Nous ne conservons qu'un hash de chaque jeton. Si vous le perdez, créez-en un autre.
- Un jeton ne peut lire ni vos contacts, ni vos avis, ni votre facturation, ni changer l'adresse de votre vitrine.
- Les modifications sont publiées immédiatement pour vos clients : demandez à votre assistant de confirmer avant de supprimer.

## Vous n'avez pas encore de vitrine ?

Créez la vôtre et connectez votre assistant ensuite. Mercader propose 14 jours d'essai.

[Créer ma vitrine](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)