README

Bindet einen Gambio-Shop an den everysize-Direktkauf an: Bestellungen aus everysize werden importiert (inkl. Gastkonten, Varianten, Bestandsabzug und optionaler Bestellbestätigung), und Bestellnummer, Versand, Sendungsnummern, Storno, Retoure und Auto-Erstattungen werden zurückgemeldet.

Den Quellcode gibt es auch als Composer-Paket everysize/checkout-gambio. Installiert wird das Modul aber nicht per Composer, sondern über das ZIP (siehe Installation): Gambio lädt Module nur aus GXModules/ (hier GXModules/Everysize/Checkout), nicht aus vendor/. Ein composer require im Shop-Verzeichnis ist nicht vorgesehen — Gambio liefert vendor/ ohne composer.json aus, Composer würde dessen Autoloader überschreiben.

Voraussetzungen

Gambio GX 26.09 (getestet mit 26.09.0)
PHP ≥ 8.1 mit curl und json
Gambio-Cronjob (Toolbox → Cronjobs) — der Abgleich hängt daran

Kein PayPal-Modul nötig: bezahlt wird bei everysize. Erstattet wird über everysize (das Geld geht über das PayPal-Konto zurück, mit dem bezahlt wurde).

Installation

Gambio 26.09 hat keinen Installer, der ZIPs entgegennimmt — das Modul wird als Dateisatz unter GXModules/Everysize/Checkout installiert:

ZIP (everysize-checkout-gambio-<version>.zip, Download in everysize Business unter „Shop-Integration“ → Gambio) entpacken und den enthaltenen Ordner GXModules in das Shop-Root kopieren (per FTP/SFTP), so dass GXModules/Everysize/Checkout/GXModule.json liegt.
Cache leeren: Admin → Toolbox → Cache → „Cache leeren“.
Module Center: admin.php?do=ModuleCenter → „everysize Checkout" → Installieren. Das legt die Modul-Tabellen an (everysize_checkout_*, idempotent), setzt die Schema-Version und aktiviert den Cronjob im Zusammenspiel mit dem Modul-Schalter „Abgleich aktiv" (ein Schalter, kein zweiter Haken).
Client-ID und Client-Secret (aus everysize Business, „Shop-Integration") eintragen und speichern.
Konfiguration: Versand-/Storno-/Retoure-Status, Import-Status, Bestellbestätigung an/aus, „Abgleich aktiv".

Update: Neue ZIP-Dateien entpacken und den Ordner GXModules/Everysize/Checkout über den bestehenden kopieren (Dateien werden ersetzt, Zugangsdaten und Einstellungen bleiben in der Datenbank) und den Cache leeren. Neue Tabellen legt das Modul beim nächsten Aufruf selbst an (Bestellseite, Cronjob, CLI-Abgleich, Admin-Aktionen), ohne Klick und ohne Datenverlust; scheitert das Anlegen, meldet die Bestellseite „Datenbank-Update nötig“ samt Fehlertext, zeigt keine Erstattungsformulare, und der Abgleich bricht mit demselben Fehler ab. Danach einmal „Toolbox → Cache“ im Admin aufrufen, damit die Sprachtexte des Moduls neu eingelesen werden (der Text-Cache liegt in der Datenbank, nicht im Dateisystem).

Cronjob (Import + Rückmeldung)

Der Abgleich läuft über den Gambio-Cronjob (alle 5 Minuten standardmäßig):

Admin → Toolbox → Cronjobs: Dort steht der Task „everysize Checkout-Abgleich" mit dem Schalter „aktivieren" (folgt dem Modul-Schalter „Abgleich aktiv") und dem Intervall. Die Cronjob-URL zum Eintragen in einen externen Cron ist dieselbe, die Gambio für jeden Cronjob anbietet:
```
{SHOP_URL}/shop.php?do=Cronjobs/Run&token={TOKEN}
```
Der Token steht im Gambio-Admin unter Toolbox → Cronjobs („Cronjob-URL" pro Eintrag); er wird vom Shop verwaltet und ist kein Modul-Secret.
Alternativ per CLI: php GXModules/Everysize/Checkout/bin/sync.php (--json für Maschinen, --force zum Umgehen des „Abgleich aktiv"- Schalters, Exit-Code 1 bei Fehlern). Die CLI importiert ohne Bestellbestätigung — die holt der Cronjob mit dem nächsten Lauf nach (confirmation_sent_at bleibt dann zunächst NULL).

Was der Import anlegt

orders-Zeile wie der Gambio-Checkout (Namensspalten customers_, delivery_, billing_ aus Vor-/Nachname, orders_hash, dynamische Bestellsprache und address_format_id, Gastbestellung ohne Konto).
orders_products mit Brutto-Preisen aus everysize; Varianten erhalten products_model nach APPEND_PROPERTIES_MODEL (Master-Modell + Combi- Modell), properties_combi_model aus den Werte-Namen und eine orders_products_properties-Zeile je Eigenschaft (nicht orders_products_attributes — Eigenschaften sind keine Attribute).
orders_total mit den Titeln und Sortierungen der ot_*-Module (MODULE_ORDER_TOTAL_*_SORT_ORDER, Steuerzeile aus TAX_ADD_TAX + tax_rates.tax_description, Summe fett).
Bestandsabzug nach der Gambio-Matrix (STOCK_LIMITED, products.use_properties_combis_quantity: 0 = Artikel (+ Combi nur bei Attribut-Bestandsprüfung), 1 = nur Artikel, 2 = nur Combi, 3 = nichts), symmetrisch zu xtc_remove_order. Negativer Bestand ist eine Warnung, kein Fehler — die Bestellung ist bezahlt.
Import-Meldung: Vor dem Schreiben liest das Modul je Position den aktuellen Brutto-Preis im Shop und den Bestand und meldet beides einmal an everysize. Weicht der Preis vom bezahlten ab oder reicht der Bestand nicht, steht eine Warnung im Protokoll; der Import läuft in jedem Fall mit dem bezahlten Preis weiter, ein Fehler bei der Meldung stoppt ihn nicht.
Eine REVOKED-Bestellung wird direkt in den konfigurierten Storno-Status gestellt und bucht keinen Bestand ab.

Rückmeldung an everysize

Versand (Status-Wechsel) + Sendungsnummern (orders_parcel_tracking_codes)
Storno je Position (Gambio-Storno/Retoure), Auto-Erstattung bei aktivem Schalter, Nachmeldung von Sendungsnummern bis 14 Tage
Jede Rückmeldung wird idempotent vermerkt (everysize_checkout_report)
Erstattungen (Box und automatisch) stehen als Kommentar im Bestellverlauf, ohne Statuswechsel; Erstattungen aus der Box zusätzlich im Protokoll
Nur eine klare Ablehnung der Erstattungsanfrage selbst gilt als „kein Geld geflossen“. Bei jeder anderen Antwort (Timeout, Serverfehler, auch 401/403/404/429) und bei einer Antwort ohne Refund-ID meldet die Box „Ergebnis unklar“: Das Geld kann ausgezahlt worden sein. Bitte in PayPal prüfen. Solange der Fall offen ist, geht keine andere Erstattung raus (auch keine automatische), und innerhalb von 2,5 Minuten nach dem Senden wird nichts wiederholt. „Wiederholen“ liest zuerst die Erstattungen bei PayPal: steht dort eine seit dem Anlegen neue, passende Erstattung, die der Shop nicht kennt, wird sie als Erfolg gebucht und nichts gesendet; ist die Liste nicht lesbar, wird nichts gesendet. Sonst gilt: Ging die erste Anfrage nicht durch, wird der Betrag jetzt ausgezahlt. Lehnt der Checkout die Wiederholung ab, bleibt der Fall offen. „Als geklärt markieren“ sendet nichts und beendet den Fall (frühestens 2,5 Minuten nach dem Senden); die automatische Erstattung bleibt dann für diese Bestellung aus.
Die automatische Erstattung sendet höchstens einmal je Bestellung und nur, wenn nichts auf einen Versand hindeutet (Status, Sendungsnummer, Lieferschein), kein Widerruf erfasst ist, die Gesamtsumme noch dem entspricht, was bezahlt wurde, und PayPal keine Erstattung zeigt. Ein unklarer Fall wird nie automatisch wiederholt. Stornos, die die Automatik übergeht (vor dem Einschaltdatum, mit nachträglich ergänzter Position), stehen einmal im Protokoll. Grenze: Eine Gutschrift, die nur im Shop gebucht wird, erkennt das Modul nicht (außer über die genannten Indizien). Erstatten Sie vor dem Storno selbst oder schalten Sie die Automatik ab.
Der everysize-Import schreibt die Händler-Bestellnummer NACH dem Commit zurück; eine fehlgeschlagene Rückmeldung wird beim nächsten Lauf geholt.

Storno bei everysize erkennen

Wird eine bereits importierte Bestellung später bei everysize storniert, schreibt das Modul bei jedem Abgleich (nach Import und Rückmeldung) einen Hinweis in den Bestellverlauf und einen Eintrag ins Protokoll:

Bestellung noch offen: „Bestellung … wurde bei everysize storniert. Bitte nicht versenden und im Shop stornieren.“
Bestellung im Shop schon als versendet markiert: „… ist hier aber schon als versendet markiert. Bitte prüfen.“
Bestellung im Shop schon storniert, zurückgesendet oder vollständig erstattet (eine Teilerstattung zählt nicht): kein Hinweis.

Der Hinweis steht einmal je Bestellung, auf Deutsch und Englisch, ohne Statuswechsel, ohne Mail an die Kundin und nennt nur die Bestellnummer. Das Modul ändert nichts selbst: kein Status, kein Bestand, keine Erstattung; Sie entscheiden. Ein Fehler bei dieser Prüfung erscheint höchstens als Warnung im Protokoll (je Fehlerart einmal am Tag) und stoppt weder Import noch Rückmeldung. Grenzen: Berücksichtigt werden Stornos der letzten 30 Tage (nach Bestelldatum), höchstens 500 Bestellungen je Lauf (bei mehr die jüngsten). Eine Erstattung, die Sie direkt in PayPal ohne Storno bei everysize veranlassen, erkennt das Modul nicht.

Architektur

src/ — Framework-freier Kern (Settings, API-Client, Sync, Import/Export-Logik, Unit-getestet).
Admin/Classes/ — Gambio-Anbindung (Db, Settings über den Konfigurationsspeicher, OrderImporter/OrderMailer, Protocol, Cronjob-Task/Dependencies/Logger, Module-Center-Modul).
Admin/TextPhrases/ — Sprachdateien (DE/EN).
bin/sync.php — CLI-Einstieg.

Lizenz

MIT, siehe LICENSE.

everysize / checkout-gambio

Package info

Security

Statistics