Klickpfade über die API bearbeiten

Dieser Artikel beschreibt die Endpunkte, über die eigene Skripte Klickpfade und die Schritte einer mehrstufigen Anmeldung entwerfen und ausprobieren. Ein KI-Assistent nutzt dieselben Regeln über den MCP-Server (Anmeldung und Klickpfade beschreiben). Die Schrittsprache selbst steht in Anmeldung und Klickpfade beschreiben.

Token und Rechte

Sie brauchen ein Token, das an die Website gebunden ist und das Recht „Klickpfade bearbeiten“ trägt. Wie Sie es anlegen, steht in Anmeldung und Klickpfade beschreiben. Mit dem Recht erhält das Token zwei Berechtigungen: journeys:read zum Lesen und Prüfen, journeys:write zum Speichern von Entwürfen und zum Starten von Probeläufen.

Jede Anfrage trägt das Token als Kopfzeile, die Basisadresse ist https://barrierepruefung.de/api/v1:

Authorization: Bearer IHR_TOKEN
Accept: application/json
Accept-Language: de

{site} in den Pfaden ist die „Website-Kennung“ aus dem Reiter „Einbindung“. Für jede andere Website antwortet die API mit 404. Texte in Antworten folgen Accept-Language (de oder en). Schreibende Aufrufe nehmen optional actor_name an: den Namen, unter dem Ihr System die handelnde Person kennt. Er steht am Entwurf als Beleg, verantwortlich bleibt die Person, die das Recht erteilt hat.

Endpunkte

Das Schema der Schrittsprache steht ohne Token unter https://barrierepruefung.de/api/v1/schema/klickpfad.json und https://barrierepruefung.de/api/v1/schema/anmeldeablauf.json (JSON Schema 2020-12).

Freigeben und Löschen gibt es über die API nicht. Zugangsdaten auch nicht: Weder Benutzername, Passwort noch das Geheimnis für den Einmalcode, keine Anmeldedienste und keine Bestätigung dafür werden gesetzt oder ausgegeben.

Schritte prüfen

POST /sites/{site}/journeys/pruefen mit steps und optional stop_before speichert nichts und antwortet immer mit 200. Ein ungültiger Pfad ist hier das Ergebnis:

{
  "gueltig": false,
  "fehler": [
    {
      "code": "selektor_nicht_erlaubt",
      "schritt": 2,
      "feld": "selector",
      "text": "Schritt 2: Der Selektor enthält unerlaubte Zeichen. Erlaubt sind CSS-Selektoren, role=… und text=…."
    }
  ],
  "bereinigt": [
    {"action": "goto", "url": "/warenkorb"},
    {"action": "click", "selector": "xpath=//button"}
  ]
}

Einen Entwurf speichern

POST /sites/{site}/journeys legt einen neuen Klickpfad an, mit name, steps und optional stop_before. Er hat danach keine laufenden Schritte, nur einen Entwurf. PUT /sites/{site}/journeys/{id}/entwurf setzt den Entwurf eines vorhandenen Pfads; dessen Name bleibt, die laufenden Schritte auch.

{
  "name": "Bestellstrecke",
  "steps": [
    {"action": "goto", "url": "/warenkorb"},
    {"action": "click", "selector": "role=button[name=\"Zur Kasse\"]"}
  ],
  "stop_before": "role=button[name=\"Zahlungspflichtig bestellen\"]",
  "actor_name": "Build-Skript"
}

Die Antwort (201 beim Anlegen, sonst 200) beschreibt den Pfad:

{
  "data": {
    "id": 42,
    "name": "Bestellstrecke",
    "status": "entwurf",
    "schritte": [],
    "stop_before": null,
    "entwurf": {
      "schritte": [
        {"action": "goto", "url": "/warenkorb"},
        {"action": "click", "selector": "role=button[name=\"Zur Kasse\"]"}
      ],
      "stop_before": "role=button[name=\"Zahlungspflichtig bestellen\"]",
      "von": {"weg": "api", "name": "Build-Skript", "token_name": "Build"},
      "am": "2026-10-30T09:15:00+00:00"
    },
    "freigegeben": null,
    "letzter_lauf": {
      "status": "gescheitert",
      "am": "2026-10-30T03:12:44+00:00",
      "lauf_id": "01JBX0A2C4E6G8H1J3K5M7N9P0",
      "seitdem_geaendert": false,
      "grund": null,
      "befund": {
        "code": "element_versteckt",
        "schritt": 2,
        "schritte": 2,
        "aktion": "click",
        "selektor": "role=button[name=\"Zur Kasse\"]",
        "viewport": "mobile",
        "befund": {"treffer": 1, "sichtbar": 0},
        "ueberschrift": "Schritt 2 von 2 gescheitert (click, Mobil, 390 px)",
        "erklaerung": "Der Selektor trifft ein Element, es ist aber nicht sichtbar.",
        "hinweis": "Wählen Sie ein Element, das in dieser Breite sichtbar ist, …"
      }
    },
    "freigabe_url": "…/websites/…/pruefung"
  }
}

status ist entwurf, freigegeben oder freigegeben_mit_entwurf. letzter_lauf ist null, solange der Pfad in keinem abgeschlossenen Lauf vorkam. Sonst steht dort der Stand im letzten Lauf: status ist erfolgreich, gescheitert oder nicht_geprueft (kein Scheitern des Pfads: Anmeldung, Drosselung, Frist, Budget oder Proxy verhinderten die Prüfung, der Grund steht in grund), am und lauf_id nennen den Lauf, seitdem_geaendert ist true, wenn der Pfad danach freigegeben wurde. Nur bei gescheitert ist befund gesetzt: code ist einer der Codes aus Anmeldung und Klickpfade beschreiben, schritt, schritte, aktion, selektor und viewport sagen, wo, befund enthält die Messwerte (treffer, sichtbar, erster_sichtbar, erster_bedienbar, abgeloest, navigiert, adresse; je nach Code nicht alle), und ueberschrift, erklaerung und hinweis sind Texte in der Sprache der Anfrage. Verzweigen Sie an code, nicht an den Texten.

Unter freigabe_url gibt eine Person den Entwurf frei (Anmeldung und Klickpfade beschreiben).

Für eine mehrstufige Anmeldung schlägt PUT /sites/{site}/anmeldung/entwurf mit schritte die Schritte vor, mit Platzhaltern statt Zugangsdaten (Anmeldung und Klickpfade beschreiben). Das geht nur, wenn im Reiter „Prüfung“ bereits ein Zugang dieser Art angelegt ist; sonst antwortet die API mit 404, bei einem einfachen Anmeldeformular mit kein_ablauf.

Probeläufe

POST /sites/{site}/probelaeufe startet einen Probelauf und antwortet sofort mit 202. Er braucht genau eine Quelle:

• {"journey_id": 42, "quelle": "entwurf"} oder "quelle": "freigegeben": ein gespeicherter Klickpfad. Ist ein Zugang aktiv, meldet sich der Probelauf wie eine Prüfung zuerst an.
• {"anmeldung": "entwurf"}: nur der Entwurf der Anmeldung.
• {"schritte": [...], "stop_before": "…"}: ungespeicherte Schritte, ohne Anmeldung.

Den Stand fragen Sie mit GET /sites/{site}/probelaeufe/{id} ab, bis status nicht mehr wartet oder laeuft ist:

{
  "data": {
    "id": "01JBX3K7Q8M4V2N6P0R5S9T1W3",
    "status": "fertig",
    "quelle": "entwurf",
    "journey_id": 42,
    "mit_anmeldung": false,
    "erfolgreich": false,
    "grund": null,
    "schritte": [
      {"nr": 1, "viewport": "desktop", "action": "goto", "ok": true, "grund": null, "adresse": "https://www.example.org/warenkorb", "aria": "- main: …", "befund": null, "bild_url": "…"},
      {"nr": 2, "viewport": "desktop", "action": "click", "ok": false, "grund": "klick_abgelehnt:nicht_gefunden", "adresse": "https://www.example.org/warenkorb", "aria": "- main: …", "befund": {"code": "klick_abgelehnt:nicht_gefunden", "schritt": 2, "schritte": 2, "aktion": "click", "selektor": "role=button[name=\"Zur Kasse\"]", "viewport": "desktop", "befund": {"treffer": 0, "sichtbar": 0}, "ueberschrift": "…", "erklaerung": "…", "hinweis": "…"}, "bild_url": "…"}
    ],
    "anmeldung": null,
    "dauer_ms": 5120,
    "angelegt_am": "2026-10-30T09:16:00+00:00",
    "fertig_am": "2026-10-30T09:16:07+00:00",
    "loeschen_ab": "2026-10-31T09:16:00+00:00",
    "freigabe_hinweis": "Bevor dieser Pfad in Prüfungen läuft, muss eine Person ihn im Tab ‚Prüfung‘ freigeben: …"
  }
}

• status: wartet, laeuft, fertig, gescheitert (der Probelauf als Ganzes scheiterte, Grund in grund, etwa start_fremder_host, eine Fehlerseite des Proxys proxy_fehler:…, budget_ueberschritten, abgelaufen oder scanner_veraltet während einer Aktualisierung) oder abgelehnt.
• erfolgreich: true nur, wenn der Probelauf fertig ist, kein Schritt scheiterte und wirklich etwas gelang (ein Schritt mit ok: true oder, bei einem Probelauf nur der Anmeldung, eine gelungene Anmeldung); null, solange er läuft. Verzweigen Sie daran, nicht an status: Auch ein fertiger Probelauf kann an einem Schritt gescheitert sein.
• Ein Probelauf prüft jede Breite des Prüfprofils nacheinander und endet beim ersten Scheitern. schritte enthält einen Eintrag je Schritt und Breite; viewport ist desktop, mobile oder reflow-320 (ältere Ergebnisse ohne Angabe gelten als desktop). Bei einem gescheiterten Schritt trägt befund dieselbe Form wie in letzter_lauf, mit selektor; sonst ist er null. Das Bild gehört zu Schritt und Breite.
• Je Schritt ok: true, false oder null für „nicht ausgeführt“. Nach dem ersten Fehlschlag endet der Probelauf. Die Gründe sind dieselben wie in einer Prüfung (Anmeldung und Klickpfade beschreiben); stop_before heißt, dass der Pfad vor dem Abbruchziel angehalten hat.
• bild_url ist eine signierte Adresse, die 10 Minuten gilt. Fragen Sie den Probelauf erneut ab, bekommen Sie eine neue.
• Liegt ein Schritt außerhalb Ihrer Domain, steht in adresse nur die Herkunft, aria und bild_url sind leer.
• Nach loeschen_ab sind Ergebnis und Bilder gelöscht.

Die Grenzen der Probeläufe stehen in Anmeldung und Klickpfade beschreiben.

Fehler

Fehler kommen als application/problem+json mit status, detail (Satz in der Sprache der Anfrage) und, wo es eine gibt, einer stabilen Kennung reason. Verzweigen Sie an reason, nicht am Satz.

Die Codes in fehler[].code bilden ein abgeschlossenes Verzeichnis: