merka.ch
Se connecter
Retour aux annonces

API

Le catalogue de Merka se lit par une API publique. Une seule adresse, un seul verbe, du JSON-RPC 2.0 dans le corps : c’est le protocole MCP, celui que parlent les assistants. Cette page montre comment faire une requête, et ce qu’on obtient.

https://merka.ch/api/mcp

Ce que l’API rend, et ce qu’elle ne rend pas

  • Lecture seule. Aucun outil ne modifie quoi que ce soit : ni annonce, ni compte, ni commande.
  • Aucune donnée personnelle. Les réponses portent le titre, le prix, l’état, la catégorie, la ville et le lien d’une annonce. Jamais le nom, l’adresse, le contact ni l’identifiant d’un vendeur.
  • Aucune clé à demander. L’API est ouverte, comme les pages du site qu’elle décrit.

Faire une requête

Le champ « method » choisit ce qui est fait, « params » porte l’outil et ses arguments. À copier tel quel dans un terminal :

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 réponse :

{
  "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-…\"
      }]
    }" }]
  }
}

Les outils

La liste ci-dessous est celle que rend l’appel « tools/list » — même source, donc jamais périmée.

rechercher_annonces

Cherche des objets d'occasion en vente sur Merka (Suisse). Rend au plus 50 résultats, avec titre, prix en francs, état, catégorie et lien.

Paramètres

  • texte · string — Mots-clés, en français, allemand, italien ou anglais
  • categorie · string — 61 valeurs (lister_categories)
  • prixMax · number — Prix maximum de l'objet, en CHF
  • limite · number — 1 à 50, défaut 20

obtenir_annonce

Rend le détail d'une annonce à partir de son identifiant.

Paramètres

  • id · string, obligatoire — Identifiant rendu par la recherche

lister_categories

Rend les 61 familles du catalogue et le nombre d'annonces publiées.

Paramètres

Aucun paramètre.

Les limites

Elles comptent par adresse appelante.

  • 120 appels par minute
  • 20'000 appels par jour
  • 50 résultats au maximum par appel

Un refus rend un en-tête « Retry-After » en secondes : attendez ce délai plutôt que de réessayer en boucle.

Un usage plus large, un flux complet, un besoin d’écriture : écrivez-nous, on en parle. contact@merka.ch

Ajouter Merka dans Claude

Merka s’ajoute comme connecteur personnalisé. Il n’y a rien à installer et rien à autoriser : le connecteur ne lit que le catalogue public. C’est cette adresse, seule, qu’il faut coller :

https://merka.ch/api/mcp
  1. 1Ouvrir les réglages, puis « Connecteurs ».
  2. 2« Ajouter un connecteur personnalisé ».
  3. 3Coller l’adresse ci-dessus dans le champ, et rien d’autre.
  4. 4« Ajouter ». Merka apparaît dans la liste, prêt à l’emploi.

Offres Team et Enterprise : un propriétaire l’ajoute d’abord dans les réglages de l’organisation, les membres cliquent ensuite sur « Connecter ».

Dans Claude Code, une ligne suffit :

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

Ajouter Merka dans ChatGPT

Deux chemins. Le plus sûr est la ligne de commande : elle écrit le réglage sans passer par aucun menu.

Dans un terminal :

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

Par la fenêtre de réglages, si vous préférez :

https://merka.ch/api/mcp
  1. 1Ouvrir la fenêtre « Se connecter à un MCP personnalisé ».
  2. 2Nom : Merka.
  3. 3Type : « Diffusion HTTP en continu ».
  4. 4Coller l’adresse, puis enregistrer.

L’étape 3 est celle qu’on rate : la fenêtre s’ouvre sur « STDIO », qui lance un programme sur votre propre machine. Tant qu’elle y reste, le champ réclame une commande à lancer et l’adresse n’a nulle part où aller.

Ce réglage vit dans un fichier, sur l’ordinateur où vous le faites. Il est donc à refaire sur chaque ordinateur, et il ne suit pas le téléphone.

La description machine

Deux formats, un seul contrat : les deux sont produits à partir de la même définition, ils ne peuvent pas diverger.

  • /api/openapi.json — Description OpenAPI 3.1, pour les outils REST et les générateurs de client.
  • {"jsonrpc":"2.0","id":1,"method":"tools/list"} — Le schéma natif du protocole, rendu par l’appel « tools/list ».