Inbetriebnahme-Verfahren

Allgemeines Dokument. Es gilt für jede Installation, bei der Shopify durch die Migration eines bestehenden Shops (PrestaShop, WooCommerce, Magento …) befüllt wird, während Dolibarr die zugehörige Verkaufshistorie bereits enthält.

1. Das Risiko, das dieses Verfahren ausschließt

Wenn Ihre historischen Bestellungen nach Shopify übernommen werden, erhalten sie dort neue Shopify-Kennungen, und ihr Erstellungs- sowie Änderungsdatum ist das des Migrationstages — Shopify erlaubt das Rückdatieren des Bearbeitungsdatums, niemals dieser beiden Zeitstempel.

Doli2Shop erkennt eine bereits importierte Bestellung an ihrer Shopify-Kennung. Eine Bestellung, die aus einer anderen Quelle in Dolibarr liegt, trägt keine Shopify-Kennung: Das Modul kann nicht wissen, dass es sich um denselben Verkauf handelt. Ohne Vorkehrungen wird sie ein zweites Mal importiert — mit dem heutigen Datum, in Ihre Buchhaltung.

Drei voneinander unabhängige Wege können eine Bestellung importieren:

2. Vor der Migration — die Einstellungen

• Richtung der Bestandssynchronisation. DOLI2SHOP_SYNC_STOCKS_DIRECTION muss auf dolibarr_to_shopify stehen, wenn Dolibarr Ihr führendes System für Bestände ist. Der Standardwert ist both: Damit schreibt ein Shopify-Bestands-Webhook auch Lagerbewegungen zurück nach Dolibarr.
• Unbezahlte Bestellungen. Standardmäßig werden nur Bestellungen mit dem Finanzstatus bezahlt importiert. Sollen auch zahlungsoffene Bestellungen erfasst werden (B2B-Zahlungsziel, Überweisung), aktivieren Sie DOLI2SHOP_SYNC_NON_PAID_ORDERS.
• Artikelreferenzen. Die SKU der Shopify-Varianten müssen exakt den Dolibarr-Referenzen entsprechen: Diese Zuordnung verhindert doppelt angelegte Artikel und Varianten.
• E-Mail-Adressen der Geschäftspartner. Ein bestehender Kunde wird über die E-Mail-Adresse des Firmendatensatzes selbst zugeordnet, nicht über dessen Kontakte, und innerhalb derselben Mandanteneinheit. Eine Adresse, die nur an einem Kontakt hängt oder von der Shopify-Adresse abweicht, erzeugt eine doppelte Firma. Bereinigen Sie das vor der Umstellung — eine Daten-, keine Konfigurationsaufgabe.

3. Während der Migration — was ausgeschaltet bleiben muss

Solange die Migration nicht abgeschlossen und geprüft ist, müssen alle drei Importwege inaktiv sein:

1. die Bestell-Webhooks — Bildschirm Webhooks in der Modulkonfiguration;
2. die geplante Aufgabe Doli2ShopOrdersCatchup;
3. die geplante Aufgabe Doli2ShopOrdersHistoricalImport.

Prüfung mit einer einzigen Abfrage (nur lesend):

SELECT label, entity, status FROM llx_cronjob WHERE label LIKE 'Doli2Shop%';

Beide Aufgaben müssen status = 0 anzeigen. Prüfen Sie bei einer Multicompany-Installation zugleich, ob die Spalte entity der Einheit entspricht, in der das Modul konfiguriert ist: Eine in der falschen Einheit angelegte Aufgabe läuft ins Leere, ohne einen Fehler zu melden.

Die Artikel- und Bestandssynchronisation darf in dieser Phase weiterlaufen.

4. Die Umstellung

1. Schließen Sie die Migration ab und prüfen Sie sie in Shopify.
2. Notieren Sie den genauen Zeitpunkt des Migrationsendes — nennen wir ihn T0.
3. Senken Sie DOLI2SHOP_CATCHUP_LOOKBACK_HOURS auf einen Wert, der nicht vor T0 zurückreicht: 1 oder 2 Stunden. Der Standardwert ist 168 (7 Tage) und würde Ihre migrierten Bestellungen unmittelbar hereinholen.
4. Aktivieren Sie zuerst die Bestell-Webhooks, danach die Nachhol-Aufgabe.

5. Nach der Umstellung — die Kontrollen

• Öffnen Sie den Bildschirm der Webhook-Ereignisse: Er listet mit Status auf, was eingeht.
• Prüfen Sie, dass keine Bestellung mit einem Datum vor T0 in Dolibarr angelegt wurde.
• Setzen Sie DOLI2SHOP_CATCHUP_LOOKBACK_HOURS erst dann auf den üblichen Wert (168) zurück, wenn T0 mehr als sieben Tage zurückliegt. Vorher würde das Zeitfenster Ihre migrierten Bestellungen erfassen.

6. Was dieses Verfahren nicht abdeckt

Das Nachhol-Zeitfenster begrenzt die geplante Aufgabe, nicht die Webhooks.

Nach der Umstellung löst jede Änderung einer migrierten Bestellung in Shopify — eine Bearbeitung, eine Rückerstattung, eine Adresskorrektur, das Hinzufügen eines Tags — einen orders/updated-Webhook aus. Das Modul kennt diese Bestellung nicht und legt sie an. Sie erhalten eine historische Bestellung, neu importiert mit dem heutigen Datum.

Diese Lücke lässt sich nicht durch das Verfahren schließen. Schließen würde sie eine Einstellung „Datum der Inbetriebnahme“: Jede vor dem gewählten Datum in Shopify erstellte Bestellung würde vom Import ausgeschlossen — unabhängig vom Weg, also Erstellungs-Webhook, Änderungs-Webhook und Nachhol-Aufgabe —, während der bewusste historische Import seine eigenen Grenzen behält.

⚠️ Diese Einstellung existiert im Modul noch nicht. Sie ist eine Entwicklung und wird auf Angebot angeboten. Ohne sie hilft nur Wachsamkeit gegenüber den migrierten Bestellungen: Sie nach der Umstellung in Shopify nicht bearbeiten und regelmäßig prüfen, dass keine Bestellung vor T0 in Dolibarr aufgetaucht ist.

7. Falls dennoch ein Duplikat entsteht

1. Finden Sie es über den Bildschirm der Webhook-Ereignisse: Das Ereignis trägt die Kennung der betroffenen Shopify-Bestellung.
2. Solange die angelegte Dolibarr-Bestellung weder validiert noch fakturiert ist, bleibt ihr Löschen buchhalterisch folgenlos.
3. Ist sie bereits fakturiert, erfolgt die Korrektur nach Ihrer üblichen Dolibarr-Praxis (Gutschrift oder Stornierung, je nach Rechnungslegung) — seitens des Moduls ist nichts Besonderes nötig.
4. Beseitigen Sie zuerst die Ursache, sonst legt der nächste Webhook dieselbe Bestellung erneut an.