Shop-Anbindung (Shopware 6)

# Voraussetzungen

• Shopware 6, für Bestellstatus und Bestellimport ab Version 6.4. Den Kasten „Shop-API (Shopware 6)“ zeigen die Website-Einstellungen, sobald der Scan den Shop als Shopware 6 erkannt hat. Shopware 5 lässt sich nicht anbinden.
• Eine bestätigte Domain: Zugangsdaten gehen nur an eine Website, deren Besitz nachgewiesen ist.
• Der Business-Tarif für den Bestellimport, wie für die übrigen E-Commerce-Auswertungen. Name, Firma und Kundennummer speichert XICTRAQ nur, wenn der Tarif die Kundenzuordnung enthält; auch sie gehört zum Business-Tarif.
• Die Rolle Inhaber, Admin oder Editor für die Website: Verbinden, Prüfen und Trennen schicken Anfragen an den Shop. Lesen darf jede Rolle, die die Website sieht.
• Eine Admin-API, die per https unter der Adresse des Shops erreichbar ist. Liegt sie auf einer Subdomain oder in einem Unterverzeichnis, tragen Sie die API-Adresse eigens ein; sie muss zur Domain der Website gehören.

# Einrichtung

Die Anbindung braucht in Shopware eine Integration und für Bestellstatus und Bestellimport eine Rolle mit reinen Leserechten. Administratorrechte braucht die Integration in keinem Fall.

1. 1
   Integration anlegen

   In der Shopware-Administration unter Einstellungen › System › Integrationen eine neue Integration anlegen, ohne Administratorrechte. Access Key ID (beginnt mit SWIA) und Secret Access Key notieren.
2. 2
   Rolle mit acht Leserechten anlegen

   Unter Einstellungen › System › Benutzer & Rechte eine neue Rolle anlegen und unter „Detaillierte Privilegien“ für genau die acht Einträge der Tabelle unten nur „Lesen“ setzen. Für den Patchstand allein ist keine Rolle nötig.
3. 3
   Rolle der Integration zuweisen

   Unter Einstellungen › System › Integrationen die Integration öffnen und ihr die neue Rolle geben.
4. 4
   In XICTRAQ verbinden

   Website › Einstellungen › Shop-API (Shopware 6): Access Key ID und Secret Access Key eintragen, bei Bedarf die API-Adresse, den Schalter „Bestellungen importieren“ einschalten und auf „Verbinden“ klicken. XICTRAQ meldet sich sofort beim Shop an, prüft die Rechte mit einer Probeanfrage und nennt fehlende Einträge. Gespeichert wird nur ein Zugang, den der Shop angenommen hat.

# Die acht Leserechte

Jeder Eintrag jeweils nur mit „Lesen“. Das Recht sales_channel fehlt bewusst: die Kennung des Verkaufskanals steht an der Bestellung, seinen Namen braucht der Import nicht.

Nur für den Bestellstatus im Bestellverlauf, ohne Import, genügen vier dieser Rechte: order, order_transaction, order_delivery und state_machine_state. Dann liest XICTRAQ einmal täglich nur Bestellnummer und die drei Status der vom Tracker erfassten Käufe der letzten 30 Tage, bis zu 1000 je Tag; sind es mehr, kommen sie reihum dran, der älteste Stand zuerst.

# Datenfluss

# Zählregeln

• Eine Bestellung zählt einmal: mit dem Kauf des Trackers, wenn es ihn gibt, sonst mit der Importzeile.
• Importzeilen zählen in Umsatz, Bestellungen, Durchschnittsbestellwert, Finanzen, Bestellverlauf, Kunden, Produkten, Zahlungs- und Versandarten sowie in Wochen- und Monatsberichten. In Conversion-Rate, Funnel und ROAS zählen sie nicht, weil ihnen kein Besuch zugrunde liegt. Bei den Umsatzquellen stehen sie als „Ohne Besuch (Shop)“.
• Eine im Shop stornierte Bestellung bekommt keine Importzeile; eine vorhandene fällt beim nächsten Abgleich weg.
• Eine Online-Bestellung, deren jüngste Zahlung fehlgeschlagen oder abgebrochen ist, zählt nicht: der Kunde hat nicht bezahlt und die Bestätigungsseite nicht gesehen. Zahlt er später, kommt sie mit dem neuen Zahlungsversuch zurück. Für Bestellungen aus dem Shop-Admin gilt diese Sperre nicht.
• Eine ganz erstattete Bestellung aus dem Import (Zahlungsstatus refunded) bekommt zusätzlich eine Erstattung über den Bestellbetrag zum Zeitpunkt der Erstattung. Ist ein vom Tracker erfasster Kauf laut Shop ganz erstattet und hat der Tracker keine Erstattung gemeldet, legt der Import die Erstattung ebenfalls an. Beides gilt nicht für stornierte Bestellungen: sie bekommen keine Erstattungszeile, und wird eine erstattete Bestellung später storniert, fällt ihre Erstattungszeile beim nächsten Abgleich weg. Teilerstattungen, Rücksendungen und Rückbuchungen aus dem Import stehen in der Shop-Übersicht, mindern den Umsatz aber nicht.
• Der Kauf des Trackers zu einer Bestellung, die im Shop später storniert wurde, zählt in der Vorgabe weiter im Umsatz; die Shop-Übersicht weist diese Fälle bei den Stornos getrennt aus. Mit „Stornos: ohne“ rechnet XICTRAQ sie heraus, siehe Abschnitt Stornos.

# Stornos

In der Vorgabe bleiben die Zahlen so, wie der Tracker sie gemessen hat: ein erfasster Kauf zählt, auch wenn die Bestellung im Shop später storniert wird. XICTRAQ kennzeichnet solche Käufe und rechnet sie auf Wunsch heraus.

• Woran XICTRAQ einen Storno erkennt: am Bestellstatus cancelled der Bestellung, die der Bestellimport dem Kauf zugeordnet hat; hat er keine zugeordnet, am Bestellstatus, den der Bestellstatus-Abruf zuletzt aus dem Shop gelesen hat. Ist beides ausgeschaltet, kennt XICTRAQ keinen Storno, und alle Käufe zählen.
• Kennzeichen: Käufe, deren Bestellung im Shop storniert ist, tragen im Bestellverlauf, bei den letzten Bestellungen und in der Zeitleiste eines Besuchers das Kennzeichen „Im Shop storniert“. Die Kachel „Im Shop storniert“ im Bestellverlauf nennt, wie viele es im Zeitraum sind.
• Umschalter: „Stornos: mit“ ist die Vorgabe. „Stornos: ohne“ im E-Commerce-Reiter rechnet diese Käufe aus Umsatz, Bestellungen und den übrigen Kennzahlen heraus, eine Erstattung zu derselben Bestellung ebenso; Umsatz- und Bestellkarten im Dashboard haben dafür die Einstellung „Stornos herausrechnen“. Funnel und Abbruchquote ändert der Umschalter nicht: sie zählen Besuche, die die Bestätigungsseite erreicht haben. Per API heißt der Schalter exclude_cancelled=1, die Antwort trägt dann cancelled_excluded.
• Importzeilen betrifft der Umschalter nicht: eine im Shop stornierte Bestellung bekommt ohnehin keine.
• Die Umsatz-Übersicht zählt auch den Umsatz, den der Tracker beim Kauf am Seitenaufruf vermerkt. Dieser Vermerk trägt keine Bestellnummer; mit „Stornos: ohne“ entfällt er für jede Sitzung mit einem Kauf zu einer stornierten Bestellung. Kauft eine Sitzung mehrmals und ist nur eine Bestellung storniert, entfällt der Vermerk auch für ihre übrigen Bestellungen.

# Was die Shopdaten zeigen

Aus den importierten Bestellungen rechnet XICTRAQ eine Shop-Übersicht je Website und Zeitraum. In der App stehen die Werte als Karten zur Wahl (Karten-Picker › Analytics · E-Commerce › Shop-Bestellungen (Import)), per API unter GET /websites/:id/shop/summary. Beträge stehen in Cent.

• Herkunft: Bestellungen und Umsatz aus dem Tracker, aus dem Import und davon aus dem Shop-Admin, jeweils mit dem Vorzeitraum.
• Bestell-, Zahlungs- und Versandstatus nach den technischen Namen aus Shopware, mit Bestellungen und Umsatz je Status.
• Stornos mit Quote und den Tracker-Käufen zu stornierten Bestellungen, die in der Vorgabe weiter zählen; Erstattungen, Teilerstattungen, Rücksendungen und Rückbuchungen.
• Offene Zahlungen, davon seit mehr als sieben Tagen offen, je Zahlungsart; offene Lieferungen, davon seit mehr als drei Tagen offen, sowie versendete und zurückgeschickte.
• Verkaufskanäle als „Kanal 1“, „Kanal 2“ und so weiter nach Bestellzahl, mit Anteil. Die Namen der Kanäle kennt XICTRAQ nicht, weil die Rolle das Recht sales_channel bewusst nicht hat.
• Erfassungsquote des Trackers: der Anteil der Online-Bestellungen (nicht im Shop-Admin angelegt, nicht storniert), die der Tracker auf der Bestätigungsseite erfasst hat, je Tag. Gerechnet wird ab dem ersten Tracker-Kauf der Website; davor bleibt die Quote leer. Fällt sie über drei Tage unter 80 % des eigenen 28-Tage-Werts, meldet XICTRAQ das als Hinweis.
• Wiederkäufer: Kunden, die im Zeitraum bestellt und schon vorher bei diesem Shop bestellt haben (erkannt an der Kundennummer, 365 Tage), mit deren Bestellungen und Umsatz, neben der Zahl aller Kunden im Zeitraum. Als reine Zählung ohne Namen und nur mit Kundenzuordnung im Tarif; stornierte Bestellungen zählen nicht.

# Freigabelinks

Ein Freigabelink zeigt die Kennzahlen des Shops, aber nie Kundendaten: weder Name, Firma und Kundennummer aus dem Bestellimport noch Identitäten des Trackers mit Name, Firma oder Kunden-ID. Bestellverlauf, Bestellungen, Kundenliste, identifizierte Nutzer, Zeitleiste und Besucherprofil erscheinen dort ohne diese Angaben, Downloads aus der Freigabe ebenso. Bestellungen, Umsatz und die übrigen Kennzahlen bleiben.

# Verkaufskanäle

Hat der Shop nur einen Verkaufskanal, zählen alle Bestellungen, und der Shop lässt sich nur einer Website zuordnen; eine zweite Website mit demselben Shop lehnt XICTRAQ beim Speichern ab, sonst zählte jede Bestellung doppelt. Hat er mehrere Kanäle, bedient er oft mehrere Websites. Dann zählt für eine Website nur ein Kanal, aus dem der Tracker dieser Website schon eine Bestellung gemeldet hat; Bestellungen aus anderen Kanälen speichert der Import für diese Website nicht. Kommt ein Kanal hinzu, holt eine neue Rückholung seine älteren Bestellungen nach. Für einen Shop mit mehreren Kanälen braucht der Import also den Tracker auf der jeweiligen Website. Bis zu 30 Kanäle je Website sind möglich.

# Fehlermeldungen

Der Stand des letzten Abgleichs steht in den Website-Einstellungen unter Shop-API und in der API im Feld import.error. Ein Fehler des Bestellimports berührt den Patchstand nicht.

Beim Verbinden und Speichern

# Abschalten und Löschen

• Schalter „Bestellungen importieren“ aus und speichern: XICTRAQ löscht die importierten Bestellungen mit Positionen, die Importzeilen in den Auswertungen und die Kundenidentitäten aus dem Import. Patchstand und, falls eingeschaltet, Bestellstatus laufen weiter.
• „Trennen“: Die gespeicherten Zugangsdaten und alle importierten Daten werden gelöscht, offene Alarme der Anbindung geschlossen.
• „Analytics-Daten zurücksetzen“ in den Website-Einstellungen löscht auch die importierten Bestellungen. Ist der Import eingeschaltet, holt der nächste Abgleich den Bestellverlauf von vorn aus dem Shop.
• Einzelnen Kunden löschen: Das Löschen eines Besuchers in Analytics erfasst auch Kunden aus dem Import, die über Identität oder zugeordnete Bestellung zu ihm gehören; per API nennen Sie die Kundennummer im Parameter customer_number von DELETE /websites/:id/analytics/visitor/:hash. XICTRAQ leert dann Name, Firma und Kundennummer an den importierten Bestellungen, löscht die Import-Identität und sperrt die Kundennummer, sodass spätere Abgleiche für sie keine Kundenangaben und keine Identität mehr speichern. Die Bestellungen zählen ohne Kundenbezug weiter. Löschen dürfen Inhaber und Admins der Website.
• In Shopware: Wer die Integration löscht oder ihr die Rolle entzieht, beendet den Zugang sofort; XICTRAQ meldet den Abbruch dann als Fehler der Anbindung.

# Verwandte Doku-Kapitel