merka.ch
Accedere
Torna agli annunci

API

Il catalogo di Merka si legge tramite un’API pubblica. Un solo indirizzo, un solo verbo, JSON-RPC 2.0 nel corpo: è il protocollo MCP, quello che parlano gli assistenti. Questa pagina mostra come fare una richiesta e che cosa si ottiene.

https://merka.ch/api/mcp

Che cosa restituisce l’API, e che cosa no

  • Sola lettura. Nessuno strumento modifica alcunché: né annuncio, né conto, né ordine.
  • Nessun dato personale. Le risposte contengono titolo, prezzo, stato, categoria, città e link di un annuncio. Mai il nome, l’indirizzo, il contatto o l’identificativo di chi vende.
  • Nessuna chiave da richiedere. L’API è aperta, come le pagine del sito che descrive.

Fare una richiesta

Il campo «method» sceglie che cosa viene fatto, «params» porta lo strumento e i suoi argomenti. Da copiare così com’è in un terminale:

curl -s https://merka.ch/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"rechercher_annonces",
                 "arguments":{"texte":"livre","limite":2}}}'

La risposta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{
      \"resultats\": 1,
      \"annonces\": [{
        \"id\": \"1b69a020-…\",
        \"titre\": \"Livre Statistiques pour l'économie\",
        \"prixChf\": 25,
        \"categorie\": \"Scolaire & études\",
        \"etat\": \"bon\",
        \"ville\": \"Nyon\",
        \"lien\": \"https://merka.ch/annonce/1b69a020-…\"
      }]
    }" }]
  }
}

Gli strumenti

L’elenco qui sotto è quello restituito dalla chiamata «tools/list»: stessa fonte, quindi mai obsoleto.

rechercher_annonces

Cerca oggetti usati in vendita su Merka (Svizzera). Restituisce al massimo 50 risultati con titolo, prezzo in CHF, stato, categoria e link.

Parametri

  • texte · string — Parole chiave in francese, tedesco, italiano o inglese
  • categorie · string — 61 valori (lister_categories)
  • prixMax · number — Prezzo massimo dell'oggetto, in CHF
  • limite · number — Da 1 a 50, valore predefinito 20

obtenir_annonce

Restituisce i dettagli di un annuncio tramite il suo identificativo.

Parametri

  • id · string, obbligatorio — Identificativo restituito dalla ricerca

lister_categories

Restituisce le 61 categorie e il numero di annunci pubblicati.

Parametri

Nessun parametro.

I limiti

Contano per indirizzo chiamante.

  • 120 chiamate al minuto
  • 20'000 chiamate al giorno
  • 50 risultati al massimo per chiamata

Un rifiuto restituisce un’intestazione «Retry-After» in secondi: attendere quel tempo invece di riprovare in continuazione.

Un uso più ampio, un flusso completo, la scrittura: scriveteci, ne parliamo. contact@merka.ch

Aggiungere Merka in Claude

Merka si aggiunge come connettore personalizzato. Niente da installare e niente da autorizzare: il connettore legge solo il catalogo pubblico. Va incollato questo indirizzo, e nient’altro:

https://merka.ch/api/mcp
  1. 1Aprire le impostazioni, poi «Connectors».
  2. 2«Add custom connector».
  3. 3Incollare l’indirizzo qui sopra, e nient’altro.
  4. 4«Add». Merka compare nell’elenco, pronto all’uso.

Piani Team ed Enterprise: un owner lo aggiunge prima nelle impostazioni dell’organizzazione, poi i membri cliccano su «Connect».

In Claude Code basta una riga:

claude mcp add --transport http merka https://merka.ch/api/mcp

Aggiungere Merka in ChatGPT

Due strade. La più sicura è la riga di comando: scrive l’impostazione senza passare da alcun menu.

In un terminale:

codex mcp add merka --url https://merka.ch/api/mcp

Dalla finestra delle impostazioni, se preferite:

https://merka.ch/api/mcp
  1. 1Aprire la finestra «Connetti a un MCP personalizzato».
  2. 2Nome: Merka.
  3. 3Tipo: «Streaming HTTP».
  4. 4Incollare l’indirizzo, poi salvare.

Il passo 3 è quello che sfugge: la finestra si apre su «STDIO», che avvia un programma sul proprio computer. Finché resta così, il campo chiede un comando da avviare e l’indirizzo non ha dove andare.

Questa impostazione vive in un file, sul computer dove la fate. Va quindi rifatta su ogni computer e non vale per il telefono.

La descrizione per le macchine

Due formati, un solo contratto: entrambi derivano dalla stessa definizione e non possono divergere.

  • /api/openapi.json — Descrizione OpenAPI 3.1, per gli strumenti REST e i generatori di client.
  • {"jsonrpc":"2.0","id":1,"method":"tools/list"} — Lo schema nativo del protocollo, restituito dalla chiamata «tools/list».