README

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

Phoenix-Add-ons liegen verteilt im Shop-Root (admin/, includes/hooks/, ext/everysize_checkout/, Sprachdateien) — es gibt kein Module-Center, das ein ZIP entgegennimmt; die Installation ist das Kopieren der Dateien (siehe Installation).

Voraussetzungen

CE Phoenix Cart 1.1 (getestet mit 1.1.0.8)
PHP ≥ 7.4 mit curl und json (getestet mit 8.3)
MySQL 5.7/8 (das Add-on legt vier eigene Tabellen everysize_checkout_* an)
Ein Cron, der den Abgleich aufruft (siehe unten)

Kein Zahlungsmodul nötig: bezahlt wird bei everysize. Erstattet wird über everysize (das Geld geht über das PayPal-Konto zurück, mit dem bezahlt wurde). Phoenix kennt keinen Online-Erstattungsweg für Zahlungsarten — die Erstattung läuft über die everysize-Box im Bestelldetail und die Auto-Erstattung.

Installation

ZIP (everysize-checkout-phoenix-cart-<version>.zip, Download in everysize Business unter „Shop-Integration" → Phoenix Cart) entpacken und den Inhalt in das Shop-Root kopieren (per FTP/SFTP) — es landen admin/, includes/ und ext/everysize_checkout/ dazu; Phoenix-eigene Dateien werden nicht berührt. Hinweis zum Admin-Ordner: Phoenix empfiehlt, den Standard-admin-Ordner umzubenennen (Sicherheit). Liegt euer Admin-Panel unter anderem Namen, kopiert den Inhalt des ZIP-admin/-Ordners entsprechend in euren (ggf. umbenannten) Admin-Ordner statt nach admin/ — includes/ und ext/ immer ins Shop-Root.
Cache leeren: im Shop-Root die Dateien includes/work/*.cache löschen (Phoenix hängt Hook-Dateien und Sprachen an Dateipfade).
Installieren: Admin → Menü everysize → everysize Checkout → „Installieren". Das legt die Tabellen everysize_checkout_settings, everysize_checkout_order, everysize_checkout_order_item, everysize_checkout_report und everysize_checkout_protocol an (idempotent) und setzt die Schema-Version. Deinstallieren behält alle Daten — es setzt nur das Install-Flag zurück, damit sich die Installation später fortsetzen kann.
Client-ID und Client-Secret (aus everysize Business, „Shop-Integration") eintragen und speichern.
Konfiguration: Carrier, Import-Status, Status für Versand/Storno/Retoure, Bestellbestätigung an/aus, Auto-Erstattung an/aus, „Abgleich aktiv".

Update: Neues ZIP entpacken und den Inhalt über den bestehenden Shop-Root kopieren (Dateien werden ersetzt, Zugangsdaten, Einstellungen und Verknüpfungen bleiben in der Datenbank), includes/work/*.cache löschen. Neue Tabellen legt das Add-on beim nächsten Aufruf selbst an (Admin-Seite, Bestelldetail, Abgleich), ohne Klick und ohne Datenverlust; ein Klick auf „Installieren“ ist nur beim ersten Mal nötig. Scheitert das Anlegen, zeigt die Admin-Seite den Fehler, das Bestelldetail „Datenbank-Update nötig“ ohne Erstattungsformulare, und der Abgleich bricht mit dem Fehler ab. Andere Bestellseiten und die Bestellübersicht bleiben davon unberührt.

Abgleich (Import + Rückmeldung)

Der Abgleich läuft über einen System-Cron alle 5 Minuten, CLI-Einstieg:

php /pfad/zum/shop/ext/everysize_checkout/sync.php            # normal
php ext/everysize_checkout/sync.php --json                    # für Maschinen
php ext/everysize_checkout/sync.php --force                   # umgeht „Abgleich aktiv“

Der Abgleich importiert neue Bestellungen („processing"), meldet Status und Sendungsnummern zurück und räumt das Protokoll auf (31 Tage). Ohne Zugangsdaten beendet er sich mit Exit 0 und einer Meldung; bei Fehlern mit Exit 1.

API-Umgebung: ohne Konfiguration läuft das Add-on immer gegen die Produktion (https://ext-checkout.everysize.com). Ein Test-Shop setzt EVERYSIZE_CHECKOUT_API_URL auf die Adresse eines Test-Systems — die everysize mit den Test-Zugangsdaten ausgibt. Jede andere Adresse (nicht https://…everysize.com) ist ein Fehler und fällt nicht auf Produktion zurück.

Was der Import anlegt

Eine orders-Zeile wie der Phoenix-Checkout (Denormalisate customers_*/delivery_*/billing_*, payment_method als Text „everysize Checkout", Versandart aus orders_total), Gastbestellung mit customers_id = 0 — Phoenix kennt keinen Gast-Checkout, aber die Spalte hat keinen Fremdschlüssel, und der Admin liest ausschließlich die Denormalisate.
orders_products mit dem Netto-Stückpreis (Phoenix speichert netto), products_tax = Mehrwertsteuersatz; die Variante als products_attributes- Zeile (Option „Größe“, Aufpreis 0.0000). Die Artikelnummer löst sich auf nach products_model — exakt vor groß/klein-insensitiv, aktive vor inaktiven Produkten; passt kein Modell, wird „Basis-Modell + Größe“ als Optionswert probiert. Mehrdeutige Artikelnummern sind ein Fehler, der Bestand wird nie geprüft (die Bestellung ist bezahlt).
orders_total mit Phoenix-Titeln: Positionen und Versand netto und die MwSt.-Zeile mit dem steuerlichen Satz je Position (Logik wie Tax::fetch: Geo-Zone des Shops, mehrere Steuersätze je Position als eigene Zeilen), Gesamtsumme fett. Steht DISPLAY_PRICE_WITH_TAX auf true, werden Positionen und Versand brutto angezeigt und die MwSt.-Zeile entfällt.
Bestandsabzug nach der Phoenix-Matrix: STOCK_LIMITED === 'true' zieht products_quantity ab und setzt das Produkt bei 0 optional inaktiv (dasselbe wie update_stock.php). Der Attribut-Bestand wird nicht angetastet — Phoenix hat keinen ATTRIBUTES_STOCK.
Import-Meldung (ab 1.1.0): Vor dem Schreiben liest das Add-on je Position den aktuellen Brutto-Shop-Preis und den Bestand (nur wenn der Shop den Verkauf über den Bestand begrenzt). Weicht der Preis um mehr als 0,009 vom bezahlten Preis ab oder liegt der Bestand unter der Bestellmenge, steht eine Warnung im Protokoll; der Lauf bleibt erfolgreich. Die Meldung an everysize ist reine Information: sie ändert weder Bestellung noch Preis, ein Fehler dabei stoppt den Import nicht und wird nicht wiederholt. Stornierte und bereits importierte Bestellungen werden nicht gemeldet. Der Preis ist der Bruttopreis, den der Shop im Inland verlangt (Steuersatz des Shop-Standardlandes, nicht des Lieferlandes). Den Bestand meldet das Add-on nur, wenn STOCK_LIMITED und STOCK_CHECK auf true stehen und der Checkout ohne Bestand nicht erlaubt ist (STOCK_ALLOW_CHECKOUT), sonst bleibt er leer. Grenze: Phoenix führt den Bestand je Artikel, nicht je Größe. Gemeldet wird der Bestand des ganzen Artikels, und everysize deaktiviert damit nur die verkaufte Größe. Ist eine einzelne Größe ausverkauft, während der Artikel insgesamt noch Bestand hat, bleibt das unbemerkt.
Eine stornierte Bestellung (REVOKED) wird direkt in den konfigurierten Storno-Status gestellt und bucht keinen Bestand ab.

Rückmeldung an everysize

Versand: Bestellung auf den konfigurierten Versand-Status setzen — der Sync meldet Fulfillment (Carrier aus der Einstellung). Sendungsnummer und Carrier tragen Händler in der everysize-Box ein, auch nachträglich oder korrigiert (bis 14 Tage nachgemeldet, solange die Bestellung im Checkout completed ist).
Storno: Statuswechsel auf den Storno-Status → MERCHANT_DECLINE. Ist die „Automatische Erstattung" aktiv und es existiert kein Erstattungsvorgang, wird voll erstattet. Nach einem gemeldeten Versand wird derselbe Status- wechsel als RETOUR gemeldet — auch wenn Versand und Storno im selben 5-Minuten-Fenster liegen (erst Fulfillment mit Sendungsnummer, dann RETOUR).
Retoure: Kommt Ware zurück, erstatten Sie wie gewohnt — bei everysize-Bestellungen in der everysize-Box: Häkchen „Ware ist zurückgekommen: Retoure an everysize melden“ setzen, den zu erstattenden Betrag eintragen (z. B. ohne Versandkosten) und „Erstatten“. Das Add-on meldet zuerst die Retoure (RETOUR) und erstattet dann den Betrag. Ist schon alles erstattet, meldet „Retoure melden“ die Retoure allein. Wer lieber mit Status arbeitet, nutzt weiter den Retoure-Status bzw. den Storno-Status nach dem Versand (beides ohne Erstattung).
Erstattungen aus der Box laufen sofort über den Checkout an PayPal (ganz oder teilweise); Auto-Erstattungen nach dem Storno ebenfalls. Beide stehen als Kommentar im Bestellverlauf, Box-Erstattungen 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), 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), stehen einmal im Protokoll. Grenze: Eine Gutschrift, die nur im Shop gebucht wird, erkennt das Modul nicht. Erstatten Sie vor dem Storno selbst oder schalten Sie die Automatik ab.
Jede Rückmeldung wird idempotent vermerkt (everysize_checkout_report), so dass ein Abgleich-Lauf nichts doppelt sendet.
Die Import-Meldung (Shop-Preis und Bestand je Position) geht einmal direkt nach dem Import an everysize.
Die Händler-Bestellnummer meldet der Import NACH dem Commit zurück; eine fehlgeschlagene Rückmeldung holt der nächste Lauf nach.

Storno bei everysize erkennen

Wird eine bereits importierte Bestellung später bei everysize storniert, schreibt das Add-on 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 über everysize 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 Add-on ä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 Add-on nicht.

Admin

Menü everysize:
- everysize Checkout — Installation, Zugangsdaten (Secret wird nie zurückgeschrieben), Verbindungstest, Status-Zuordnungen, Bestell- bestätigung, Auto-Erstattung, „Jetzt abgleichen" (läuft synchron im Request).
- everysize Protokoll — die Einträge des Abgleichs, gefiltert nach ok/Fehler, 50 pro Seite.
Bestelldetail: Tab everysize mit everysize-Nummer, Import-Zeit, Zahlungsmeldung, PayPal-Capture-ID, Original-Mail der Kundin, Zahlständen (bezahlt/erstattet/noch offen), Erstattungs-Formular (mit Bestätigungs- dialog und einmaligem Erstattungsschlüssel), Sendungsnummer + Carrier und der Rückmeldungs-Tabelle. Ohne Zugangsdaten zeigt die Box einen Hinweis statt der Zahlstände; der Rest bleibt nutzbar.
Bestellübersicht: Kennzeichen „— everysize " hinter der Gesamtsumme und ein Suchfeld für die everysize-Nummer (eine eigene Spalte gibt es nicht — Phoenix' Listenansicht ist hart kodiert).

Artikelnummern

Everysize bestellt mit der Varianten-Artikelnummer (CW2288-111-42.5), die der Händler im everysize-Business hinterlegt. Sie muss im Shop auffindbar sein — entweder als products_model exakt in dieser Form, oder als Kombination aus products_model (Basis) und dem Optionswert der Größe („42.5"). Mehrere Produkte mit derselben Artikelnummer sind ein Importfehler (wird im Protokoll vermerkt), damit nie in die falsche Bestellung importiert wird.

Lizenz

MIT, siehe LICENSE.

everysize / checkout-phoenix-cart

Package info

Security

Statistics