ERP und Bestellexport

Ein ERP- oder Warenwirtschaftssystem kann eine Bestellung importieren, während der Kunde noch über sein Angebot entscheidet. Nimmt der Kunde danach an, enthält die Shopware-Bestellung den Zusatzartikel, der bereits importierte Auftrag aber nicht.

Die optionale ERP-Export-Einstellung verhindert diesen Ablauf für eine vom ERP verwendete Shopware-Integration oder ein separates Shopware-Administrationskonto. Im normalen Ablauf ist jede Bestellung automatisch für das ERP bereit: sofort, wenn kein Angebot infrage kommt, wenn ein Angebot endet, ohne die Bestellung zu ändern, oder nachdem Shopware ein angenommenes Angebot vollständig verarbeitet hat. Wird diese Verarbeitung in einem seltenen Fall nicht abgeschlossen, wartet die Bestellung auf eine Prüfung und erscheint unter Marketing → Cross-Selling & Upselling → ERP-Export. Wenn Shopwares geplante Aufgaben laufen und eine Absenderadresse des Shops hinterlegt ist, sendet die geplante Prüfung nach dem festgelegten Zeitraum eine E-Mail an die hinterlegten Empfänger.

Voraussetzung: Ihr ERP fragt erneut ab

Verwenden Sie die Einstellung nur, wenn das externe System:

• bei jedem Lauf alle noch zu importierenden Bestellungen erneut abfragt;
• eine Bestellung, die in einem früheren Lauf fehlte, beim nächsten Lauf normal importiert;
• eine fehlende Bestellung nicht als gelöscht oder storniert wertet;
• entweder eine eigene Shopware-Integration oder ein separates Shopware-Administrationskonto verwendet, dessen Zugangsdaten nicht mit anderen Systemen geteilt werden.

Ein Import, der nur Bestellungen abfragt, die neuer als die zuletzt importierte Bestellung sind, kann wartende Bestellungen dauerhaft verpassen und ist nicht kompatibel.

Einrichtung

1. Verwendet das ERP Integrations-Zugangsdaten, legen Sie unter Einstellungen → System → Integrationen eine Integration an, die ausschließlich das ERP verwendet. Meldet sich das ERP mit Benutzernamen und Passwort an, legen Sie stattdessen unter Einstellungen → System → Benutzer & Berechtigungen ein separates Administrationskonto an. Verwenden Sie kein gemeinsam genutztes Konto.
2. Öffnen Sie Erweiterungen → Meine Erweiterungen, suchen Sie Cross-Selling & Upselling nach dem Kauf, öffnen Sie das Menü … und wählen Sie Konfigurieren.
3. Wählen Sie oben Alle Verkaufskanäle oder den gewünschten Verkaufskanal und konfigurieren Sie im Bereich ERP-Export:

• Bestellung erst importieren lassen, wenn sie für das ERP bereit ist (Standard: Aus): Wenn die Einstellung aus ist, kann das ERP jede neue Bestellung wie gewohnt importieren. Wenn sie an ist, ist eine Bestellung, für die kein Angebot infrage kommt, sofort bereit. Kommt ein Angebot infrage, ist die Bestellung bereit, wenn es endet, ohne die Bestellung zu ändern, oder nachdem Shopware das angenommene Angebot vollständig verarbeitet hat, indem der Zusatzartikel hinzugefügt und eine etwaige Zahlung des Zusatzbetrags erfasst wurde.
• Integration, mit der das ERP Bestellungen importiert (Standard: keine): Bestimmt eine Integration, deren direkte Bestellabfragen warten. Lassen Sie das Feld leer, wenn das ERP stattdessen ein separates Administrationskonto verwendet.
• Benutzerkonto, mit dem das ERP Bestellungen importiert (Standard: keines): Wählen Sie das separate Administrationskonto, mit dem sich das ERP mit Benutzernamen und Passwort anmeldet. Solange eine Bestellung wartet, findet dieses Konto sie weder in Bestellabfragen noch im Bestellmodul der Administration. Lassen Sie das Feld leer, wenn das ERP eine Integration verwendet. Sind beide Zugangsdaten ausgewählt, warten beide.
• E-Mail, wenn eine Bestellung mit angenommenem Angebot nicht für das ERP bereit wird (Standard: leer): Sendet eine E-Mail an die hinterlegten Empfänger, wenn die Verarbeitung eines angenommenen Angebots in einem seltenen Fall nicht bis zum voraussichtlichen Zeitpunkt abgeschlossen ist. Offene Angebote lösen diese E-Mail nicht aus. Geben Sie eine Adresse pro Zeile ein. Lassen Sie das Feld leer, um keine E-Mail zu senden; betroffene Bestellungen erscheinen weiterhin im Tab ERP-Export.
• Schwellenwert für Überfälligkeitsbenachrichtigung (Minuten) (Standard: 15): Anzahl der Minuten, nach denen Shopware die hinterlegten Empfänger über ein angenommenes Angebot informiert, dessen Verarbeitung noch geprüft werden muss. Die E-Mail wird nicht vor dem voraussichtlichen Zeitpunkt unter ERP-Export gesendet. Bei Werten von 0 oder weniger gelten 15 Minuten; bei Werten über 1.440 gelten 1.440 Minuten (ein Tag).

Die Werte können global gelten und je Verkaufskanal überschrieben werden. Ein Verkaufskanal kann die globalen Werte erben. Jede wirksame Verkaufskanal-Konfiguration gilt für eine Integration und/oder ein Benutzerkonto, nicht für eine Liste von Zugangsdaten. Sind beide konfiguriert, warten beide.

Alles, was dieselben Zugangsdaten verwendet, erhält dieselbe gefilterte Bestellansicht. Verwenden Sie deshalb keine gemeinsam genutzte Integration.

Eine Änderung des ERP-Schalters, der ausgewählten Integration oder des ausgewählten Benutzerkontos beendet laufende Angebote in den betroffenen Verkaufskanälen, bevor die neue Einstellung gilt.

Ablauf

Die Erweiterung verwendet dafür keinen anderen Bestellstatus. Andere Benutzer der Administration und alle anderen API-Zugangsdaten können weiterhin auf die Bestellung zugreifen; das ausgewählte ERP-Benutzerkonto kann dies während der Wartezeit nicht. Bei einem ungenutzten Angebot wartet die Bestellung bis zum Ablauf der Gültigkeit des Angebots-Links. Wurde bereits eine Zahlungsbestätigung begonnen, endet das Warten erst nach Ablauf dieses Bestätigungszeitraums. Bei einem angenommenen Angebot ist die Bestellung bereit, sobald die Verarbeitung abgeschlossen ist. Das ERP importiert die bereite Bestellung beim nächsten Lauf.

Nimmt der Kunde ein Angebot mit Rabatt an, enthält die Bestellung eine eigene Rabattposition. Damit Ihr ERP diese Position zuordnen kann, geben Sie ihr in den globalen Einstellungen eine Produktnummer (Produktnummer für die Rabattposition).

Abgedeckte API-Abfragen

Das Warten gilt für direkte Lesezugriffe auf die Admin-API-Entität order:

• Liste, Detail, Suche und Suche nach IDs;
• Aggregationen;
• Assoziationspfade, deren letzte abgefragte Entität order ist.

Schreibzugriffe werden nicht gefiltert, damit das ERP nach dem Import seinen normalen Statuswechsel ausführen kann.

Nicht abgedeckt sind insbesondere:

• Bestellungen, die nur eingebettet unter einer anderen Hauptentität zurückgegeben werden, etwa ein Kunde samt Bestellungen;
• Sync API, Store API, Flow-Builder- oder Webhook-Nachrichten;
• eigene Endpunkte, direkte SQL-Abfragen oder ein Export, der andere Zugangsdaten verwendet.

Prüfen Sie deshalb den tatsächlichen Endpunkt und die Zugangsdaten Ihres Systems. Die Einstellung gilt nur für die aufgeführten Lesezugriffe der Admin API.

Änderungen an der Konfiguration

Eine Änderung des ERP-Schalters, der ausgewählten Integration oder des ausgewählten Benutzerkontos bildet eine feste Grenze. Bevor die neue Konfiguration gilt, beendet die Erweiterung offene Angebote in der betroffenen globalen Einstellung oder im betroffenen Verkaufskanal. So kann ein Angebot aus der alten Konfiguration die Bestellung nicht später noch ändern.

Wird ein angenommenes Angebot noch verarbeitet, lehnt Shopware die Konfigurationsänderung ab. Warten Sie, bis die aktuelle Bestelländerung abgeschlossen ist, und speichern Sie erneut. Erscheint die Meldung erneut, öffnen Sie Marketing → Cross-Selling & Upselling → ERP-Export und prüfen Sie die betroffene Bestellung. Geben Sie sie erst für den Import frei, wenn Bestellpositionen und Gesamtsumme zum endgültigen Zahlungs- oder Erstattungsergebnis passen, und speichern Sie danach die Konfiguration erneut. Auch eine Deaktivierung der Erweiterung wird in diesem Fall gestoppt.

Bestellungen, die vor dem Aktivieren der Einstellung eingegangen sind, beginnen nicht nachträglich zu warten. Beim Aktivieren werden noch offene alte Angebote in den betroffenen Verkaufskanälen beendet, damit sie eine bereits bereite Bestellung nicht später ändern können.

Wenn eine Bestellabfrage fehlschlägt

Die Wartebedingung ist Teil derselben Datenbankabfrage, die die Bestellung liest. Kann diese Abfrage wegen eines Datenbank-, Schema- oder Abfragefehlers nicht sicher ausgeführt werden, schlägt der aktuelle API-Abruf fehl. Die Erweiterung wiederholt ihn nicht ohne die Bedingung und liefert keine ungefilterte Ersatzantwort.

Beheben Sie die Ursache und lassen Sie das ERP seinen normalen vollständigen Lauf wiederholen. Umgehen Sie den fehlgeschlagenen Abruf nicht mit anderen Zugangsdaten oder durch Abschalten der Einstellung; für diese Wege gilt die Prüfung der Importbereitschaft nicht.

ERP-Export, Benachrichtigungen und Prüfung

Unter Marketing → Cross-Selling & Upselling → ERP-Export sehen berechtigte Benutzer wartende und bereite Bestellungen mit ihrem Stand, dem Verkaufskanal, dem voraussichtlichen Zeitpunkt und dem E-Mail-Status. Ansicht und Für den Import freigeben sind getrennte Rollenberechtigungen.

Die geplante Prüfung läuft alle fünf Minuten (cwk_ppu.export_gate_overdue_notification). Wird die Verarbeitung eines angenommenen Angebots in einem seltenen Fall nicht nach dem konfigurierten Zeitraum und dem voraussichtlichen Zeitpunkt abgeschlossen, sendet Shopware eine E-Mail an die für den Verkaufskanal hinterlegten Empfänger. Der erfolgreiche Versand wird vermerkt; bei einem Fehler versucht Shopware den Versand beim nächsten Lauf erneut. Offene Angebote lösen diese E-Mail nicht aus.

Shopware kann diese Prüfung über den Admin Worker ausführen, solange ein Administrator angemeldet ist, oder über eigene Worker für geplante Aufgaben und die Message Queue. Eigene Worker werden empfohlen, damit die Prüfung auch nachts und am Wochenende zuverlässig läuft.

Unter Marketing → Cross-Selling & Upselling → Status meldet die Erweiterung:

• eine aktivierte Konfiguration ohne vorhandene API-Integration oder ohne vorhandenes Benutzerkonto;
• angenommene Angebote, deren Verarbeitung nach dem voraussichtlichen Zeitpunkt noch geprüft werden muss.

Die überfälligen wartenden Bestellungen lassen sich ohne Änderung auflisten und einzeln untersuchen:

bin/console cwk:ppu:export-gate --stale
bin/console cwk:ppu:export-gate <order-id>

Nach der Prüfung: Für den Import freigeben

Eine Bestellung, die geprüft werden muss, wird nicht allein durch den Ablauf des voraussichtlichen Zeitpunkts bereit. So importiert das ERP sie nicht, bevor Sie sie geprüft haben.

Eine einzelne überfällige Bestellung kann über die Zeilenaktion in ERP-Export (Für den Import freigeben) oder interaktiv freigegeben werden:

bin/console cwk:ppu:export-gate <order-id> --release

Das ist eine Wiederherstellungsaktion, kein Aufräumbefehl. Prüfen Sie vor der Bestätigung Bestellpositionen, Transaktionen, Einzüge, Erstattungen und die Protokolle der Erweiterung. Stellen Sie sicher, dass die endgültigen Bestellpositionen und die Gesamtsumme zum endgültigen Zahlungs- oder Erstattungsergebnis passen. Wenn Sie den Import zu früh zulassen, kann das ERP die Bestellung importieren, bevor diese Einträge vollständig sind. Es gibt bewusst keinen Sammelbefehl.

Prüfablauf vor dem Live-Betrieb

1. Aktivieren Sie die Einstellung für einen Test-Verkaufskanal und wählen Sie entweder die ausschließlich vom ERP verwendete Integration oder das separate Benutzerkonto des ERP.
2. Legen Sie eine Testbestellung an, die ein Angebot erhält, und lassen Sie die Angebotsseite offen.
3. Starten Sie einen ERP-Import. Die ausgewählten ERP-Zugangsdaten dürfen die Bestellung noch nicht importieren können.
4. Lehnen Sie das Angebot ab. Beim nächsten vollständigen Lauf müssen die ausgewählten ERP-Zugangsdaten die Bestellung importieren können.
5. Wiederholen Sie den Test mit einer Annahme. Das ERP muss die Bestellung mit dem Zusatzartikel und der neuen Gesamtsumme erhalten.
6. Prüfen Sie, dass andere API-Zugangsdaten und Benutzer der Administration durchgehend auf die Bestellung zugreifen können. Das ausgewählte ERP-Benutzerkonto darf sie während der Wartezeit nicht sehen.

Kommt die Bestellung in Schritt 3 trotzdem an, verwendet das ERP wahrscheinlich andere Zugangsdaten oder einen nicht abgedeckten Exportpfad. Siehe Status (Health-Check) und FAQ.