WebBlocks Commerce Betreiberhandbuch

Das WebBlocks-Commerce-Plugin installieren, konfigurieren, testen und betreiben.

WebBlocks Commerce Betreiberhandbuch

Dieses Handbuch erklärt, wie das erste WebBlocks-Commerce-MVP-Plugin installiert, konfiguriert und getestet wird. Das aktuelle Plugin unterstützt Hosted Checkout für ein einzelnes Produkt über PayPal. Es ist bewusst klein gehalten: Produktverwaltung, schreibgeschützte Bestellverwaltung, geheimnissichere Bereitschaftsdiagnosen, öffentliche Kauf-URLs, ein pluginbasierter Commerce-Buy-Button-Block, PayPal-Checkout-Weiterleitungen und PayPal-Webhook-Zahlungsbestätigung.

Das Plugin wird unter plugins/webblocks-commerce entwickelt. Es bleibt ein manuell installiertes Plugin-Paket und darf nicht in den CMS-Kern verschoben werden.

Aktueller Nutzerablauf

Ein CMS-Operator installiert und aktiviert WebBlocks Commerce.
Der Operator führt die Plugin-Migrationen über die Plugin-Detailseite aus.
Der Operator konfiguriert die PayPal-Zugangsdaten in der Installationsumgebung.
Der Operator öffnet Commerce Settings, um Checkout- und Webhook-Bereitschaft zu bestätigen.
Der Operator legt ein Commerce-Produkt an.
Die Produktdetailseite zeigt eine öffentliche Kauf-URL.
Der Operator fügt einer Seite einen Commerce Buy Button-Block hinzu und wählt das Produkt aus.
Ein Besucher startet den Checkout, genehmigt die Zahlung bei PayPal und kehrt zur Website zurück.
Die Bestellung bleibt ausstehend, bis der PayPal-Webhook die Zahlung verifiziert und einzieht.
Der Operator prüft die bezahlte Bestellung unter Commerce Orders.

Plugin installieren

Das Plugin-ZIP aus dem CMS-Repository bauen:

php plugins/webblocks-commerce/build-plugin.php

Danach den manuellen Plugin-Lebenszyklus abschließen:

System -> Plugins öffnen.
Das erzeugte WebBlocks-Commerce-ZIP hochladen.
Die Plugin-Detailseite prüfen.
Das Plugin aktivieren.
Plugin-Setup/Migrationen ausführen, wenn das Plugin Setup required meldet.
Bestätigen, dass der Zustand von setup-required auf ready wechselt.

Das Plugin besitzt die webblocks_commerce_*-Tabellen. Das Deaktivieren des Plugins setzt Routen, Menüs, Einstellungen und Verhalten außer Kraft. Das Deinstallieren eines deaktivierten, manuell hochgeladenen Plugins entfernt das hochgeladene Paket, erhält aber die plugineigenen Tabellen.

API-Automatisierung

Vertrauenswürdige Operator-Tools können den Setup- und Seitenbau-Workflow über /webadmin/api ausführen, wenn das CMS-API-Token explizite Plugin-, Commerce- und Content-Capabilities hat.

Plugin-Lebenszyklus:

GET /webadmin/api/plugins POST /webadmin/api/plugins/install POST /webadmin/api/plugins/webblocks-commerce/enable POST /webadmin/api/plugins/webblocks-commerce/setup POST /webadmin/api/plugins/webblocks-commerce/disable DELETE /webadmin/api/plugins/webblocks-commerce

Commerce-Ressourcen:

GET /webadmin/api/commerce/products POST /webadmin/api/commerce/products PATCH /webadmin/api/commerce/products/{product} GET /webadmin/api/commerce/orders GET /webadmin/api/commerce/orders/{order}

Die erforderlichen Token-Capabilities sind bewusst getrennt:

Plugin-Lebenszyklus: plugins.read, plugins.install, plugins.manage, plugins.setup und nur bei Bedarf plugins.uninstall
Produktarbeit: commerce.read und commerce.products.write
Bestellprüfung: commerce.orders.read
Seitenplatzierung: content.validate und content.apply

Der API-Ablauf zum Hinzufügen eines Kauf-Buttons:

webblocks-commerce installieren, aktivieren und einrichten.
Mit POST /webadmin/api/commerce/products ein aktives Produkt anlegen.
GET /webadmin/api/block-types oder GET /webadmin/api/content-contract lesen.
Über content validate/apply einen webblocks-commerce-buy-button-Block hinzufügen.
settings.commerce_product_id auf die vom Commerce-API zurückgegebene Produkt-ID setzen.

Der Commerce-Buy-Button-Block gehört dem Plugin. Bei deaktiviertem Plugin ist er aus der Block-Discovery ausgeblendet, und content validate/apply weist fehlende, unbekannte oder inaktive Produkt-IDs zurück. Die API erfasst keine Kartendaten; Besucher schließen den Checkout weiterhin über den öffentlichen Commerce-/PayPal-Ablauf ab.

PayPal-Konfiguration

WebBlocks Commerce nutzt die PayPal-REST-APIs. PayPal dokumentiert, dass REST-APIs OAuth-2.0-Zugriffstoken verwenden und API-Aufrufe eine Client-ID und ein Client-Secret gegen ein Zugriffstoken tauschen. Halten Sie das Client-Secret geheim und fügen Sie es niemals in CMS-Inhalte, Doku-Seiten, Screenshots oder Support-Logs ein.

Offizielle PayPal-Referenzen:

Diese Umgebungsvariablen in der CMS-Installation setzen:

WEBBLOCKS_COMMERCE_GATEWAY=paypal WEBBLOCKS_COMMERCE_PAYPAL_MODE=sandbox WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_ID=your-paypal-client-id WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_SECRET=your-paypal-client-secret WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID=your-paypal-webhook-id

WEBBLOCKS_COMMERCE_PAYPAL_MODE=live erst verwenden, nachdem Sandbox-Checkout und Webhook-Verifizierung getestet wurden.

PayPal-Sandbox einrichten

Im PayPal Developer Dashboard:

Apps & Credentials öffnen.
Die Standard-REST-API-App verwenden oder eine neue App anlegen.
Sandbox-Client-ID und Client-Secret in die Installationsumgebung kopieren.
Die Webhook-Einstellungen der App anlegen oder öffnen.
Diese Webhook-URL hinzufügen:

https://your-site.example/commerce/webhooks/paypal

Mindestens diese Ereignisse abonnieren:

CHECKOUT.ORDER.APPROVED PAYMENT.CAPTURE.COMPLETED

Die PayPal-Webhook-ID in WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID kopieren.
Für Checkout-Tests PayPal-Sandbox-Käufer- und -Verkäuferkonten verwenden.

Bei lokalen HTTPS-Tunneln die HTTPS-URL des Tunnels als Webhook-URL verwenden. In Produktion die endgültige öffentliche HTTPS-Site-URL verwenden.

Bereitschaftsdiagnosen

Öffnen:

/webadmin/plugins/webblocks-commerce/settings

Die Einstellungsseite zeigt bewusst nur sichere Diagnosen:

aktives Gateway
PayPal-Modus
Client-ID konfiguriert oder fehlend
Client-Secret konfiguriert oder fehlend
Webhook-ID konfiguriert oder fehlend
Checkout-Bereitschaft
Webhook-Bereitschaft
erwartete Webhook-URL
Plugin-Schema-Bereitschaft

Rohe PayPal-Client-Secrets, Token, Webhook-Payload-Signaturen oder Zahlungsdaten dürfen nicht angezeigt werden.

Produkt anlegen

Öffnen:

/webadmin/plugins/webblocks-commerce/products

Ein Produkt mit folgenden Feldern anlegen:

Titel
Slug
Beschreibung
Status
Preisbetrag
Währung
optionaler Lagerbestand
optionale SKU
optionaler Site-Scope

Den Produktstatus auf Active setzen, wenn es für den Checkout verfügbar sein soll. Entwurfs- und archivierte Produkte starten keinen öffentlichen Checkout.

Die Produktdetailseite zeigt die öffentliche Kauf-URL des Produkts:

/commerce/products/{slug}/buy

Kauf-Button in eine Seite einfügen

Nachdem das Plugin aktiviert und das Setup bereit ist, zeigt der Block-Picker des Page-Builders einen plugineigenen Commerce Buy Button-Block.

Empfohlener Ablauf:

Die Kunstwerk-, Portfolio- oder "Works"-Seite im Page-Builder öffnen.
Commerce Buy Button in den gewünschten Slot einfügen.
Ein aktives Commerce-Produkt auswählen.
Optional Button-Beschriftung, Ausrichtung und Preisanzeige anpassen.
Die Seite veröffentlichen, sobald der umgebende Inhalt fertig ist.

Der Block rendert einen öffentlichen Button, der auf Folgendes verlinkt:

/commerce/products/{slug}/buy

Die Kauf-URL des Produkts bleibt als Fallback für manuelle Navigationseinträge oder bestehende Linkfelder nützlich.

Keine PayPal-Hosted-Checkout-URLs in CMS-Inhalte einfügen. PayPal-Genehmigungs-URLs werden pro Bestellung erzeugt und dürfen nur aus dem Checkout-Startablauf stammen.

Checkout-Verhalten

Wenn ein Besucher die Kauf-URL anklickt:

Die Kaufseite prüft, ob das Plugin aktiviert, das Setup bereit, das Produkt aktiv und das Gateway konfiguriert ist.
Der Besucher startet den Checkout.
WebBlocks Commerce erzeugt eine ausstehende Bestellung, eine Bestellposition und einen ausstehenden Zahlungsversuch.
Der PayPal-Adapter erzeugt eine PayPal Order.
Der Besucher wird zur PayPal-Genehmigung weitergeleitet.
Der Besucher kehrt zu einer signierten Erfolgs- oder Abbruchseite zurück.
Die Erfolgsseite markiert die Bestellung nicht als bezahlt.
PayPal sendet einen Webhook an /commerce/webhooks/paypal.
WebBlocks Commerce verifiziert die Webhook-Signatur mit PayPal.
Bei CHECKOUT.ORDER.APPROVED zieht WebBlocks Commerce die PayPal-Bestellung ein.
Ist der Einzug abgeschlossen, wird die Bestellung als paid und der Zahlungsversuch als succeeded markiert.

Webhook-Ereignisse werden nach Gateway und Ereignis-ID gespeichert, sodass wiederholte Zustellungen idempotent sind.

Bestellungen prüfen

Öffnen:

/webadmin/plugins/webblocks-commerce/orders

Bestellungen sind im MVP schreibgeschützt. Die Bestelldetailseite zeigt:

Bestellnummer
Kunden-E-Mail, wenn PayPal eine zurückgibt
Bestellstatus
Positionen
Zahlungsversuche
Gateway-Checkout- und Zahlungsreferenzen
Zeitstempel

Manuelle Statusänderungen, Erstattungen, Versand, Steuern und Fulfillment-Workflows sind bewusst zurückgestellt.

Sandbox-Verifizierungscheckliste

Diese Checkliste vor dem Wechsel in den Live-Modus verwenden:

WebBlocks Commerce ist installiert, aktiviert und das Setup bereit.
Commerce Settings zeigt das Schema als bereit.
Commerce Settings zeigt paypal als Gateway.
Die PayPal-Client-ID ist konfiguriert.
Das PayPal-Client-Secret ist konfiguriert.
Die PayPal-Webhook-ID ist konfiguriert.
Die Webhook-URL nutzt HTTPS und zeigt auf /commerce/webhooks/paypal.
Ein Produkt ist aktiv und hat den erwarteten Preis / die erwartete Währung.
Die Kauf-URL des Produkts ist öffentlich erreichbar.
Eine Seite mit einem Commerce Buy Button rendert die erwartete Produktbeschriftung und den Kauflink.
Der Checkout-Start leitet zu PayPal weiter.
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 stellt CHECKOUT.ORDER.APPROVED zu.
Der Webhook wird erfolgreich verifiziert.
Der PayPal-Bestelleinzug wird abgeschlossen.
Die CMS-Bestellung wird paid.
Der Zahlungsversuch wird succeeded.
Das erneute Senden desselben Webhooks dupliziert keine Zahlungsversuche.
Ungültige Webhook-Signaturen werden abgewiesen und markieren Bestellungen nicht als bezahlt.
Kein PayPal-Secret erscheint in Admin-Ansichten, öffentlichen Seiten, Logs, Screenshots oder Doku.

Live-Modus-Checkliste

Vor dem Wechsel zu WEBBLOCKS_COMMERCE_PAYPAL_MODE=live:

Bestätigen, dass der Operator ein PayPal-Business-Konto besitzt, wo PayPal dies verlangt.
Die Live-REST-App im PayPal Developer Dashboard anlegen oder auswählen.
Sandbox-Client-ID, Client-Secret und Webhook-ID durch Live-Werte ersetzen.
Die Live-Webhook-URL mit der Produktions-HTTPS-Domain konfigurieren.
Bestätigen, dass die Produktionssite öffentliche PayPal-Webhook-Anfragen empfangen kann.
Wenn für den Operator akzeptabel, einen Live-Checkout mit geringem Betrag durchführen.
Die Bestellung im CMS-Admin prüfen.

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

Fehlerbehebung

Wenn die Kaufseite meldet, dass der Checkout nicht bereit ist:

Commerce Settings öffnen.
Bestätigen, dass das Gateway paypal ist.
Bestätigen, dass Client-ID und Client-Secret konfiguriert sind.
Bestätigen, dass das Produkt aktiv ist und einen gültigen Preis hat.
Bestätigen, dass die Plugin-Migrationen gelaufen sind.

Wenn der Checkout zu PayPal weiterleitet, die Bestellung aber ausstehend bleibt:

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

Wenn ein Webhook abgewiesen wird:

Prüfen, ob das Webhook-Ereignis aus dem passenden PayPal-Modus stammt.
Prüfen, ob Sandbox-Zugangsdaten nicht mit Live-Webhook-IDs vermischt sind.
Prüfen, ob die Webhook-ID zur selben PayPal-REST-App wie die Client-Zugangsdaten gehört.

Aktuelle Einschränkungen

Das MVP enthält noch nicht:

Warenkorb oder Checkout mit mehreren Produkten
Steuern
Versand
Gutscheine
Abonnements
Erstattungen aus dem CMS
Kundenkonten
Bestandsreservierung
Fulfillment-Workflows
PayPal-Live-Onboarding-UI im CMS

Diese Punkte sind bewusst zurückgestellt, damit die erste Plugin-Scheibe klein, sicher und überprüfbar bleibt.