Per sviluppatori e agenti

API e MCP per modificare la tua vetrina

Collega Claude, ChatGPT, Cursor o il tuo script alla tua vetrina Mercader. Possono leggere e modificare il tuo profilo, i tuoi prodotti, i tuoi eventi e i tuoi link, e ogni modifica viene pubblicata subito.

Crea un token nel pannello Leggi la guida passo passo

Inizia in un minuto

Scegli il tuo client. Con OAuth non copi nessun token: il tuo assistente apre la schermata dei permessi di Mercader e tu approvi l'accesso.

Claude.ai o ChatGPT

Aggiungi un connettore personalizzato e incolla questo 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 o il tuo codice

Crea un token personale nel pannello e invialo come Bearer:

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

Autenticazione

Ogni richiesta porta l'intestazione Authorization: Bearer <token>. Un token dà accesso solo alla vetrina di chi l'ha creato.

OAuth 2.1 (consigliato per gli assistenti)

Registrazione dinamica dei client (RFC 7591) e codice di autorizzazione con PKCE S256. Solo client pubblici, senza segreto.
Discovery: la risposta 401 del MCP include WWW-Authenticate con l'URL dei metadati della risorsa protetta.
Il token di accesso dura 1 ora e quello di aggiornamento 30 giorni. Ogni aggiornamento li rinnova entrambi.
Revoca (RFC 7009) su /oauth/revoke, o dal pannello in qualsiasi momento.

Token personali

Creali nel pannello, in Admin › Assistenti IA. Iniziano con mk_live_ e vengono mostrati una sola volta.
Non scadono: revocali dal pannello quando non ti servono più.
Utili per script, curl e client senza OAuth.

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

Permessi (scope)

Permessi (scope)
Permesso	Cosa fa
`profile:write`	Nome, presentazione, colore, lingua, valuta, logo, copertina e link.
`catalog:write`	Prodotti, eventi e mercatini, e le loro immagini.

API REST

JSON su HTTPS. I campi che non invii restano invariati; una stringa vuota cancella un campo facoltativo.

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

API REST
Metodo	Percorso	Permesso	Cosa fa
GET	`/me`	qualsiasi	Profilo, piano e limiti, prodotti, eventi e link, con i loro id.
PATCH	`/profile`	`profile:write`	Cambia nome, presentazione, colore, lingua, paese, valuta, logo o copertina.
GET	`/products`	qualsiasi	Elenca i prodotti.
POST	`/products`	`catalog:write`	Crea un prodotto (name e price obbligatori).
PATCH	`/products/{id}`	`catalog:write`	Cambia prezzo, foto, disponibilità o altri campi.
DELETE	`/products/{id}`	`catalog:write`	Elimina un prodotto.
GET	`/events`	qualsiasi	Elenca eventi e mercatini.
POST	`/events`	`catalog:write`	Crea un evento (title e start_date in ISO 8601).
PATCH	`/events/{id}`	`catalog:write`	Modifica un evento.
DELETE	`/events/{id}`	`catalog:write`	Elimina un evento.
GET	`/social-links`	qualsiasi	Elenca i link social e di contatto.
POST	`/social-links`	`profile:write`	Aggiunge un link (Instagram, WhatsApp, Website, Email…).
PATCH	`/social-links/{id}`	`profile:write`	Modifica un link.
DELETE	`/social-links/{id}`	`profile:write`	Elimina un link.
POST	`/uploads`	secondo il tipo	Restituisce un URL firmato per caricare un'immagine.

Esempio: creare un prodotto

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

Schemi completi nella specifica OpenAPI 3.1

Caricare immagini

Richiedi un caricamento con kind (product, event, avatar o header) e content_type (image/jpeg, image/png o image/webp).
Invia i byte dell'immagine con PUT a upload_url. L'URL scade dopo 2 ore.
Usa public_url come image_url del prodotto o dell'evento, o come avatar_url o header_url del profilo.

Server MCP

Streamable HTTP, senza stato. Stesse operazioni, convalide e limiti dell'API REST.

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

Server MCP
Strumento	Cosa fa
`get_my_storefront`	Stato attuale della vetrina: profilo, URL pubblico, piano, limiti e tutti gli elementi con i loro id.
`update_profile`	Cambia solo i campi del profilo che riceve. L'indirizzo (slug) non si può cambiare.
`create_productupdate_productdelete_productcreate_eventupdate_eventdelete_eventcreate_social_linkupdate_social_linkdelete_social_link`	Crea, modifica o elimina prodotti, eventi e link. Gli strumenti di eliminazione sono segnalati come distruttivi.
`create_image_upload`	Prepara il caricamento di un'immagine e restituisce upload_url e public_url.

MCP pubblico in sola lettura

Per cercare in tutte le vetrine pubblicate, senza autenticazione:

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

Limiti ed errori

120 richieste al minuto per token. Oltre, 429 con Retry-After.
I limiti del tuo piano valgono come nel pannello: al massimo ricevi 403 plan_limit.
Le risposte portano Cache-Control: no-store.

Formato degli errori

Ogni errore restituisce un JSON con un codice stabile e una descrizione leggibile:

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

Formato degli errori
Codice	HTTP	Significato
`invalid_input`	400	Un campo manca, è sconosciuto o ha un formato non valido.
`invalid_token`	401	Token assente, sconosciuto, revocato o scaduto.
`insufficient_scope`	403	Il token non ha il permesso richiesto dall'operazione.
`plan_limit`	403	Hai raggiunto il limite del piano o la prova è terminata.
`not_found`	404	L'elemento non esiste nella tua vetrina.
`no_profile`	409	L'account non ha ancora completato l'onboarding.
`rate_limited`	429	Troppe richieste nell'ultimo minuto.

Sicurezza e privacy

Conserviamo solo un hash di ogni token. Se lo perdi, creane un altro.
Un token non può leggere i tuoi contatti, le tue recensioni o la fatturazione, né cambiare l'indirizzo della tua vetrina.
Le modifiche sono subito visibili ai tuoi clienti: chiedi al tuo assistente di confermare prima di eliminare.

Non hai ancora una vetrina?

Crea la tua e collega il tuo assistente dopo. Mercader include 14 giorni di prova.

Crea la mia vetrina