Interface pour logiciels et agents

Cette plateforme sert à publier des annonces, et un logiciel doit pouvoir le faire aussi — un système de gestion des stocks, un script ou un agent IA. L’interface web est une représentation ; l’API est le second chemin, à parts égales.

L’accès

La clé est créée par l’utilisateur lui-même, sous «Accès» dans son compte, puis communiquée au logiciel. Nous ne créons aucune clé et ne pouvons pas réafficher une clé existante : elle est stockée sous forme de hachage.

Vers les accès

Elle s’envoie comme un en-tête Bearer ordinaire :

Authorization: Bearer ia_…

Pour la machine : le schéma

Cette page explique à un humain ce qu’un agent peut faire. L’agent, lui, préfère un schéma — il est disponible en OpenAPI à l’adresse ci-dessous et ne demande aucune clé : qui construit un client n’en a pas encore.

GET https://inserate-anzeigen.ch/api/schnittstelle.json

Ce qu’une clé peut faire

Exactement trois choses. Tout le reste répond 403 — y compris un chemin ajouté plus tard : est autorisé ce qui figure dans le tableau, et non tout ce qui n’est pas interdit.

Les chemins

Pour remplir les champs — ces chemins sont ouverts même sans clé :

Ce qu’elle ne peut pas faire

Supprimer, modifier, signaler comme vendu, prolonger, changer le profil, écrire des messages, créer d’autres clés. Cela demande une connexion avec l’adresse e-mail et le mot de passe. Et une clé ne peut republier que ce qu’elle a elle-même suspendu : ce que vous suspendez dans le navigateur, vous seul le remettez en ligne.

Quelle est la portée d’une clé

Cela se décide à la création, et le choix par défaut est le plus étroit : une clé ordinaire ne voit et ne touche que les annonces qu’elle a publiées elle-même. Qui choisit «toutes les annonces de ce compte» obtient une clé qui touche aussi celles du navigateur. Hors de sa portée, un chemin répond 403 avec felder.grund = ausserhalb-des-schluessels — on lit exactement aussi loin qu’on peut agir.

Un exemple complet

Voici le corps de requête minimal pour publier une annonce : chaque champ y est obligatoire, aucun ne manque. Un brouillon (status: entwurf) peut avoir des lacunes ; une annonce publique exige un titre, au moins 20 caractères de description, une catégorie, le type de prix avec le prix, et la localité complète.

POST /api/inserate
Authorization: Bearer ia_…
Idempotenz-Schluessel: VH-1009
Content-Type: application/json

{
  "titel": "Cube Aim Pro Mountainbike",
  "beschreibung": "Occasion, geprüft und fahrbereit. Abholung in Zürich.",
  "kategorieId": 4,
  "preisart": "fix",
  "preis": 780,
  "plz": "8004",
  "ort": "Zürich",
  "kanton": "ZH"
}

Et voici la réponse, réduite à ce qu’un appelant lit vraiment :

201 Created

{
  "inserat": {
    "id": 418,
    "slug": "cube-aim-pro-mountainbike-418",
    "status": "aktiv", …
  },
  "marktlage": {
    "spiegel": {
      "anzahl": 14,
      "vonRappen": 196500,
      "bisRappen": 335000,
      "dazwischen": 6
    },
    "ungewoehnlichHoch": false
  }
}

La même requête deux fois

Une coupure réseau ne doit pas créer une deuxième annonce. Envoyez votre propre valeur lors de la création — votre numéro de stock est le candidat naturel. Si la même valeur revient dans les 24 heures, nous répondons 200, avec le même identifiant et wiederholung: true, au lieu de créer. La valeur vaut par compte ; les numéros courts sont expressément admis.

Idempotenz-Schluessel: VH-1009

À quelle fréquence

Par clé : 20 créations par heure, 100 par jour. Pour les comptes professionnels, 50 par heure — un stock se saisit d’un seul tenant, pas au compte-gouttes ; la limite journalière reste la même. Au-delà, nous répondons 429 et indiquons dans l’en-tête Retry-After les secondes à attendre — attendez-les au lieu de deviner. Les requêtes venant de l’interface web ne comptent pas ici.

Ce qui peut échouer

Chaque erreur a la même forme : une phrase dans fehler et, lorsqu’il y a quelque chose à distinguer, un champ dans felder. Les trois 401 sont délibérément distinguables — elles exigent de vous des choses opposées.

Ce qui revient

À la création, vous recevez l’annonce et deux informations qui n’empêchent rien : marktlage indique la fourchette de la catégorie et si votre prix la dépasse ; hinweis apparaît si nous ne connaissons pas votre code postal — l’annonce n’apparaîtra alors dans aucune recherche par rayon. À la mise en pause, nous vous disons combien de conversations et de propositions de prix ouvertes vous laissez en plan.

Ce à quoi nous nous engageons

• Nous vérifions l’exactitude des annonces. Une annonce contraire aux règles est bloquée — y compris celle déposée par un logiciel.
• Chaque annonce créée via l’API sait d’où elle vient. Le vendeur et l’administration le voient ; les acheteurs non.
• Une révocation prend effet immédiatement. Un blocage de compte et une dissolution de compte révoquent toutes les clés du compte.
• La valeur de la clé est stockée sous forme de hachage. Nous ne pouvons pas la restaurer et ne vous la demanderons jamais.

Une remarque pour finir

Cette interface est faite pour publier, pas pour aspirer. Extraire des données en masse contrevient aux règles d’utilisation — et la limite est calibrée sur ce qu’un vendeur fait avec son propre stock.