Schnittstelle: öffentliche Wege

Die Wege auf dieser Seite erreichen Sie ohne Sitzung und ohne Widget-Schlüssel. Sie tragen alles, was vor der Anmeldung geschieht – ein Konto anlegen, die Adresse bestätigen, sich anmelden, ein Passwort zurücksetzen, eine Einladung annehmen –, und das, was außerhalb eines Kontos lesbar ist: Betriebszustand, Änderungsprotokoll, Erklärung zur Barrierefreiheit, Kontaktanfrage, Demo und die Abholung eines Warenkorbs durch Ihren Shop. Die Wege des Widgets beschreibt Widget-Wege, die Anmeldung für alle übrigen Wege Anmeldung an der Schnittstelle.

Überblick

Gemeinsame Regeln

Alle Pfade beginnen mit https://app.xicbot.de/api/v1/; die App ruft sie von diesem Ursprung aus auf. Senden Sie JSON mit Content-Type: application/json und Accept: application/json. Fehler unter /api/ kommen als JSON zurück, auch für unbekannte Pfade. Die Prüfung der Felder antwortet mit 422, einem Text in message und je Feld einer Liste von Meldungen in errors.

Grenzen

Gezählt wird je Herkunft: eine IPv4-Adresse für sich, eine IPv6-Adresse gekürzt auf ihr /64-Netz. Eine IPv4-Adresse in IPv6-Schreibweise wie ::ffff:192.0.2.10 zählt als IPv4. Minuten- und Stundengrenze sind getrennte Zähler; beide müssen frei sein. Wege mit demselben Zähler teilen ihn: status gilt für Betriebszustand, Änderungsprotokoll, Demo-Abfrage und Barrierefreiheit zusammen, auth-token für Bestätigung und neues Passwort, invitation für beide Einladungswege. Ist eine Grenze erreicht, antwortet der Weg mit 429 und dem Kopf Retry-After in Sekunden.

Anmeldung und Passwortanforderung haben zusätzlich eigene Zähler. Deren 429 trägt {"error": "too_many_attempts", "retry_in": …}; retry_in nennt die Sekunden bis zum nächsten erlaubten Versuch. Die Grenzen der übrigen Wege stehen unter Grenzen der Schnittstelle.

Fehlerantworten

Aufrufe aus dem Browser

Aus dem Browser einer anderen Website sind nur die Wege unter /api/v1/public/ lesbar, und nur für die zugelassenen Ursprünge; Ursprünge, Methoden, Köpfe und die Gültigkeit der Vorabfrage stehen unter Schnittstelle: Grundlagen. Registrierung, Anmeldung, Passwort und Einladung sind für fremde Ursprünge nicht freigegeben; die Warenkorbabholung regelt ihre Freigabe selbst, wie weiter unten beschrieben.

Konto anlegen

Die Adresse wird vor dem Speichern vereinheitlicht: ohne Leerraum am Rand, in Unicode-Normalform C, klein geschrieben und ohne den Zusatz hinter einem Plus. Bei Anbietern, die Punkte im lokalen Teil nicht unterscheiden, fallen auch die Punkte weg. Führt ein Anbieter dasselbe Postfach unter zwei Domains, gilt die Adresse unter beiden als dieselbe. Aus Anna+Test@example.com wird so anna@example.com. Ein lokaler Teil in Anführungszeichen bleibt ungefaltet. Ist die vereinheitlichte Adresse schon vergeben, auch durch ein gelöschtes Konto, antwortet der Weg mit 422 und {"error": "validation", "fields": {"email": ["validation.unique"]}}. In der App heißt dieser Schritt Konto anlegen, die Passwortregel steht dort als Mindestens 12 Zeichen, darunter Buchstaben und Ziffern.

Anmelden

Zweiter Faktor

1. 1

   Schritt 1

   Passwort senden

   Hat das Konto einen zweiten Faktor und fehlt totp, antwortet der Weg mit 428. error ist totp_required, wenn eine Authentifizierungs-App eingerichtet ist, sonst webauthn_required. Dazu kommen challenge, expires_in mit 600 Sekunden und methods mit den Faktoren, die sich im zweiten Schritt verwenden lassen: totp, webauthn oder beide. Hat das Konto nur Sicherheitsschlüssel und ist die Anmeldung per Schlüssel auf dem Server nicht eingerichtet, kommt statt der 428 schon hier 503 webauthn_unconfigured. Ist eine Authentifizierungs-App eingerichtet, können Sie totp gleich mit dem Passwort senden und sparen den zweiten Schritt; an einem Konto ohne App ergibt ein mitgesendeter Code bad_totp.

2. 2

   Schritt 2

   Sicherheitsschlüssel vorbereiten

   Sind Sicherheitsschlüssel hinterlegt und ist die Anmeldung per Schlüssel auf dem Server eingerichtet, enthält die Antwort ein Objekt webauthn mit challenge, rp_id, allow (die zugelassenen Schlüsselkennungen) und timeout, mindestens 30. Damit fordern Sie im Browser die Bestätigung am Schlüssel an.

3. 3

   Schritt 3

   Nachweis senden

   Senden Sie email, challenge und entweder totp oder webauthn, ohne Passwort und von derselben IP-Adresse wie im ersten Schritt. Die Aufforderung gilt 600 Sekunden und verfällt beim fünften Fehlversuch; als Fehlversuch zählen ein falscher Code, ein abgelehnter Schlüssel und ein Aufruf von einer anderen IP-Adresse. Ein solcher Aufruf ergibt 422 challenge_expired, lässt die Aufforderung für die ursprüngliche Adresse aber bestehen. Ist sie abgelaufen oder schon verbraucht, antwortet der Weg ebenfalls mit 422 challenge_expired, und Sie beginnen wieder mit dem Passwort.

Das Token gilt 30 Tage; der genaue Zeitpunkt steht in expires_at. Als Namen trägt es die Kennung des Browsers aus User-Agent, höchstens 190 Zeichen, oder sitzung, wenn keine gesendet wurde. Auf den Zähler für Adresse und Herkunft geht jeder Fehlversuch: falsche Zugangsdaten, ein falscher Code, ein abgelehnter Schlüssel und eine abgelaufene Aufforderung oder eine von einer anderen IP-Adresse. Der Zähler je Herkunft allein zählt nur falsche Zugangsdaten. Eine erfolgreiche Anmeldung setzt den Zähler für Adresse und Herkunft zurück, den Zähler je Herkunft nicht. Die App zeigt bei 429 Zu viele Versuche. Bitte warten Sie einen Moment. und bei einem gesperrten Mandanten Dieses Konto ist gesperrt. Bitte schreiben Sie an mail@xicbot.de. Mehr zu Sitzungen und zweitem Faktor unter Anmelden und Zugang und Konto und Sicherheit.

Passwort zurücksetzen

Der Link führt auf https://app.xicbot.de/kennwort/neu?token=…&sprache=de und gilt 60 Minuten. Jeder neu verschickte Link ersetzt den vorigen. Je Postfach gehen höchstens zehn Links in der Stunde hinaus, gleich aus welchem Netz sie angefordert werden; darüber bleibt die Antwort 200, es geht keine Mail hinaus, es entsteht kein neuer Link, und der zuletzt verschickte bleibt gültig. Mit 429 antworten nur die beiden Grenzen je Herkunft: die für Adresse und Herkunft zusammen (3 je Stunde; sie zählt jede Anforderung, gleich ob es das Konto gibt) mit too_many_attempts und retry_in, die für die Herkunft allein (20 je Stunde) mit dem Kopf Retry-After. In der App heißen Einstieg und Schaltfläche Passwort vergessen? und Link anfordern.

Betriebszustand und Änderungsprotokoll

Kontaktanfrage

Demo

Maßgeblich ist der Host der Adresse: klein geschrieben, ohne www. und ohne den Standardport des Schemas. https://www.example.com/kontakt und https://example.com/ ergeben also dieselbe Demo für example.com; ein abweichender Port bleibt Teil des Hosts. Läuft für diesen Host schon eine aktive Demo, bekommen Sie diese mit existing: true zurück; es wird keine neue angelegt und nichts auf die Tagesgrenze angerechnet. Das Widget der Demo ist auf den Host ohne Port beschränkt.

Erklärung zur Barrierefreiheit

Einladung annehmen

Eine Einladung aus dem Team kommt als Link https://app.xicbot.de/einladung?token=…&sprache=de und gilt 168 Stunden. Das Token hat 48 Zeichen; gespeichert wird nur sein SHA-256-Wert. Wie Einladungen entstehen und welche Rolle was darf, steht unter Team und Rollen.

Warenkorb abholen

Stellt der Assistent im Gespräch einen Warenkorb zusammen, gibt das Warenkorbwerkzeug dem Besucher als next_url eine Adresse zu Ihrem Shop: die dort eingetragene Übergabeadresse mit angehängtem ?token=…, oder &token=…, wenn die Adresse schon eine Abfrage enthält. Bis dahin liegt der Warenkorb bei XICBOT. Im Widget erscheint dazu der Link Weiter, der next_url in einem neuen Tab öffnet. Ihr Shop liest mit dem Token den Warenkorb ab und legt daraus seinen eigenen an. Ändert der Assistent den offenen Warenkorb, bleibt das Token gleich; stellt er den Warenkorb ganz neu zusammen, entsteht ein neuer mit neuem Token. Die Einrichtung beschreiben Katalog und Shop und Werkzeuge.

Die Frist beträgt 7 Tage ab der letzten Änderung; ändert der Assistent den Warenkorb im Gespräch, beginnt sie neu. Die Antwort enthält keine Kennung des Mandanten, des Gesprächs oder der Übergabe und nichts über den Besucher: wer das Token hat, hat den Warenkorb, nicht das Gespräch.

curl https://app.xicbot.de/api/v1/cart/pickup/<token> \
  -H 'Accept: application/json'

Häufige Fragen