Schnittstelle für Software und Agenten

Diese Plattform ist zum Inserieren da, und das soll auch eine Software können — ein Warenwirtschaftssystem, ein Skript oder ein KI-Agent. Die Oberfläche ist eine Darstellung; die Schnittstelle ist der gleichberechtigte zweite Weg.

Der Zugang

Den Schlüssel stellt der Nutzer selbst aus, unter «Zugänge» in seinem Konto, und gibt ihn der Software bekannt. Wir stellen keine Schlüssel aus und können einen ausgestellten nicht wieder anzeigen — er wird gehasht gespeichert.

Zu den Zugängen

Mitgeschickt wird er als gewöhnlicher Bearer-Kopf:

Authorization: Bearer ia_…

Für die Maschine: das Schema

Diese Seite erklärt einem Menschen, was ein Agent darf. Der Agent selbst liest lieber ein Schema — es steht als OpenAPI unter der Adresse unten und braucht keinen Schlüssel: Wer einen Klienten baut, hat noch keinen.

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

Was ein Schlüssel darf

Vier Dinge: erstellen, anhalten, fortsetzen und die eigenen lesen. Alles andere antwortet 403 — auch dann, wenn ein Weg später dazukommt: Erlaubt ist, was in der Tabelle steht, nicht alles ausser dem Verbotenen.

Die Wege

Zum Ausfüllen — diese Wege sind auch ohne Schlüssel offen:

Was er nicht darf

Löschen, bearbeiten, verkauft melden, verlängern, das Profil ändern, Nachrichten schreiben, weitere Schlüssel ausstellen. Dafür braucht es eine Anmeldung mit E-Mail und Passwort. Und fortsetzen kann ein Schlüssel nur, was er selbst angehalten hat: Was Sie im Browser anhalten, stellen nur Sie wieder in die Suche.

Wie weit ein Schlüssel reicht

Das entscheidet der Mensch beim Ausstellen, und die Vorgabe ist die engere: Ein gewöhnlicher Schlüssel sieht und bewegt nur die Inserate, die er selbst angelegt hat. Wer «alle Inserate dieses Kontos» wählt, bekommt einen Schlüssel, der auch die aus dem Browser anfassen darf. Ausserhalb seiner Reichweite antwortet ein Weg 403 mit felder.grund = ausserhalb-des-schluessels — gelesen wird genau so weit, wie auch angefasst werden darf.

Ein vollständiges Beispiel

Das ist der kleinste Rumpf, mit dem ein Inserat öffentlich wird — jedes Feld darin ist Pflicht, keines fehlt. Ein Entwurf (status: entwurf) darf Lücken haben; ein öffentliches Inserat braucht Titel, mindestens 20 Zeichen Beschreibung, Kategorie, Preisart samt Preis und die vollständige Ortsangabe.

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

Und das kommt zurück — gekürzt auf das, was ein Aufrufer wirklich liest:

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

Dieselbe Anfrage zweimal

Ein Netzabbruch darf kein zweites Inserat erzeugen. Schicken Sie beim Erstellen einen eigenen Wert mit — Ihre Bestandsnummer ist der natürliche Kandidat. Kommt derselbe Wert innerhalb von 24 Stunden erneut, antworten wir mit 200, derselben Kennung und wiederholung: true, statt neu anzulegen. Der Wert gilt je Konto; kurze Nummern sind ausdrücklich in Ordnung.

Idempotenz-Schluessel: VH-1009

Wie oft

Je Schlüssel: 20 Erstellungen in der Stunde, 100 am Tag. Für gewerbliche Konten sind es 50 in der Stunde — ein Bestand wird am Stück eingepflegt, nicht tröpfchenweise; die Tagesgrenze bleibt dieselbe. Wird es zu viel, antworten wir 429 und nennen im Kopf Retry-After die Sekunden bis zum nächsten Versuch — warten Sie sie ab, statt zu raten. Anfragen aus der Oberfläche zählen hier nicht mit.

Was schiefgehen kann

Jeder Fehler antwortet mit derselben Form: ein Satz in fehler, und wo es etwas zu unterscheiden gibt, ein Feld in felder. Die drei 401 sind absichtlich unterscheidbar — sie verlangen Gegenteiliges von Ihnen.

Was zurückkommt

Beim Erstellen bekommen Sie das Inserat, und dazu zwei Auskünfte, die nichts verhindern: marktlage sagt, in welcher Spanne die Kategorie liegt und ob Ihr Preis darüber liegt; hinweis erscheint, wenn wir Ihre Postleitzahl nicht kennen — das Inserat steht dann in keiner Umkreissuche. Beim Pausieren sagen wir Ihnen, wie viele Gespräche und offene Preisvorschläge Sie damit stehen lassen.

Wozu wir uns verpflichten

• Wir prüfen Inserate auf Richtigkeit. Ein Inserat, das gegen die Regeln verstösst, wird gesperrt — auch eines, das eine Software eingestellt hat.
• Jedes über die Schnittstelle erstellte Inserat weiss, woher es kommt. Der Anbieter und die Verwaltung sehen es; Käufer nicht.
• Ein Widerruf wirkt sofort. Eine Kontosperre und eine Kontoauflösung widerrufen alle Schlüssel des Kontos.
• Der Schlüsselwert wird gehasht gespeichert. Wir können ihn nicht wiederherstellen und werden ihn nie von Ihnen erfragen.

Ein Hinweis zum Schluss

Diese Schnittstelle ist zum Inserieren gebaut, nicht zum Absaugen. Wer Daten in grosser Zahl abzieht, verstösst gegen die Nutzungsregeln — und die Bremse ist danach bemessen, was ein Anbieter mit seinem eigenen Bestand tut.