README

Bindet einen Magento-Shop an den everysize-Direktkauf an: Bestellungen, die Kundinnen auf everysize.com aufgeben, landen als Bestellung im Shop; Bestellnummer, Versand, Storno, Retoure und Erstattungen gehen zurück an everysize.

Composer-Paket everysize/checkout-magento2, Modul Everysize_Checkout.

Voraussetzungen

Magento Open Source 2.4.4 oder neuer (getestet mit 2.4.9/PHP 8.4); Adobe Commerce funktioniert ebenso
PHP ≥ 8.1 mit curl und json
Magento-Cron (bin/magento cron:run) — der Abgleich hängt an der Standard-Cron-Gruppe

Kein PayPal-Modul nötig: bezahlt wird bei everysize. Importierte Bestellungen tragen die Zahlungsart „everysize (PayPal)“ mit einer bezahlten Rechnung. Erstattet wird über everysize (das Geld geht über das PayPal-Konto zurück, mit dem die Kundin bezahlt hat) — siehe „Retoure und Erstattung“.

Ablauf

Richtung	Was	Wann
everysize → Shop	neue Bestellungen (`PROCESSING`, auch bereits stornierte `REVOKED`) ohne Händler-Bestellnummer	jeder Lauf
Shop → everysize	Magento-Bestellnummer	direkt nach dem Import
Shop → everysize	Preis und Bestand des Artikels im Shop	direkt nach dem Import
Shop → everysize	Versand mit Sendungsnummer und Versanddienstleister	Sendung angelegt
Shop → everysize	Sendungsnummer nachgetragen oder korrigiert	bis 14 Tage nach der Versandmeldung, nur wenn everysize sie noch nicht hat
Shop → everysize	Erstattung (ganz oder teilweise)	Gutschrift mit „Erstatten“ (online) oder Button im Reiter „everysize“
Shop → everysize	Storno/Retoure als Rückmeldung	Artikel storniert oder Gutschrift angelegt
everysize → Shop	Hinweis auf Bestellungen, die bei everysize storniert wurden	am Ende jedes Abgleichs, Bestellungen der letzten 30 Tage

Der Abgleich läuft alle 5 Minuten (Cron, Einstellung „Automatischer Abgleich“) und in einem Lauf in beide Richtungen. Manuell:

bin/magento everysize:sync              # Import + Rückmeldungen
bin/magento everysize:order:import      # nur Import
bin/magento everysize:order:export      # nur Rückmeldungen

Installation

Per Composer (composer require everysize/checkout-magento2) oder als ZIP: das ZIP im Ordner app/code des Shops entpacken (es legt app/code/Everysize/Checkout mit registration.php und etc/ an). Danach:

bin/magento module:enable Everysize_Checkout
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

Konfiguration

Verkäufe → everysize Checkout → Einstellungen:

Zugangsdaten — Client-ID und Client-Secret aus everysize Business („Shop-Integration“ → Magento 2). Das Secret wird verschlüsselt in der Shop-Datenbank gespeichert und ist dort allein nicht lesbar. Der „Verbindung testen“-Button zeigt die everysize-Shop-ID und die verbundene Umgebung.
Import — Store-View für importierte Bestellungen, Bestellstatus (Standard „Verarbeitung“) und ob die Bestellbestätigung per Shop-Mail geht (dann versendet das Modul sie selbst nach dem Speichern; die Mail der Kundin geht in jedem Fall an die everysize-Weiterleitungsadresse, die Original-Adresse steht nur zur Information im Reiter „everysize“).
Abgleich — Automatischer Abgleich (Cron) an/aus.
Erstattungen — Ob ein Storno vor dem Versand automatisch voll über everysize erstattet wird (an, Standard) und ab wann.

Die Moduleinstellungen gelten shopweit (eine everysize-Verbindung pro Installation).

Storno bei everysize

Wird eine schon importierte Bestellung bei everysize storniert, schreibt das Modul einmal einen Kommentar in den Bestellverlauf („Bitte nicht versenden und im Shop stornieren“) und einen Eintrag ins Protokoll. Ist die Bestellung im Shop schon als versendet markiert, lautet der Kommentar „Bitte prüfen“. Der Kommentar ist keine Kundenbenachrichtigung, es geht keine Mail raus. Das Modul ändert dabei nichts: kein Status, kein Bestand, keine Erstattung; Sie entscheiden. Geprüft werden Bestellungen der letzten 30 Tage; schon stornierte oder erstattete Bestellungen bekommen keinen Kommentar. Eine Erstattung, die Sie direkt in PayPal machen, ohne die Bestellung bei everysize zu stornieren, kennt everysize nicht als Storno; dafür gibt es keinen Hinweis.

Retoure und Erstattung

Gutschrift aus der Rechnung, „Erstatten“ (online) — Bestellung → Reiter „Rechnungen“ → Rechnung öffnen → „Gutschrift“ → Mengen/Beträge → „Erstatten“. Der Betrag der Gutschrift geht sofort über everysize an PayPal zurück, auch teilweise; lehnt everysize/PayPal ab, wird keine Gutschrift angelegt und Magento zeigt den Grund. Das ist der normale Weg.
„Offline erstatten“ bucht nur die Gutschrift und bewegt kein Geld — für Erstattungen, die direkt im PayPal-Konto gemacht wurden. Eine Gutschrift aus der Bestellansicht (Button „Gutschrift“ oben) ist in Magento immer offline.
Jede Gutschrift meldet die betroffenen Artikel an everysize: vor dem gemeldeten Versand als Storno (MERCHANT_DECLINE), danach als Retoure.
Ein Storno vor dem Versand ohne jede Erstattung erstattet das Modul im nächsten Lauf automatisch voll (Einstellung, siehe oben). Das geschieht nur, wenn sicher nichts versendet wurde (keine Lieferung, keine Versandmeldung) und es keine andere Erstattung gibt: keine Gutschrift im Shop — auch keine Offline-Gutschrift —, und bei everysize/PayPal keine erstattete oder ausstehende. Ist die Erstattungsliste nicht lesbar, wird der Lauf übersprungen. Greift eine Sperre, steht der Grund im Reiter „everysize“; erstattet wird dann nur von Hand.
Fassung 3 der Regeln (Kurzfassung): Ein 2xx ohne refundId ist unklar, kein Erfolg. Der Eintrag wird zuerst angelegt, danach wird die PayPal-Liste gelesen und deren refundIds werden im Eintrag gespeichert; eine alte oder fremde Erstattung gilt nie als Treffer. Ungültige oder nicht lesbare Liste, veralteter Tab: der neue Eintrag wird gelöscht, nichts gesendet. Lehnt der Checkout eine Wiederholung sicher ab, bleibt der Eintrag offen (PayPal prüfen, als geklärt markieren). Die 150 s zählen ab der letzten Sendung; Wiederholen und „Als geklärt markieren“ sind atomar. Erst Schlüssel-/Erstattungsbericht, dann wird der Eintrag gelöscht. Die Automatik sendet höchstens einmal. Die Bestätigungen im Reiter laufen über renderEventListenerAsTag und funktionieren auch unter strenger CSP. Eine im Reiter wiederholte oder als geklärt markierte Gutschrift erhöht den Ablehnungszähler (neuer Gutschrift-Schlüssel).
Bezahlt, aber nicht gebucht: Rollt Magento eine Gutschrift nach gezahlter Erstattung zurück oder kommt eine Offline-Gutschrift dazwischen, wird keine weitere Gutschrift-Erstattung der Bestellung gesendet, bis die bezahlte Erstattung als Transaktions-ID einer festgeschriebenen Gutschrift steht (Gutschrift mit genau diesem Betrag noch einmal anlegen) oder im Reiter „Als geklärt markieren“ wurde. Die Meldung nennt den schon ausgezahlten Betrag.
Ergebnis unklar: Antwortet der Checkout nicht eindeutig (Zeitüberschreitung, Serverfehler, aber auch 401, 403, 404, 429 oder ein Fehler im Browser), kann das Geld geflossen sein. Eindeutig abgelehnt ist nur 422 mit PAYPAL_REFUND_FAILED oder REFUND_AMOUNT_INVALID und 400 mit ORDER_NOT_PAID_USING_EVERYSIZE_CHECKOUT_PAYMENTS. Jede Erstattung steht vor dem Senden als offener Eintrag in der Datenbank (einer je Bestellung, zwei Admins oder Tabs senden nie gleichzeitig; bei der Gutschrift über eine eigene DB-Verbindung, damit er den Rollback der Gutschrift übersteht). Solange er offen ist, geht keine andere Erstattung raus — weder von Hand noch automatisch noch als Gutschrift. Ein Eintrag unter 150 Sekunden gilt als „läuft noch“. Danach: Wiederholen im Reiter (derselbe Betrag; vorher liest das Modul die PayPal-Liste und schließt den Eintrag als Erfolg ab, wenn dort eine passende, dem Shop noch unbekannte Erstattung steht; ging die erste Anfrage nicht durch, wird der Betrag jetzt ausgezahlt) oder Als geklärt markieren (sendet nichts, schreibt Bericht und Protokolleintrag, die automatische Erstattung bleibt für diese Bestellung gesperrt). Ein anderer Betrag wird abgelehnt. Das Formular sendet die beim Laden bekannte Erstattungssumme mit: veraltet oder Liste nicht lesbar heißt, es wird nichts gesendet. Der Schlüssel einer Online-Gutschrift ist aus Bestellung, Betrag, den festgeschriebenen Gutschriften der Bestellung und den eindeutigen Ablehnungen abgeleitet; wird eine Gutschrift nach gebuchter Erstattung von Magento zurückgerollt, wird beim nächsten Versuch die Gutschrift gebucht und nicht erneut erstattet. Nach einer eindeutigen Ablehnung ist der Schlüssel neu. Alte Berichte „unklar“ früherer Versionen sind keine offenen Einträge, nur Anzeige und Sperre der Automatik. Erstattungsaufrufe warten bis zu 90 Sekunden.

Reiter „everysize“ in der Bestellung

everysize-Bestellnummer, PayPal-Transaktion (Capture-ID), die Original- E-Mail der Kundin (nur zur Information), was gemeldet ist, und das Erstattungs-Formular für Beträge ohne Gutschrift: Betrag (vorbelegt mit dem offenen Betrag, bei unklarem Ergebnis mit dessen Betrag), ganz oder teilweise — vor dem Absenden fragt der Browser mit dem Betrag nach; ein Formular, das zweimal abgeschickt wird, erstattet nur einmal. Bestellstatus und Sendungsnummern meldet das Modul selbstständig.

Bestellliste

Spalte „everysize“ mit der everysize-Bestellnummer, filter- und sortierbar.

Testumgebung

Das Modul liest die API-Adresse aus der Umgebungsvariable EVERYSIZE_CHECKOUT_API_URL (nur https://-Adressen unter everysize.com): ist sie gesetzt, zeigt die Einstellungsseite die Testumgebung an und überträgt nichts in die Produktion. Ohne die Variable läuft das Modul immer gegen die Produktion.

Tests

Die Unit-Tests laufen ohne Magento (reine PHP-Klassen mit Fakes für Datenbank und HTTP):

composer install --working-dir=test-vendor   # einmalig
test-vendor/bin/phpunit --testdox

Ein Syntax-Check aller Quelldateien gegen PHP 8.1 (die Untergrenze des Moduls) lässt sich mit einem PHP-8.1-Container fahren:

docker run --rm -v "$PWD:/app" -w /app php:8.1-cli \
    sh -c 'find . -name "*.php" -not -path "./test-vendor/*" | xargs -n1 php -l'

Lizenz

MIT — siehe LICENSE.

everysize / checkout-magento2

Package info

Security

Statistics