Katalog, Warenkorb und Shopanbindung

Der Katalog ist die Liste der Produkte, die Ihr Assistent kennt: Was dort nicht steht, nennt er nicht. Sie pflegen ihn von Hand, führen ihn als JSON-Liste ein oder lassen ihn aus einem angebundenen Shop abgleichen. Aus dem Katalog holt das Werkzeug Im Katalog suchen Produkte, die im Gespräch als Karten erscheinen, und das Werkzeug Warenkorb übergeben stellt einen Warenkorb zusammen, den Ihr Shop über eine Abholmarke abholt. Diese Seite beschreibt Katalog, Shopanbindung, beide Werkzeuge und die Abholung mit ihren Feldern, Grenzen und Meldungen.

Wo Sie was finden

Der Katalog liegt in der App in der Gruppe Auslöser unter Werkzeuge (app.xicbot.de/werkzeuge), Reiter Katalog. Oben steht der Satz „Was der Assistent nennen darf. Was hier nicht steht, kennt er nicht.“, darunter der Kasten Shopanbindung, die Liste Produkte, das Formular Produkt anlegen und der Kasten Einfuhr. Die Werkzeuge Im Katalog suchen und Warenkorb übergeben legen Sie ebenfalls unter Werkzeuge an, wie unter Werkzeuge beschrieben. Übergebene Warenkörbe finden Sie unter Vorgänge im Reiter Warenkörbe, siehe Termine und Vorgänge.

Rollen und Paket

Mit der Rolle Lesen ist das Produktformular gesperrt, und es erscheint: „Mit der Rolle Lesen lässt sich hier nur ansehen. Ändern kann, wer mindestens die Rolle Bearbeiten hat.“ Statt Bearbeiten steht an jedem Produkt Ansehen, der Kasten Einfuhr fehlt. Ist noch kein Shop angebunden, sehen Nutzer unterhalb der Verwaltung den Satz „Einen Shop anbinden können Administratoren dieses Kontos.“ Welche Rolle was darf, steht unter Team und Rollen.

Produktfelder

Ein Produkt legen Sie mit Produkt anlegen an, ein vorhandenes öffnen Sie mit Bearbeiten. Bearbeiten rollt das Formular in Sicht und setzt den Fokus auf seine Überschrift „Bearbeiten: …“ mit dem Titel. Gespeichert wird mit Speichern („Wird gespeichert …“); danach ist das Formular leer, neben dem Knopf steht „Gespeichert: …“ mit dem Titel, und der Fokus steht am Knopf Bearbeiten des Produkts in der Liste. Abbrechen verwirft die Eingaben und bringt den Fokus dorthin zurück.

Produkte ansehen, ändern und löschen

• Die Liste Produkte ist nach Titel sortiert und zeigt je Produkt Titel, Kennung und Preis, ohne Preis einen Strich. Bei einem nicht verfügbaren Produkt folgt der Zusatz „· nicht verfügbar“.
• Ein Produkt aus dem angebundenen Shop trägt zusätzlich „aus dem Shop · Abgleich …“ mit Datum und Uhrzeit seines letzten Abgleichs.
• Darüber steht die Gesamtzahl als „im Katalog: …“, während einer Suche „… Treffer von … im Katalog“, dazu der gezeigte Ausschnitt, etwa „1–50 gezeigt“. Je Seite stehen 50 Produkte; bei mehr blättern Zurück und Weiter mit „Seite 1 / 10“.
• Das Suchfeld nimmt bis zu 120 Zeichen und findet Produkte, deren Titel oder Kennung mit dem eingegebenen Text beginnt; das sagt auch der Hinweis unter dem Feld. Eine neue Suche beginnt auf Seite 1.
• Während des Ladens steht „Wird geladen …“. Scheitert der Abruf, erscheint „Die Liste konnte nicht geladen werden.“ mit dem Knopf Erneut laden; ein leerer Katalog zeigt „Der Katalog ist leer.“, eine Suche ohne Treffer „Kein Produkt, dessen Titel oder Kennung mit „…“ beginnt.“
• Löschen fragt „Dieses Produkt aus dem Katalog löschen?“ mit Löschen und Abbrechen; danach steht „Das Produkt ist gelöscht.“ unter der Überschrift der Liste, und die Seite lädt neu, sodass das nächste Produkt nachrückt.
• Ist ein Produkt inzwischen gelöscht, etwa in einem anderen Fenster, meldet die Seite beim Speichern oder Löschen „Diesen Eintrag gibt es nicht mehr. Laden Sie die Seite neu, um den aktuellen Stand zu sehen.“
• Eine schon vergebene Kennung lehnt das Formular mit „Diese Kennung gibt es im Katalog schon.“ ab.

Einfuhr

Der Kasten Einfuhr nimmt eine Liste im JSON-Format entgegen: „Eine Liste im JSON-Format, höchstens 500 Zeilen je Lauf. Vorhandene Kennungen werden aktualisiert, nicht verdoppelt. Trägt ein Eintrag die Kennung eines Produkts aus dem Shop, überschreibt der nächste Abgleich dessen abgeglichene Angaben.“ Sie fügen die Liste in das Textfeld ein und klicken Einfuhr starten. Jeder Eintrag ist ein Produkt mit den Feldnamen der Tabelle unten.

[
  {
    "external_id": "TASSE-01",
    "title": "Kaffeetasse Steingut",
    "price_cents": 1490,
    "list_price_cents": 1890,
    "currency": "EUR",
    "image_url": "https://shop.example.com/bilder/tasse-01.jpg",
    "product_url": "https://shop.example.com/tasse-01",
    "is_available": true,
    "rating_tenths": 45,
    "rating_count": 12,
    "delivery_days": 2,
    "features": ["spülmaschinenfest", "300 ml"],
    "accessories": ["UNTERSETZER-01"],
    "action": "product"
  }
]

• Ein Lauf nimmt mindestens einen und höchstens 500 Einträge. Größere Kataloge teilen Sie auf mehrere Läufe auf.
• Alles oder nichts: Ist ein einziger Eintrag ungültig, schreibt der Lauf keinen.
• Eine vorhandene Kennung wird aktualisiert, eine neue angelegt. Danach meldet der Kasten neben dem Knopf zum Beispiel „neu: 3, geändert: 12, im Katalog: 240“.
• Ist die Eingabe kein JSON oder keine Liste, erscheint „Die Eingabe ist kein gültiges JSON.“, und es wird nichts gesendet.
• Einfuhr, Anlegen und Ändern von Produkten sowie Speichern, Prüfen und Abgleichen der Shopanbindung teilen sich eine Grenze von 20 Aufrufen je Minute und angemeldetem Nutzer.

Shopanbindung

Statt den Katalog zu pflegen, können Sie einen Shop anbinden, dessen Verkaufskanal eine Store API mit Zugriffsschlüssel anbietet. Der Katalog wird dann stündlich abgeglichen, und bei jeder Produktsuche liest der Assistent Preis und Verfügbarkeit im Shop nach. Die Anbindung liest nur: In den Shop wird nichts geschrieben. Im Shop selbst installieren Sie dafür nichts; es genügen Adresse und Zugriffsschlüssel des Verkaufskanals. Das Widget kommt wie auf jede andere Website mit dem Einbaucode in den Shop, siehe Widget einbauen.

Anbindung einrichten

1. 1

   Schritt 1

   Schlüssel besorgen

   Den Zugriffsschlüssel finden Sie in Ihrer Shopverwaltung beim Verkaufskanal, den der Assistent lesen soll.

2. 2

   Schritt 2

   Eintragen und speichern

   Tragen Sie Shopadresse und Zugriffsschlüssel ein und klicken Sie Speichern. Das Schlüsselfeld bleibt danach leer; angezeigt wird nur noch „…“ mit den letzten vier Zeichen.

3. 3

   Schritt 3

   Verbindung prüfen

   Verbindung prüfen („Wird geprüft“) liest die Währung und einen Artikel, mit einer Frist von 5 Sekunden. Erfolg meldet „Die Verbindung steht. Der Shop rechnet in …“, ein leerer Verkaufskanal „Die Verbindung steht (…), der Verkaufskanal zeigt aber keine Artikel.“ Mehr als drei Prüfungen je Minute und Konto lehnt der Server ab.

4. 4

   Schritt 4

   Ersten Abgleich starten

   Jetzt abgleichen reiht einen Abgleich ein: „Der Abgleich ist eingereiht.“ oder, wenn schon einer wartet, „Ein Abgleich wartet bereits.“ Die Anzeige fragt danach alle 3 Sekunden nach, bis zu 100 Mal, und lädt die Produktliste neu.

Anzeige der Anbindung

Mit der Rolle Verwaltung stehen darunter die Knöpfe Jetzt abgleichen (gesperrt, solange ein Abgleich läuft oder die Anbindung pausiert ist), Verbindung prüfen, Bearbeiten und Anbindung lösen. Konnte der Stand nicht geladen werden, erscheint „Der Stand konnte nicht geladen werden.“ mit Erneut laden; ohne Anbindung steht „Es ist noch kein Shop angebunden.“

Was der Abgleich tut

• Der Abgleich wird stündlich zur 41. Minute für jede eingeschaltete Anbindung eines aktiven Kontos eingereiht, dessen Paket die Shopanbindung enthält. Ein wartender oder laufender Abgleich wird nicht verdoppelt, ein Abgleich von Hand wird vorgezogen.
• Von Hand geht es höchstens alle 15 Minuten; der regelmäßige Abgleich läuft davon unabhängig weiter.
• Gelesen wird in Seiten zu 100 Artikeln, höchstens 100 Seiten, also bis zu 10000 Artikel. Hat der Shop mehr, gilt der Lauf als unvollständig: Gelesenes wird übernommen, Fehlendes nicht zurückgenommen.
• Jede Anfrage an den Shop hat 20 Sekunden Zeit, der ganze Abgleich 300 Sekunden. Weiterleitungen folgt der Abgleich nicht.
• Artikel mit Varianten zählen als Behälter und werden übersprungen; jede Variante kommt als eigenes Produkt, ihr Titel trägt die Ausprägung in Klammern.
• Zugeordnet wird über die Shopkennung. Ein Produkt ohne Shopbezug, dessen Kennung der Artikelnummer eines Shopartikels entspricht, wird übernommen und gehört ab dann dem Abgleich; so verdoppelt der erste Abgleich einen eingeführten Katalog nicht.
• Produkte ohne Shopbezug, deren Nummer der Shop nicht führt, bleiben unberührt.
• Nur nach einem Lauf, der alle Seiten des Shops gelesen hat, werden Shopartikel, die nicht mehr kamen, als zurückgenommen auf nicht verfügbar gesetzt. Gelöscht wird dabei nichts.
• Scheitert der Abgleich, bleibt der bisherige Katalog unverändert. Liefert der Shop keinen Artikel, obwohl er bisher welche hatte, bleibt der Katalog ebenfalls unverändert.

Meldungen der Anbindung

Preise und Verfügbarkeit aus dem Shop

Ist ein Shop angebunden und eingeschaltet und enthält Ihr Paket die Shopanbindung, liest der Assistent bei jeder Produktsuche und jeder Änderung am Warenkorb Preis und Verfügbarkeit der Artikel, die aus dem Shop stammen, dort nach; für die Karten der Produktsuche auch Streichpreis und Lieferzeit. Dafür hat der Shop 3 Sekunden Zeit, der Verbindungsaufbau 2 Sekunden. Geschrieben wird dabei nichts, weder in den Shop noch in den Katalog.

Produktsuche im Gespräch

Das Werkzeug Im Katalog suchen legen Sie unter Werkzeuge an. Es liest nur; ohne Bestätigung läuft es, wenn seine Freigabe auf ohne Rückfrage steht. Das Formular schlägt für ein neues Werkzeug mit Bestätigung vor. Der Assistent übergibt einen Suchbegriff, Kennungen aus einer früheren Suche oder beides, dazu eine von vier Formen und die Zahl der Treffer. In der Vorschau steht „Im Katalog suchen nach: …“, in einem englischen Gespräch „Search catalog for: …“.

• Genannte Kennungen stehen vorn, Treffer zum Suchbegriff füllen danach bis zur gewünschten Zahl auf. Ohne Begriff und ohne Kennung wird nicht gesucht; der Assistent erhält „Ohne Suchbegriff kann nicht gesucht werden.“
• Gesucht wird im Titel und in der Beschreibung.
• Gefunden werden nur Produkte, die auf Verfügbar stehen. Eine Kennung, die nicht im Katalog steht, taucht in keiner Form auf, auch nicht als Zubehör.
• Findet sich nichts, zeigt das Widget keine Karte, und der Assistent erhält den Hinweis „Im Katalog steht dazu nichts. Erfinde kein Produkt und keinen Preis.“
• Den Lagerbestand eines Artikels liest ein eigenes Werkzeug, Lagerbestand lesen aus dem Werkzeugbausatz; auch es liest nur und läuft ohne Bestätigung, wenn seine Freigabe auf ohne Rückfrage steht.

Produktkarten

Warenkorb im Gespräch

Das Werkzeug Warenkorb übergeben stellt im Gespräch einen Warenkorb zusammen. Jeder Aufruf ändert etwas und braucht darum die Bestätigung des Besuchers: Das Widget zeigt den Vorschlag mit Bestätigen und Ablehnen. Ein Vorschlag, der 60 Minuten unbestätigt bleibt, verfällt; danach steht „Dieser Vorschlag wurde nicht rechtzeitig bestätigt und darum nicht ausgeführt. Fragen Sie einfach noch einmal.“ Wie Bestätigungen im Gespräch ablaufen, steht unter Gespräch im Widget.

• Ein Posten fasst 1 bis 99 Stück; mehr wird auf 99 begrenzt.
• Jeder Posten braucht eine Kennung aus dem Katalog. Jede Änderung rechnet den ganzen Warenkorb neu gegen den Katalog, mit angebundenem Shop gegen die Preise, die der Shop gerade nennt.
• Ein Artikel, den der Shop gerade nicht als lieferbar führt, kommt nicht in den Warenkorb; der Assistent erfährt, welcher es war.
• Alle Änderungen nach set schreiben in denselben Warenkorb, die Abholmarke bleibt dieselbe.
• Wird derselbe bestätigte Aufruf ein zweites Mal ausgeführt, ändert sich der Warenkorb nicht noch einmal.
• Das Widget zeigt nach jeder Änderung die Posten, Zwischensumme (nur wenn sie von der Summe abweicht), Gutschein (nur mit Rabatt), Versand („kostenlos“ bei 0), Summe, den Betrag bis zum kostenlosen Versand und, bei einer Übergabeadresse mit http:// oder https://, den Knopf Weiter.

Übergabe an den Shop

1. 1

   Schritt 1

   Adresse hinterlegen

   Tragen Sie beim Werkzeug Warenkorb übergeben die Adresse für die Warenkorbübergabe ein: die Adresse einer Seite Ihres Shops, etwa https://shop.example.com/warenkorb, höchstens 500 Zeichen.

2. 2

   Schritt 2

   Besucher klickt Weiter

   Der Knopf Weiter öffnet diese Adresse in einem neuen Tab und hängt token= mit der Abholmarke an, mit ? oder, wenn die Adresse schon eine Abfrage hat, mit &. Die Marke besteht aus 40 zufälligen Buchstaben und Ziffern. Ohne hinterlegte Adresse oder bei einer Adresse, die nicht mit http:// oder https:// beginnt, zeigt das Widget keinen Knopf.

3. 3

   Schritt 3

   Shop holt den Warenkorb ab

   Ihre Seite ruft mit der Marke GET /api/v1/cart/pickup/{token} auf und legt die Posten in den eigenen Warenkorb. Die Abholung liest nur; innerhalb der Frist kann Ihre Seite sie wiederholen.

Mehr zu Wegen ohne Anmeldung steht unter Öffentliche Wege der API.

Versand und Gutscheine

Im Werkzeug Warenkorb übergeben legen Sie im Abschnitt Versand und Gutscheine fest, womit der Assistent im Warenkorb rechnet: „Damit rechnet der Assistent im Warenkorb. Ob ein Shop einen Rabatt später übernimmt, entscheidet der Shop.“

• Höchstens 20 Gutscheincodes je Werkzeug; mit Gutschein hinzufügen und Gutschein entfernen pflegen Sie die Liste. Ein neuer Eintrag beginnt mit Prozent, Wert 10, Mindestwert 0 und eingeschaltetem Aktiv. Ohne Eintrag steht „Noch kein Gutscheincode hinterlegt.“
• Ein Warenkorb trägt höchstens einen Gutschein. Trägt ein Gutschein nach einer Änderung nicht mehr, etwa weil der Mindestwert unterschritten ist, fällt er weg, und der Assistent erhält den Grund aus der Tabelle unten.
• Das Widget zeigt Beträge in der Währung des Warenkorbs, derzeit EUR; die Meldungen an den Assistenten schreiben sie mit Komma vor den Cent, Tausenderpunkt und nachgestelltem Eurozeichen.

Schnittstelle

Alle Wege unter /api/v1/catalog verlangen eine Anmeldung mit bestätigter E-Mail-Adresse und ein Paket mit Shopanbindung. Die schreibenden Wege außer den beiden Löschwegen teilen sich eine Grenze von 20 Aufrufen je Minute und angemeldetem Nutzer. Anmeldung und Schlüssel beschreibt API-Integration, die Grenzen API-Grenzen.

Häufige Fragen