Rezept: Shop-Kundenservice für WooCommerce, Shopify, Shopware und Gambio

Das Website-Widget beantwortet Bestellstatus, Rücksendung, Produktfragen, Versand und Zahlung selbst, direkt aus dem Shop. Nur lesend, Bestelldaten nur nach Prüfung von Bestellnummer + E-Mail-Adresse. Modul Shop-Postfach: Antwortentwürfe mit Bestelldaten. Komplett Self-Service.

Ein Kunde fragt im Shop-Widget „Wo ist meine Bestellung 4711?“, „Kann ich die Vase noch zurückschicken?“ oder „Gibt es die Leuchte in Weiß?“. Der Assistent (früher „Bestellstatus-Bot“) liest Status, Sendungsnummer, Rückgabefrist oder Artikeldaten direkt aus dem Shop und antwortet, auch nachts. Fragen zu Versand, Zahlung und AGB beantwortet er aus den eigenen Shop-Seiten. Mit dem Modul Shop-Postfach liegt zu jeder weitergeleiteten Kunden-Mail ein Antwortentwurf mit denselben Daten in der Inbox.

Der Shop richtet das selbst ein, ohne uns: /register?branche=shop-service (Aliase shop-kundenservice, shop-bestellstatus) → Einrichtungs-Seite /manage/shop-setup. Produkt, Preise, Trust-Modell: docs/plans/shop-service.md. Einstieg vor dem Signup: kostenloser Shop-Service-Check unter /shop-check (Wissen wird übernommen).

#Tarife

Mit laufendem Abo wechselt /manage/billing den Plan in der bestehenden Stripe-Subscription — nur bei Abo-Status active. Upgrade (höherer Preis oder anderer Zyklus): Stripe bucht die anteilige Differenz sofort ab (always_invoice); klappt die Zahlung nicht sofort, lehnt Stripe den Wechsel ab (error_if_incomplete) und der Plan bleibt. Downgrade (gleicher Zyklus, niedrigerer Preis): gilt sofort, ohne Erstattung für den laufenden Zeitraum; der neue Preis ab der nächsten Verlängerung. In beiden Fällen setzt erst der Webhook customer.subscription.updated (Abo aktiv) den Plan in der DB, bis dahin zeigt die Billing-Seite „Umstellung läuft“.

#Die Schritte (/manage/shop-setup)

Jeder Meilenstein geht einmal als Beobachtungs-Meldung an Marcus (Signup-Alarm, „Self-Service: nicht anrufen“).

#Einrichtung im Builder („Lassen Sie den Assistenten einrichten“)

Dieselben fünf Schritte führt der Builder (/manage/builder) im Chat, verlinkt oben auf /manage/shop-setup. Der Builder kennt den Stand (Setup-Flow config/setup_flows/shop_service.php, gewählt über Onboarding.branchen.shop-service.setup_flow), begrüßt mit „Schritt x von 5“, sammelt die Angaben ein und richtet alles über Tools ein. Die Seite bleibt Rückfallebene; beide zeigen denselben Stand (ShopSetupFlowProvider → ShopSetupService::steps).

• Zugangsdaten nie im Chat. requestCredentials(kind) blendet ein Formular ein (Felder aus dem Flow, nicht vom Modell); die Werte gehen per POST /manage/setup/credentials in den CredentialVault (AES, 30 min, Einmal-Token an Workspace/Nutzer/Chat gebunden) und nur an das Tool, das sie braucht — danach gelöscht. Eingefügte WooCommerce-/Shopware-/Shopify-Schlüssel (shpat_…, shpss_…) maskiert der Chat vor dem Speichern (SecretRedactor::redactKnownTokens).
• Datei-Zugang (RemoteFileAccessFactory): SFTP Port 22 (Fingerabdruck vor dem Passwort bestätigen), FTP als FTPS (21 explizit, 990 implizit, Zertifikat geprüft, PASV-IP ignoriert); unverschlüsseltes FTP nur mit plain_ftp nach Warnung. Ziel durch EgressGuard::checkHostPort (öffentliche IP, gepinnt).
• Widget automatisch nur bei WooCommerce: genau wp-content/mu-plugins/taskmonkey-widget.php (gibt nur das Skript im Footer aus), Vorschau der Datei vor dem Ja, idempotent, fremde Dateien werden nie überschrieben. Shopware 6 (Theme-Build nötig), Shopify (nur Leserechte, Zeile in theme.liquid vor </body>) und Gambio: Code-Zeile + Anleitung. Nie über die Datenbank — der Connector bleibt nur lesend.
• Gedächtnis: Fakten (System, Hoster, Ansprechpartner) über rememberFact, Entscheidungen und offene Punkte über rememberSetupNote (Abschnitt „Einrichtung“, bei jedem Chat-Start im Prompt).
• Stunden-Limits pro Workspace, Audit ohne Werte (Log setup-audit, letzte 50 Einträge im Flow-Stand).

#Was der Assistent zusätzlich kann

• Rücksendung: checkReturn nennt Frist (ab Bestelldatum), Bedingungen und Retourenlink, für eine Bestellung erst nach Prüfung. createReturnRequest meldet die Rücksendung an: Entwurf an die Bestell-E-Mail + interne Notiz (Artikel, Grund, Frist) in der Inbox, Kategorie „Rücksendung“. Nichts wird gesendet, im Shop nichts geändert. Höchstens eine Anfrage je Bestellung und Tag.
• Produktfragen: findProducts mit Preis inkl. MwSt., Verfügbarkeit (ohne Mengen), Lieferzeit, Varianten, Maße/Gewicht, Link. Nie Einkaufspreise, nur aktive/veröffentlichte Artikel.
• Shop-Seiten: getShopFaq sucht in den eingelesenen Abschnitten.
• Shop-Postfach: Agent shop_antwort mit denselben lesenden Tools, Kategorien Bestellstatus, Rücksendung, Produktfrage, Reklamation, Zahlung, Sonstiges, Spam. Ausgabe Notiz + Entwurf, senden nur per Klick.

#Was der Connector darf

Die Freigabe kommt aus App\Service\Shop\ShopConnectorPolicy und wird im Connector selbst durchgesetzt:

Schreiben ist ausgeschlossen (allow_write: false).

#WooCommerce über die REST-API (ohne Connector)

• Der Schlüssel liegt nur in der Workspace-.env (SHOP_WOO_CONSUMER_KEY/…_SECRET), die Config (shop_api.php) enthält nur den Platzhalter. Anfragen gehen nur per https und nur als GET.
• Test beim Verbinden: GET /wp-json/wc/v3/orders?per_page=1&_fields=id (keine Kundendaten). Ohne schöne Permalinks automatisch ?rest_route=/wc/v3. Ein falscher Schlüssel wird nicht gespeichert.
• „Nur lesen“ lässt sich über die WooCommerce-API nicht abfragen, und wir testen nicht mit einem Schreibversuch. Der Shop bestätigt die Berechtigung „Lesen“ per Häkchen.
• Typische Fehler: 401 (Schlüssel falsch kopiert oder Hoster entfernt den Authorization-Header), 403 (Sicherheits-Plugin/Firewall), Weiterleitung (Shop-Adresse in Schritt 1 mit/ohne www). Dann hilft der Connector-Weg.
• Ändert sich Shop-System oder Adresse in Schritt 1, wird der Schlüssel gelöscht und der Shop verbindet neu. „Schlüssel löschen“ geht zurück auf den Connector-Weg.
• Überwachung: Der 30-Minuten-Check pingt dann die REST-API statt des Connectors. Eine Mail an den Shop kommt nach 2 Fehlschlägen in Folge, höchstens eine pro Tag. Ein alter Connector kann gelöscht werden.
• Sendungsnummern kommen aus dem Meta der Plugins „Shipment Tracking“ / „Advanced Shipment Tracking“, wie beim Connector.

#Shopify über eine eigene App (ohne Connector, ohne App-Store)

Seit 01.01.2026 legt Shopify keine neuen „Custom Apps“ mehr im Shopify-Admin an; eigene Apps entstehen im Dev Dashboard. Der Shop braucht dafür nur sein Inhaber-Konto, keinen Partner-Account und keinen App-Review.

Was der Shop-Betreiber tut (so steht es auch auf /manage/shop-setup und im Builder, next.help):

1. Dev Dashboard öffnen: dev.shopify.com (auch über Shopify-Admin → Einstellungen → Apps → „Apps entwickeln“).
2. „App erstellen“, Name z. B. „TaskMonkey Kundenservice“.
3. In der App-Version bei den Admin-API-Rechten nur read_orders und read_products auswählen, empfohlen dazu read_all_orders (sonst nur Bestellungen der letzten 60 Tage) und read_legal_policies (Rückerstattungs- und Versandrichtlinie). Keine write_-Rechte. Fragt Shopify nach geschützten Kundendaten: E-Mail freigeben.
4. Version veröffentlichen, App im eigenen Shop installieren, Rechte bestätigen.
5. Client-ID und geheimen Schlüssel aus den App-Einstellungen kopieren.
6. Auf /manage/shop-setup (bzw. im Builder-Formular shopify) einfügen, zusammen mit der myshopify-Adresse (mein-shop.myshopify.com, Shopify-Admin → Einstellungen → Domains; admin.shopify.com/store/mein-shop geht auch).
7. Schritt 3 testen, Schritt 5: die Widget-Zeile selbst einfügen (Onlineshop → Themes → „…“ → Code bearbeiten → Layout/theme.liquid → direkt vor </body> → Speichern; nach einem Theme-Wechsel wiederholen).

Ältere eigene Apps aus dem Admin (vor 2026 angelegt) haben einen festen Admin-API-Token shpat_…; der geht auch (Seite: „Ältere eigene App mit Admin-API-Token?“, Builder: Formular shopify_token), wenn die App nur Leserechte hat.

Technik und Sicherheit:

• Token-Weg: Client Credentials Grant (POST https://<shop>.myshopify.com/admin/oauth/access_token, form-encoded, 24 h gültig, im Tool-Cache bis max. 55 min). Geht nur, wenn App und Shop zur selben Shopify-Organisation gehören (baut eine Agentur die App, muss sie das in der Organisation des Shops tun).
• Zugangsdaten nur in der Workspace-.env (SHOP_SHOPIFY_CLIENT_ID/…_CLIENT_SECRET bzw. SHOP_SHOPIFY_TOKEN), shop_shopify_api.php nur mit Platzhaltern. API-Version an einer Stelle: ShopSetupService::SHOPIFY_API_VERSION.
• Beim Verbinden (nur im Speicher, gespeichert erst nach Erfolg): Shop + Rechte lesen (currentAppInstallation.accessScopes), App mit write_-Rechten wird abgelehnt, read_orders und read_products sind Pflicht; zweiter Test: eine Bestell-ID samt E-Mail-Feld lesbar (sonst Hinweis auf die Freigabe geschützter Kundendaten). Die Zugangsdaten müssen zur angegebenen myshopify-Adresse gehören.
• Bestellnummer = Shopify-„name“ (#1001, mit Präfix/Suffix des Shops z. B. DE-1001). Gesucht wird nur nach der Nummer, E-Mail/PLZ prüft TaskMonkey selbst und schickt sie nie an Shopify. Die Adress-PLZ wird nur bei „E-Mail + PLZ“ angefragt.
• Rückgabe-/Versandfragen: zusätzlich die Richtlinien des Shops (getShopifyPolicies, 6 h Cache); die eigenen Texte aus Schritt 1 gehen vor. Beim Einlesen der Shop-Seiten sind /policies/… die Rückfallpfade.
• „Zugang löschen“ entfernt die Zugangsdaten bei uns; in Shopify die App deinstallieren. Ein Systemwechsel in Schritt 1 löscht den Zugang ebenfalls. Überwachung: checkShopRestConnection pingt shopShopifyPing.
• Phase 2 (nicht gebaut): öffentliche App mit OAuth über einen Partner-Account (Installation per Klick, App-Review, App-Embed für das Widget statt theme.liquid).

#Was der Bot sagt, und was nie

• Daten gibt es erst nach Prüfung: Bestellnummer + E-Mail-Adresse der Bestellung, wahlweise zusätzlich die PLZ (verify_mode: email_postcode; bei WooCommerce-HPOS über den Connector nur E-Mail). Die PLZ allein reicht seit 28.09.2026 nicht mehr (zu leicht durchzuprobieren). Die Prüfung steckt im SQL. Für „falsche Angaben“ und „diese Nummer gibt es nicht“ gibt es dieselbe Antwort.
• Fehlversuche je Stunde: höchstens 5 pro Chat, 10 pro Aufrufer-IP (pseudonym) und 100 pro Workspace. Keine Sperre pro Bestellnummer, die könnte ein Fremder für den echten Kunden auslösen.
• Nie: Preise, Adressen, Zahlungsart, interne Kommentare. Nichts zusagen (keine Kulanz, keine Stornierung), dafür verweist er auf den Kontakt.
• Andere Themen lehnt er in einem Satz ab (aufgabenbezogener Bot).
• Angezeigte Bestellstatus: siehe config/tenants/_shared/tools/shop/_README.md.

#Technik

• Tools: config/tenants/_shared/tools/shop/: getOrderStatus, getShipmentTracking und getShopInfo für das Widget, darunter je System getGambioOrder/getGambioShipment bzw. getWooOrder/getWooShipment bzw. über die REST-API getWooOrderRest/getWooShipmentRest (Quelle je Workspace: shop_status.source).
• Weitere Tools: checkReturn, createReturnRequest (Core-Handler ShopTicketTools), findProducts (getGambioProducts, getWooProducts, getWooProductsRest, getSwProducts, getShopifyProducts), getShopFaq; Shopware getSwOrder/getSwShipment über apis.shop_sw mit oauth_client_credentials; Shopify getShopifyOrder/getShopifyShipment/getShopifyPolicies über apis.shop_shopify (GraphQL, nur Queries). Shop-Seiten: ShopPageImporter + shopFetchPage.
• Vorlage: config/tenants/_template/signup/shop_service/ (Widget-Prompt, public.tools, Haiku, Postfach: channels.php, inbox/policy.php, inbox/agents/shop_antwort.php, Health-Check, Secret-Rotation).
• Tests: ShopOrderToolsTest (echtes Gateway gegen nachgebaute Gambio-/WooCommerce-DBs), ShopWooRestToolsTest (REST-API gegen Fake-Antworten), ShopwareToolsTest, ShopifyToolsTest, ShopTicketToolsTest, ShopPageImporterTest, ShopSetupServiceTest, ShopSetupControllerTest, ShopPlanTest.
• Plan und Preis: docs/plans/shop-service.md (Vorgänger docs/plans/wismo-selfservice.md).