---
title: "API e MCP di Mercader per agenti IA"
description: "Documentazione dell'API REST e del server MCP di Mercader: OAuth 2.1, token personali, endpoint, strumenti, caricamento immagini, limiti ed errori."
url: https://www.mercader.app/it/developers
language: it
---

# 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: https://app.mercader.app/admin?tab=agents
- Leggi la guida passo passo: https://www.mercader.app/it/blog/gestisci-la-tua-vetrina-con-l-ia.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

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

```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 o il tuo codice

Crea un token personale nel pannello e invialo come Bearer:

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

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

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

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

| 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

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

[Schemi completi nella specifica OpenAPI 3.1](https://web.mercader.app/api/v1/openapi.json)

## Caricare immagini

1. Richiedi un caricamento con kind (product, event, avatar o header) e content_type (image/jpeg, image/png o image/webp).
2. Invia i byte dell'immagine con PUT a upload_url. L'URL scade dopo 2 ore.
3. 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
```

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

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

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