Pour les développeurs et les agents

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 Lire le guide pas à pas

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

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 ou votre propre code

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

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.

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.

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

Autorisations (scopes)

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.

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

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

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

Envoyer des images

Demandez un envoi avec kind (product, event, avatar ou header) et content_type (image/jpeg, image/png ou image/webp).
Envoyez les octets de l'image en PUT vers upload_url. L'URL expire au bout de 2 heures.
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

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

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

Format des erreurs
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