WebBlocks Commerce-Bedienerhandbuch

In diesem Handbuch wird erläutert, wie Sie WebBlocks Commerce installieren, konfigurieren und testen. Das Plugin unterstützt einen sitzungsgestützten öffentlichen Warenkorb, die Sammlung von Kunden- und Lieferadressen, einen Modus für Testbestellungen ohne Zahlung, einen mehrzeiligen gehosteten Checkout über PayPal oder SumUp, Produkt- und schreibgeschützte Bestellverwaltung, schreibgeschützte verschlüsselte Anbietereinstellungen, geheimnissichere Diagnose, öffentliche Produktseiten und einen Plugin-eigenen Commerce Buy Button-Block. Zahlungskartendaten verbleiben auf der gehosteten Zahlungsoberfläche des ausgewählten Anbieters.

Store-Besitzer, die SumUp anbinden möchten, sollten aufgabenorientiert beginnen SumUp Quick Start. Diese Bedienungsanleitung ist die technische Referenz für Architektur, APIs, Verifizierung und erweiterte Fehlerbehebung.

Das Plugin wird zusammen mit den anderen Katalog-Plugins in seinem eigenen Repository webblocks-commerce-plugin entwickelt. Es bleibt ein manuell installiertes Plugin-Paket und darf nicht in den CMS-Kern verschoben werden.

Dokumentierte Paketversion: 0.14.0. WebBlocks CMS ^1.61.0; PHP >=8.3.

PHP ext-intl ist sowohl auf Web- als auch auf CLI-Laufzeiten für die Währungsformatierung erforderlich.

1. Ein CMS-Betreiber installiert und aktiviert WebBlocks Commerce.
2. Der Betreiber führt Plugin-Migrationen über den Plugin-Detailbildschirm aus.
3. Der Betreiber wählt PayPal, SumUp oder Test order (no payment) und eine kompatible Standardwährung in Commerce Settings aus. Echte Anbieter benötigen Anmeldeinformationen; Stattdessen können vom Hosting verwaltete Umgebungswerte als Überschreibungen verwendet werden.
4. Der Operator öffnet Commerce Settings, um die Checkout- und Webhook-Bereitschaft zu bestätigen.
5. Der Betreiber erstellt ein Handelsprodukt.
6. Auf dem Produktdetailbildschirm wird eine öffentliche Kauf-URL angezeigt.
7. Der Bediener fügt einer Seite einen Commerce Buy Button-Block hinzu und wählt das Produkt aus.
8. Der Block fügt das Produkt zu /plugins/webblocks-commerce/cart hinzu; Der Besucher aktualisiert die Mengen und gibt die erforderlichen Kontakt- und Lieferdetails ein.
9. Im Test-Bestellmodus erfasst Commerce eine ausstehende, unbezahlte Bestellung und kehrt direkt zur Bestellstatusseite zurück, ohne einen Anbieter zu kontaktieren.
10. Bei PayPal oder SumUp genehmigt der Besucher die Zahlung auf der gehosteten Seite des ausgewählten Anbieters und kehrt zur Website zurück.
11. Bestellungen von echten Anbietern bleiben solange ausstehend, bis ein vom Anbieter verifizierter Webhook die Zahlung bestätigt.
12. Der Betreiber überprüft Kunden-, Liefer-, Artikel-, Steuer- und Zahlungsdetails unter Commerce Orders.

Erstellen Sie die Plugin-ZIP-Datei aus dem Plugin-Repository:

Das Artefakt wird in build/webblocks-commerce-{version}.zip geschrieben, mit seinem SHA-256 daneben.

Vervollständigen Sie dann den Lebenszyklus des manuellen Plugins:

1. Öffnen Sie System -> Plugins.
2. Laden Sie die generierte ZIP-Datei WebBlocks Commerce hoch.
3. Sehen Sie sich den Plugin-Detailbildschirm an.
4. Aktivieren Sie das Plugin.
5. Führen Sie Plugin-Setup/Migrationen aus, wenn das Plugin Setup required meldet.
6. Bestätigen Sie, dass sich der Zustand von „Setup erforderlich“ auf „Bereit“ ändert.

Das Plugin besitzt webblocks_commerce_*-Tabellen. Durch die Deaktivierung des Plugins werden Routen, Menüs, Einstellungen und Verhalten inaktiv. Durch die Deinstallation eines deaktivierten, manuell hochgeladenen Plugins wird das hochgeladene Paket entfernt, die Plugin-eigenen Tabellen bleiben jedoch erhalten.

Vertrauenswürdige Operator-Tools können den Einrichtungs- und Seitenerstellungs-Workflow über /webadmin/api durchführen, wenn das CMS-API-Token über explizite Plugin-, Handels- und Inhaltsfunktionen verfügt.

Plugin-Lebenszyklus:

Commerce-Ressourcen:

Rerforderliche Tokenfunktionen werden absichtlich aufgeteilt:

• plugin-Lebenszyklus: plugins.read, plugins.install, plugins.manage, plugins.setup und nur bei Bedarf plugins.uninstall
• Produktarbeit: commerce.read und commerce.products.write
• Bestellbewertung: commerce.orders.read
• Seitenplatzierung: content.validate und content.apply

Der API-Ablauf zum Hinzufügen einer Kaufschaltfläche lautet:

1. Installieren, aktivieren und richten Sie webblocks-commerce ein.
2. Erstellen Sie ein aktives Produkt mit POST /webadmin/api/commerce/products.
3. Lesen Sie GET /webadmin/api/block-types oder GET /webadmin/api/content-contract.
4. Fügen Sie einen webblocks-commerce-buy-button-Block durch Inhaltsvalidierung/-anwendung hinzu.
5. Legen Sie settings.commerce_product_id auf die Produkt-ID fest, die von der Commerce-API zurückgegeben wird.

Der Commerce Buy Button-Block ist Plugin-Eigentum. Es ist vor der Blockerkennung verborgen, während das Plugin deaktiviert ist, und die Inhaltsvalidierung/-anwendung lehnt fehlende, unbekannte oder inaktive Produkt-IDs ab. Sein öffentlicher Renderer postet im Warenkorb des Plugins; Es ist kein vertrauenswürdiger HTML-Block erforderlich. Die API erfasst keine Kartendaten; Besucher schließen die Zahlung über den konfigurierten PayPal- oder SumUp-gehosteten Checkout ab.

WebBlocks Commerce verwendet PayPal-REST-APIs. PayPal dokumentiert, dass REST-APIs OAuth 2.0-Zugriffstoken verwenden und dass API-Aufrufe eine Client-ID und ein Client-Geheimnis gegen ein Zugriffstoken austauschen. Halten Sie das Client-Geheimnis geheim und fügen Sie es niemals in CMS-Inhalte, Dokumentseiten, Screenshots oder Support-Protokolle ein.

Offizielle PayPal-Referenzen:

• Erste Schritte mit PayPal-REST-APIs
• PayPal unterstützte Währungscodes und Präzision
• PayPal Webhooks API
• Webhook-Signatur überprüfen

Öffnen Sie Commerce Settings, wählen Sie PayPal aus, wählen Sie Sandbox aus und geben Sie die Client-ID und das Client-Geheimnis ein. und Webhook-ID. Die Felder sind schreibgeschützt: Gespeicherte Werte werden in der Plugin-Einstellungstabelle verschlüsselt und werden nie wieder im Browser gerendert. Wenn Sie ein Feld leer lassen, bleibt der aktuelle Wert erhalten. Verwenden Sie das explizite Kontrollkästchen „Löschen“, um es zu entfernen.

Für die vom Hosting verwaltete Konfiguration werden die folgenden Umgebungsvariablen weiterhin unterstützt und übernommen Vorrang vor verschlüsselten Admin-Einstellungen:

Verwenden Sie WEBBLOCKS_COMMERCE_PAYPAL_MODE=live nur, nachdem Sandbox-Checkout und Webhook-Überprüfung getestet wurden.

Im PayPal-Entwickler-Dashboard:

1. Öffnen Apps & Credentials.
2. Verwenden Sie die Standard-REST-API-App oder erstellen Sie eine neue App.
3. Kopieren Sie die Sandbox-Client-ID und das Client-Geheimnis in das sichere Commerce-Einstellungsformular (oder in die Installationsumgebung, wenn vom Hosting verwaltete Außerkraftsetzungen verwendet werden).
4. Erstellen oder öffnen Sie die App-Webhook-Einstellungen.
5. Fügen Sie diese Webhook-URL hinzu:

1. Abonnieren Sie mindestens:

1. Kopieren Sie die PayPal-Webhook-ID in das Formular „Commerce-Einstellungen“ (oder WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID, wenn Sie eine Umgebungsüberschreibung verwenden).
2. Verwenden Sie PayPal-Sandbox-Käufer- und Verkäuferkonten für Checkout-Tests.

Für lokale HTTPS-Tunnel verwenden Sie die Tunnel-HTTPS-URL als Webhook-URL. Verwenden Sie für die Produktion die endgültige öffentliche HTTPS-Site-URL.

SumUp Hosted Checkout behält die Karteneingabe und die unterstützte Wallet-Benutzeroberfläche auf einer von SumUp gehosteten Seite bei. Die Die Integration erstellt den Checkout serverseitig und stellt den API-Schlüssel niemals dem Browser zur Verfügung.

Für einen Bildschirm-für-Bildschirm-Workflow für Ladenbesitzer verwenden Sie die SumUp Quick Start. Die kurze Setup-Sequenz lautet:

1. Erstellen und wählen Sie einen Sandbox-Händler unter SumUp Dashboard Entwicklereinstellungen → Sandboxes.
2. Kopieren Sie die Sandbox Merchant ID, die im Dashboard-Kontobereich oben links angezeigt wird.
3. Erstellen Sie einen geheimen Test-API-Schlüssel unter Einstellungen → Für Entwickler → Toolkit → API-Schlüssel.
4. Geben Sie das Gateway, den Modus, den API-Schlüssel und den Händlercode in den Commerce-Einstellungen ein und bestätigen Sie die Bereitschaft.
5. Testen Sie mit der dokumentierten Sandbox-Karte von SumUp, bevor Sie Live-Anmeldeinformationen verwenden.

Offizielle SumUp-Referenzen:

• Gehosteter Checkout
• Kassen erstellen und abrufen
• Checkout-Status-Webhooks
• API-Schlüssel
• Online-Zahlungen testen

In Commerce Settings wählen Sie SumUp, wählen Sie Sandbox aus und geben Sie den API-Schlüssel und den Händlercode ein. Gespeicherte Anmeldeinformationen werden im Ruhezustand verschlüsselt und bleiben schreibgeschützt. Hosting-verwaltete Bereitstellungen können Legen Sie stattdessen diese Umgebungsvariablen fest. Sie haben Vorrang und bilden die passenden Formularfelder schreibgeschützt:

Verwenden Sie den geheimen API-Schlüssel, der für den ausgewählten Sandbox-Händler erstellt wurde. Verwenden Sie nicht den öffentlichen Schlüssel von SumUp. Ein geheimer Testschlüssel beginnt normalerweise mit sk_test_. Fügen Sie es nicht in CMS-Blöcke, Site-Einstellungen usw. ein. Screenshots, Support-Protokolle oder normaler Chat. WebBlocks Commerce sendet diesen Rückruf automatisch wenn jede Kasse erstellt wird:

Für diesen Adapter ist keine manuelle Webhook-Registrierung im SumUp Dashboard erforderlich. Die Öffentlichkeit Der HTTPS-Endpunkt muss dennoch für SumUp erreichbar sein und darf nicht durch eine Firewall blockiert werden. Wartungsseite, HTTP-Passwort oder Proxy-Regel.

SumUp ruft den konfigurierten return_url mit CHECKOUT_STATUS_CHANGED und einer Checkout-ID auf. Das Zuladung wird nicht als Zahlungsnachweis akzeptiert. WebBlocks Commerce ruft den Checkout ab SumUp gleicht dann die ID, den Händlercode, die Bestellreferenz, den Betrag, die Währung, den Terminalstatus usw. ab. und erfolgreiche Transaktion, bevor Sie eine Bestellung als bezahlt markieren. Fehlgeschlagene und abgelaufene Statusübergänge Reservierten Lagerbestand freigeben. Unbekannte Ereignistypen werden sicher ignoriert.

Öffnen:

Der Einstellungsbildschirm bietet schreibgeschützte Anmeldeinformationsfelder und zeigt absichtlich nur sichere Diagnosen an:

• aktives Gateway
• Standardwährung und ihre Konfigurationsquelle
• PayPal-Modus
• SumUp-Modus
• Client-ID konfiguriert oder fehlt
• Client-Geheimnis konfiguriert oder fehlt
• Webhook-ID konfiguriert oder fehlt
• Checkout-Bereitschaft
• Webhook-Bereitschaft
• erwartete Webhook-URL
• SumUp-API-Schlüssel und Händlercode konfiguriert oder fehlen
• Plugin-Schema-Bereitschaft

Es dürfen keine rohen PayPal-Geheimnisse, SumUp-API-Schlüssel, Zugriffstoken, Webhook-Payload-Signaturen oder Zahlungsanmeldeinformationen angezeigt werden. Leere Anmeldeinformationsfelder behalten vorhandene verschlüsselte Werte bei. Durch explizite Löschsteuerelemente werden gespeicherte Werte entfernt, während umgebungsverwaltete Werte nicht vom CMS bearbeitet oder gelöscht werden können.

Öffnen:

Erstellen Sie ein Produkt mit:

• Titel
• slug
• Beschreibung
• status
• Preisbetrag
• Währung
• optionale Bestandsmenge
• optional SKU
• optionaler Standortumfang

Setzen Sie den Produktstatus auf Active, wenn es zur Kasse verfügbar sein soll. Für entworfene und archivierte Produkte wird kein öffentlicher Checkout gestartet.

Die Standardwährung wird mit den anderen Commerce-Einstellungen gespeichert und für neue Produkte verwendet. WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY bleibt eine optionale Umgebungsüberschreibung; wenn vorhanden, die Der Selektor ist schreibgeschützt. Die Produktwährung wird aus der unterstützten Liste des aktiven Gateways ausgewählt und Die interne Produkt-API erzwingt dieselbe Regel.

Das Umschalten von Gateways wird blockiert, wenn ein nicht archiviertes Produkt eine Währung verwendet, die vom Ziel nicht unterstützt wird Tor. Warenkörbe mit gemischten Währungen werden weiterhin abgelehnt. Checkout führt eine abschließende Gateway-Kompatibilität durch Überprüfen Sie dies, bevor eine Bestellung erstellt oder Lagerbestand reserviert wird.

Preise sind ganzzahlige Nebeneinheiten, aber die Genauigkeit der Nebeneinheiten ist währungsspezifisch und nicht immer zweistellig. Öffentliche und Administratoransichten verwenden das aktuelle CMS-Gebietsschema über PHP intl NumberFormatter, daher sind Symbole und Trennzeichen für EUR, USD, GBP, JPY und alle lokalisiert wählbare Währung. Gateway-Anfragen verwenden dieselbe Präzision. PayPal-spezifische Nulldezimalzahl Anforderungen für HUF und TWD werden erfüllt.

Es gibt keine zusätzliche Abhängigkeit Composer. PHP ext-intl ist eine Plattformanforderung und muss es sein sowohl für den Webserver als auch für die CLI aktiviert. Das Plugin-Zustandsergebnis warnt, wenn es nicht verfügbar ist. Unterstützte Codes basieren auf den offiziellen PayPal-Währungsreferenz und SumUp Checkout API enum; Handelsland und Kontobeschränkungen können diese Anbieterlisten immer noch einschränken.

Der Produktdetailbildschirm zeigt die öffentliche Kauf-URL des Produkts:

Nachdem das Plugin aktiviert und einrichtungsbereit ist, zeigt die Blockauswahl des Seitenerstellers einen Plugin-eigenen Block Commerce Buy Button an.

Rempfohlener Workflow:

1. Öffnen Sie die Seite „Kunstwerk“, „Portfolio“ oder „Werke“ im Seitenersteller.
2. Fügen Sie Commerce Buy Button zum gewünschten Steckplatz hinzu.
3. Wählen Sie ein aktives Handelsprodukt aus.
4. Ändern Sie optional die Beschriftung, Ausrichtung und Preisanzeige der Schaltfläche.
5. Veröffentlichen Sie die Seite, wenn der umgebende Inhalt bereit ist.

Der Block rendert ein natives öffentliches Formular, das das ausgewählte Produkt hinzufügt zu:

Die Produktkauf-URL bleibt für Produktdetaillinks nützlich und macht eine Aktion zum Hinzufügen zum Warenkorb verfügbar. Der Checkout wird vom Warenkorb aus abgeschlossen, sodass erforderliche Kunden- und Lieferfelder nicht übersprungen werden können. Die Warenkorb-, Produktseiten- und Checkout-Statusansichten erweitern das CMS Öffentliches Layout, wobei die Kopf- und Fußzeilenbereiche der aktiven Site erhalten bleiben.

Fügen Sie keine vom Anbieter gehosteten Checkout-URLs in CMS-Inhalte ein. Sie werden pro Bestellung generiert und sollten nur aus dem Checkout-Startflow stammen.

Wenn ein Besucher einen Commerce-Block oder eine Produktseite verwendet:

1. Das Plugin prüft die Einrichtung, den Produktstatus, den verfolgten Lagerbestand und die Warenkorbwährung.
2. Das Produkt wird im sitzungsgestützten serverseitigen Warenkorb gespeichert; Es werden keine Zahlungsdaten erhoben.
3. Der Besucher gibt Namen, E-Mail, Lieferadresse und optional den Zusatz Telefon/Adresse an.
4. An der Kasse friert WebBlocks Commerce Kunden-/Liefermetadaten, lokalisierte Zeilentitel, Preise, Mehrwertsteuer und Gesamtbeträge für eine ausstehende Bestellung ein und reserviert den Lagerbestand atomar.
5. Im Test-Bestellmodus gelangt der Besucher direkt auf eine signierte Statusseite zurück und es wird kein Zahlungsanbieter kontaktiert. Bei PayPal oder SumUp erstellt der aktive Adapter einen gehosteten Checkout und leitet den Besucher weg.
6. Auf einer unterschriebenen Rücksendeseite kann zwar gemeldet werden, dass die Bearbeitung fortgesetzt wird, die Bestellung wird jedoch nie als bezahlt gekennzeichnet.
7. PayPal-Webhooks werden signaturverifiziert und genehmigte PayPal-Bestellungen werden erfasst.
8. SumUp-Statusbenachrichtigungen lösen einen erneuten Checkout-API-Abruf und einen vollständigen Bestell-/Transaktionsabgleich aus.
9. Nur das Ergebnis des verifizierten Anbieters verschiebt die Bestellung und den Zahlungsversuch nach paid/succeeded.

Webhook-Ereignisse werden nach Gateway und Ereignis-ID gespeichert, sodass eine wiederholte Zustellung idempotent ist.

Öffnen:

Bestellungen sind schreibgeschützt. Der Bestelldetailbildschirm zeigt:

• Bestellnummer
• Kundenname, erforderliche E-Mail-Adresse, optionale Telefonnummer und Lieferadresse, erfasst vom öffentlichen Warenkorb
• Bestellstatus
• Einzelposten
• Zahlungsversuche
• Gateway-Checkout- und Zahlungsreferenzen
• timestamps

Manuelle Statusbearbeitung, Rückerstattungen, Versandkostenberechnung und Erfüllungsworkflows werden absichtlich zurückgestellt. Kunden- und Lieferadressenerfassung, Mehrwertsteuer-Snapshots und Bestandsreservierung sind implementiert.

Wählen Sie Test order (no payment) in Commerce Settings aus, wenn ein Ladenbesitzer das überprüfen möchte Vervollständigen Sie das Storefront-Formular und den Auftragserfassungsablauf, ohne PayPal oder SumUp kontaktieren zu müssen. Die Öffentlichkeit Der Warenkorb kennzeichnet den Modus deutlich, erfordert Kunden- und Lieferdetails, erstellt eine ausstehende Bestellung, Reserviert verfolgte Lagerbestände, zeichnet einen ausstehenden gefälschten Zahlungsversuch zur Prüfungskontinuität auf und leitet ihn weiter auf eine unterschriebene Bestätigungsseite, aus der hervorgeht, dass keine Zahlung eingezogen wurde. Wechseln Sie zurück zu einem konfigurierten echten Anbieter, bevor Sie bezahlte Kundenbestellungen annehmen.

Verwenden Sie diese Checkliste, bevor Sie in den Live-Modus wechseln:

• WebBlocks Commerce ist installiert, aktiviert und bereit für die Einrichtung.
• Commerce Settings zeigt, dass das Schema bereit ist.
• Commerce Settings zeigt Gateway paypal.
• Die PayPal-Client-ID ist konfiguriert.
• Das PayPal-Client-Geheimnis ist konfiguriert.
• Die PayPal-Webhook-ID ist konfiguriert.
• Die Webhook-URL verwendet HTTPS und verweist auf /plugins/webblocks-commerce/webhooks/paypal.
• Ein Produkt ist aktiv und hat den erwarteten Preis/die erwartete Währung.
• Die Produktkauf-URL wird öffentlich geöffnet.
• Eine Seite mit einem Commerce Buy Button fügt das erwartete Produkt zu /plugins/webblocks-commerce/cart hinzu.
• Wenn Sie den Checkout starten, werden Sie zu PayPal weitergeleitet.
• Ein Sandbox-Käufer kann die Zahlung genehmigen.
• Der Besucher kehrt zur signierten Erfolgsseite zurück.
• Die Bestellung bleibt vor der Webhook-Bestätigung ausstehend.
• PayPal liefert CHECKOUT.ORDER.APPROVED.
• Der Webhook wurde erfolgreich überprüft.
• Die Erfassung der PayPal-Bestellung ist abgeschlossen.
• Die CMS-Bestellung lautet paid.
• Der Zahlungsversuch wird zu succeeded.
• Das erneute Senden desselben Webhooks führt nicht zu doppelten Zahlungsversuchen.
• Ungültige Webhook-Signaturen werden abgelehnt und kennzeichnen Bestellungen nicht als bezahlt.
• Auf Admin-Bildschirmen, öffentlichen Seiten, Protokollen, Screenshots oder Dokumenten wird kein PayPal-Geheimnis angezeigt.

• Der Sandbox-Händler wird im SumUp Dashboard ausgewählt.
• Die Händler-ID und der geheime Schlüssel sk_test_ gehören zu demselben Sandbox-Konto.
• Commerce Settings zeigt Gateway sumup, Sandbox-Modus und Checkout bereit.
• Der Test-API-Schlüssel und der Sandbox-Händlercode sind konfiguriert, aber der Schlüsselwert wird nicht gerendert.
• Ein Commerce-Block fügt das aktive EUR-Produkt zu /plugins/webblocks-commerce/cart hinzu.
• Menge, Mehrwertsteuer und Endbetrag sind vor dem Bezahlen korrekt.
• Beim Starten des Bezahlvorgangs wird eine ausstehende Bestellung erstellt und zu checkout.sumup.com weitergeleitet.
• Die SumUp-Checkout-Referenz stimmt mit der CMS-Bestellnummer überein.
• Durch den Abschluss einer Sandbox-Zahlung wird CHECKOUT_STATUS_CHANGED zu /plugins/webblocks-commerce/webhooks/sumup erstellt.
• Der Handler ruft den Checkout von SumUp ab und bestätigt eine erfolgreiche Transaktion.
• Die CMS-Bestellung wird zu paid und ihr Zahlungsversuch wird zu succeeded.
• Das erneute Senden derselben bezahlten Benachrichtigung führt nicht zu einem weiteren Zahlungsversuch.
• Ein nicht übereinstimmender Händlercode, eine nicht übereinstimmende Referenz, ein nicht übereinstimmender Betrag oder eine nicht übereinstimmende Währung markieren nie eine Bestellung als bezahlt.
• Fehlgeschlagene oder abgelaufene SumUp-Checkouts geben reserviertes Inventar frei.
• Die dokumentierte erfolgreiche Testkarte 4200 0000 0000 0091 läuft mit jedem zukünftigen Ablaufdatum ab und ein beliebiger dreistelliger CVV.

Vor dem Wechsel zu WEBBLOCKS_COMMERCE_PAYPAL_MODE=live:

• Bestätigen Sie, dass der Betreiber ein PayPal-Geschäftskonto besitzt, sofern PayPal dies erfordert.
• Erstellen Sie die Live-REST-App im PayPal Developer Dashboard oder wählen Sie sie aus.
• Ersetzen Sie die Sandbox-Client-ID, das Client-Geheimnis und die Webhook-ID durch Live-Werte.
• Konfigurieren Sie die Live-Webhook-URL mit der Produktions-HTTPS-Domäne.
• Bestätigen Sie, dass die Produktionsseite öffentliche PayPal-Webhook-Anfragen empfangen kann.
• RFühren Sie eine Live-Kaufabwicklung mit geringem Betrag durch, wenn dies für den Bediener akzeptabel ist.
• Überprüfen Sie die Bestellung im CMS-Administrator.

Sandbox- und Live-Anmeldeinformationen getrennt halten. Sandbox-Webhook-IDs im Live-Modus nicht wiederverwenden.

Wählen Sie für den SumUp-Live-Modus das verifizierte echte Händlerkonto aus und erstellen Sie ein separates sk_live_ Geheimer API-Schlüssel, verwenden Sie die Live-Händler-ID dieses Kontos, legen Sie WEBBLOCKS_COMMERCE_SUMUP_MODE=live fest, Aktualisieren Sie die Anwendungskonfiguration und führen Sie eine akzeptable Kleinbetragszahlung durch. Niemals wiederverwenden bzw Mischen Sie einen Sandbox-Händler, einen Testschlüssel, einen Live-Händler oder einen Live-Schlüssel.

Wenn auf der Kaufseite steht, dass der Checkout nicht bereit ist:

• Öffnen Sie Commerce Settings.
• Bestätigen Sie, dass das ausgewählte Gateway paypal oder sumup ist.
• Bestätigen Sie für PayPal, dass die Client-ID und das Client-Geheimnis konfiguriert sind.
• Bestätigen Sie für SumUp, dass API-Schlüssel und Händlercode konfiguriert sind.
• Bestätigen Sie, dass das Produkt aktiv ist und einen gültigen Preis hat.
• Bestätigen Sie, dass Plugin-Migrationen ausgeführt wurden.

Wenn der Checkout zu PayPal weitergeleitet wird, die Bestellung aber weiterhin aussteht:

• Bestätigen Sie, dass die PayPal-Webhook-URL korrekt ist.
• Bestätigen Sie, dass WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID mit dem in PayPal konfigurierten Webhook übereinstimmt.
• Bestätigen Sie, dass PayPal CHECKOUT.ORDER.APPROVED sendet.
• Bestätigen Sie, dass die Website von PayPal über HTTPS erreichbar ist.
• Bestätigen Sie, dass die Überprüfung der Webhook-Signatur nicht fehlschlägt.

Wenn ein Webhook abgelehnt wird:

• Überprüfen Sie, ob das Webhook-Ereignis vom passenden PayPal-Modus stammt.
• Stellen Sie sicher, dass Sandbox-Anmeldeinformationen nicht mit Live-Webhook-IDs vermischt werden.
• Überprüfen Sie, ob die Webhook-ID zur gleichen PayPal-REST-App gehört wie die Client-Anmeldeinformationen.

Wenn eine SumUp-Bestellung aussteht:

• Bestätigen Sie, dass die öffentliche HTTPS-URL /plugins/webblocks-commerce/webhooks/sumup erreichbar ist.
• Bestätigen Sie, dass der API-Schlüssel den Checkout lesen kann und zum konfigurierten Händlercode gehört.
• Bestätigen Sie, dass die Checkout-Referenz, der Betrag und die Währung weiterhin mit der CMS-Bestellung übereinstimmen.
• Confirm SumUp meldet PAID und enthält eine SUCCESSFUL-Transaktion.

Wenn die von SumUp gehostete Seite einen abgelaufenen oder fehlenden Checkout meldet, starten Sie einen neuen Checkout Warenkorb. Gehostete Checkout-Sitzungen laufen nach etwa 30 Minuten ab und ihre URLs dürfen nicht mit Lesezeichen versehen werden oder wiederverwendet werden.

Das aktuelle Plugin enthält noch nicht:

• Versand
• Gutscheine
• Abonnements
• Rückerstattungen von CMS
• Kundenkonten
• Fulfillment-Workflows
• Einrichten des Anbieterkontos (Zahlungsanmeldeinformationen können in den Commerce-Einstellungen bearbeitet werden)

Diese bleiben separate Funktionen und werden nicht in Anbieterintegrationen versteckt.

Auftragsstatus wird immer nur durch Support\Orders\OrderStateMachine geändert, niemals Rohes Update. Es erzwingt das zulässige Übergangsdiagramm (pending → paid|failed|cancelled|expired, paid → refunded) ist idempotent für erneut übermittelte Webhooks und sperrt die Auftragszeile auf diese Weise Racing-Gateway-Rückrufe können einen Übergang nicht doppelt anwenden.

Tracked stock (inventory_quantity not null) wird atomar reserviert, wenn der Checkout beginnt, Dadurch wird ein Überverkauf bei gleichzeitigen Käufern verhindert und bei Bedarf wieder in den Katalog aufgenommen Die Bestellung wird storniert, läuft ab, schlägt fehl oder wird erstattet. Produkte mit einem Nullwert inventory_quantity werden nicht verfolgt (unbegrenzt) und niemals dekrementiert.

Aabgebrochene pending Aufträge behalten ihre Reservierung, bis sie abgelaufen sind. Lauf php artisan webblocks-commerce:expire-stale-orders --minutes=30 auf einem Zeitplan zur Veröffentlichung des Lagerbestand durch Kassen, die der Käufer nie abgeschlossen hat. Verknüpfen Sie es mit dem Konsolenkernel der Host-App. zum Beispiel $schedule->command('webblocks-commerce:expire-stale-orders')->everyFifteenMinutes();.

Carts sind serverseitig, dauerhaft und in einer einzigen Währung verfügbar. In einem Einkaufswagen werden nur Produkte gespeichert Referenzen + Mengen; Preise und Mehrwertsteuer werden ausschließlich live aus dem aktuellen Katalog ermittelt an der Kasse auf der Bestellung eingefroren (StartCheckout::forCart), wodurch eine mehrzeilige Bestellung entsteht, reserviert den Lagerbestand atomar für jede Zeile und markiert den Warenkorb als converted. Das Gleiche hinzufügen Produkt verschmilzt Mengen; Das Hinzufügen einer anderen Währung oder eines höheren als des verfolgten Bestands wird abgelehnt.

Besucher verwenden den sitzungsgestützten öffentlichen Warenkorb ohne API-Token. Vor dem Bezahlen das öffentliche Formular erfordert den Namen, die E-Mail-Adresse, die Straße, die Postleitzahl, den Ort und den aus zwei Buchstaben bestehenden Ländercode des Kunden; Telefon und eine zweite Adresszeile bleiben optional. Die Details werden in den Warenkorb-/Bestellmetadaten gespeichert und angezeigt auf den Bestellstatus- und Admin-Bestelldetailbildschirmen.

Öffentliche Routen:

• GET /plugins/webblocks-commerce/cart – Überprüfen Sie die Warenkorbpositionen, die Mehrwertsteuer und den Gesamtbetrag
• POST /plugins/webblocks-commerce/cart/items/{product} – Fügen Sie ein Produkt aus einem Commerce-Block oder einer Kaufseite hinzu
• PATCH|DELETE /plugins/webblocks-commerce/cart/items/{product} – Menge ändern oder eine Zeile entfernen
• POST /plugins/webblocks-commerce/cart/checkout – Speichern Sie Kunden-/Lieferdetails, erstellen Sie die Bestellung und fahren Sie mit dem konfigurierten Gateway fort

Der öffentliche Warenkorb, die Kaufseite und die Checkout-Statusseiten erweitern das öffentliche CMS-Layout und rendern das Die eigenen header- und footer-Slots der Website runden ihren Inhalt ab und werden von der Homepage aus aufgelöst Support\PublicStorefrontShell. Ein in einem Shared Slot gehaltener Header funktioniert auf die gleiche Weise, also ändern Sie den Der Site-Header ändert damit auch die Storefront. Der Commerce Buy Button ist ein nativer Plugin-Block und Beiträge in den Warenkorb legen; Es ist kein vertrauenswürdiger HTML-Block erforderlich.

Alle Funktionen des Wagens sind über die interne API plugin verfügbar, die dem Plugin gehört. – integriert im CMS-interne API-Gruppe (/webadmin/api, Bearer-Token-Authentifizierung) über den apiRoutes()-Hook des Plugins, So erhalten KI-Agenten die gleichen Fähigkeiten, die das Admin-Panel den Menschen bietet. Endpunkte (Fähigkeit in Klammern):

• POST /webadmin/api/commerce/cart – einen Warenkorb erstellen (commerce.cart.write)
• GET /webadmin/api/commerce/cart/{token} – Warenkorb mit Live-Gesamtsummen lesen (commerce.cart.read)
• POST /webadmin/api/commerce/cart/{token}/items – {product_id, quantity} (commerce.cart.write) hinzufügen
• PATCH /webadmin/api/commerce/cart/{token}/items/{product} – {quantity} festlegen (0 entfernt) (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items/{product} – eine Zeile entfernen (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items – Leeren Sie den Warenkorb (commerce.cart.write)
• POST /webadmin/api/commerce/cart/{token}/checkout – gehosteten Checkout starten, gibt redirect_url (commerce.cart.write) zurück

Produkte und Bestellungen werden auf die gleiche Weise bereitgestellt (diese Endpunkte gehören dem Plugin, nicht dem CMS-Kern und sind nur vorhanden, wenn das Plugin aktiviert ist):

• GET|POST /webadmin/api/commerce/products, PATCH /webadmin/api/commerce/products/{id} — Katalog inkl. tax_class (commerce.read / commerce.products.write)
• GET /webadmin/api/commerce/orders, GET /webadmin/api/commerce/orders/{id} – schreibgeschützt, mit der vollständigen Netto-/Steuer-/Bruttoaufschlüsselung (commerce.orders.read)

Alle diese Selbstanzeigen: Während das Plugin aktiviert ist, werden sie in der CMS-API-Erkennung angezeigt (GET /webadmin/api _links, GET /webadmin/api/openapi.json Pfade und die Erkennungsanleitung) über den apiDiscovery()-Beitrag des Plugins und verschwinden, wenn das Plugin deaktiviert ist.

Es gibt kein separates Commerce-Token: Das Plugin verwendet das gemeinsame CMS-API-Token . Es ist commerce.*-Funktionen werden über apiCapabilities() zum bewilligbaren Satz des CMS beigetragen (Sie erscheinen als „Commerce“-Gruppe in der Token-Administrator-Benutzeroberfläche, während das Plugin aktiviert ist), also a Ein einzelnes Token mit den geringsten Rechten kann nur auf die Handelsfunktionen beschränkt werden.

Storefront-Produktinhalt nutzt das CMS-Site+Locale-System und nicht ein paralleles. Die Die Basisproduktzeile enthält den Standard-/Fallback-Wert title/description. eine Übersetzungszeile pro Gebietsschema (webblocks_commerce_product_translations, kodiert nach Produkt + CMS-Gebietsschema) überschreibt sie. Dies ist die Sprachachse des Admin-Panels content – verschieden von der Sprache des Admin-Panels UI Bleibt in den Dateien Laravel resources/lang.

ProductLocalizer löst den angezeigten Titel/die angezeigte Beschreibung für ein Gebietsschema auf und greift auf die Basis zurück. Einkaufswagen tragen ein locale, also Einkaufswagenzusammenfassungen und – ganz wichtig – den -Bestellzeilentitel-Snapshot bei checkout Verwenden Sie den lokalisierten Text, den der Käufer tatsächlich gesehen hat. Die öffentliche Kaufseite lokalisiert über a ?locale=<code>-Abfrage, Rückfall auf die Basis.

Bearbeiten Sie Übersetzungen im Admin-Produktformular (pro aktiviertem, nicht standardmäßigem Gebietsschema) oder über die API (Fähigkeit in Klammern):

• GET /webadmin/api/commerce/products/{product}/translations – Listenbasis + Übersetzungen (commerce.read)
• PUT /webadmin/api/commerce/products/{product}/translations/{locale} – Upsert {title?, description?} (commerce.products.write)
• DELETE /webadmin/api/commerce/products/{product}/translations/{locale} – Gebietsschema entfernen (commerce.products.write)