Eigene Integration

Diese Seite richtet sich an Entwickler, die einen Shop auf einer Plattform ohne punchout.dev-Plugin anbinden. Sie markieren den Warenkorb im Template und bauen, wenn Sie Auto-Login möchten, den Login-Endpunkt.

Beide Schritte sind optional. Das Script-Tag allein funktioniert in jedem Shop, siehe Das Tag einbinden und Warenkorb-Erkennung.

Bevor Sie beginnen

1. Stellen Sie im Tab Allgemein des Shops im Portal das Shopsystem auf Anderes.
2. Binden Sie das Script-Tag aus dem Tab Einbindung auf jeder Seite des Shops ein, am besten im Layout-Template:

<script async src="https://js.punchout.dev/pob.js" data-shop-id="pob_live_…"></script>

Das Tag muss mindestens auf der Seite laufen, auf der ein Punchout landet (dem Landing-Pfad), und auf der Warenkorbseite. Lassen Sie den Query-String der Landing-URL unverändert, auch über Weiterleitungen hinweg, denn der Punchout hängt davon ab.

1. Den Warenkorb-Container markieren

Umschließen Sie die Positionen der Warenkorbseite mit einem Element, das das Attribut data-punchout-cart trägt. Das Attribut braucht keinen Wert:

<div data-punchout-cart>
  <table class="cart-items">
    <!-- one row per line item: name, article number, quantity, unit price, line total -->
  </table>
</div>

So behandelt punchout.dev den Marker:

Regel	Detail
Der erste Treffer gewinnt	punchout.dev liest das erste Element mit dem Attribut auf der Seite. Geben Sie es einmal aus.
Er hat Vorrang	Ein Marker hat Vorrang vor einem Warenkorb-Container, der im Tab Warenkorb gespeichert ist. Mit Marker ist keine Warenkorb-Erkennung nötig.
Er bedeutet „diese Seite hat einen Warenkorb“	Steht der Marker während eines Punchouts auf einer Seite, liest punchout.dev dort sofort den Warenkorb.
Mengenfelder zählen	Eine Menge in einem Eingabefeld, etwa <input value="2">, wird wie sichtbarer Text gelesen. Die Inhalte von Passwort-, E-Mail-, Telefon- und Kartenfeldern werden nie gelesen.

Was hineingehört und was nicht:

• Nur auf der echten Warenkorbseite. Markieren Sie nie einen Mini-Warenkorb, einen Ausklapp-Warenkorb, einen Off-Canvas-Bereich oder ein Popup. Ein solches Element gibt es auf vielen Seiten und nur, solange es offen ist. Ein Marker daran lässt das Tag auf jeder Seite den Ausklapp-Warenkorb lesen.
• Die Positionen, nicht die ganze Seite. Lassen Sie Bestellübersicht, Gutscheinformulare, Versandkostenschätzung und Checkout-Button außerhalb. Die punchout.dev-Plugins umschließen die Positionstabelle, wo immer das Template der Plattform es zulässt.
• Bei leerem Warenkorb weglassen. Ein leerer Marker zählt trotzdem als Warenkorb, und das Panel endet mit „Analyse fehlgeschlagen.“.
• Im Browser gerenderte Warenkörbe sind kein Problem. Rendert JavaScript die Positionen Ihres Warenkorbs erst nach dem Laden, setzen Sie den Marker auf einen Container, der schon im Server-HTML steht. Das Tag wartet, bis der Warenkorb fertig geladen ist, bevor es ihn liest.

Prüfen Sie den Marker mit dem Setup-Selbsttest: Erzeugen Sie im Tab Einrichtung des Shops einen Setup-Link, öffnen Sie ihn auf der Warenkorbseite mit 2 oder 3 Produkten im Warenkorb und klicken Sie auf Warenkorb erkennen. Vor dem Klick sagt das Panel „Shop-Plugin erkannt — der Warenkorb ist bereits markiert.“, und das Ergebnis nennt die Quelle Shop-Plugin. Bestätigen Sie mit Ja, passt, um den Schritt Warenkorb erkannt abzuschließen.

2. Den Login-Endpunkt bauen (optional)

Auto-Login braucht in Ihrem Shop einen Endpunkt, der ein signiertes Login-Token annimmt, den richtigen Kunden anmeldet und weiterleitet. Was das für den Einkäufer bewirkt, steht unter Auto-Login.

Maßgeblich ist die Spezifikation des Login-Tokens (auf Englisch). Ihr Endpunkt muss:

1. GET <login path>?token=<token> annehmen.
2. Die Signatur des Tokens mit der Public-Key-Zeile aus dem Portal prüfen. Die Spezifikation beschreibt das Format des Tokens.
3. Die Prüfungen in der Reihenfolge der Spezifikation ausführen: Das Token stammt von punchout.dev und ist ein Login-Token, es wurde für Ihre Shop-ID ausgestellt, es liegt in seinem Gültigkeitsfenster von 120 Sekunden, es wurde noch nicht verwendet (jede Verwendung atomar festhalten, zum Beispiel über einen eindeutigen Datenbankschlüssel), und sein next ist ein relativer Pfad.
4. Genau einen Kunden zu customer.kind und customer.value finden und anmelden.
5. Unverändert auf next in Ihrem eigenen Shop weiterleiten, mit den Headern Cache-Control: no-store und Referrer-Policy: no-referrer.
6. Bei jedem Fehler ohne Anmeldung auf next weiterleiten. Der Punchout muss als Gast weiterlaufen.

Protokollieren Sie nie das Token oder customer.value.

Testvektor

Die Spezifikation des Login-Tokens beschreibt einen Testvektor, mit dem Sie Ihren Endpunkt prüfen:

Teil	Inhalt
Öffentlicher Schlüssel	Der öffentliche Schlüssel eines Testschlüssels, also der Wert, mit dem Ihr Endpunkt konfiguriert wird. Nur ein Testschlüssel, nie ein echter.
Token	Ein Token, signiert mit dem passenden Testschlüssel
Claims	Die dekodierte Payload dieses Tokens

Das Test-Token besteht die Prüfung für die Shop-ID pob_live_test0000000000000000 innerhalb seines Gültigkeitsfensters. Dieses Fenster liegt in der Vergangenheit. Geben Sie beim Test deshalb einen festen Zeitpunkt darin als „jetzt“ vor.

Die punchout.dev-Plugins setzen dieselben Prüfungen in PHP um. Ihr Quellcode liegt in den Plugin-Zips; jedes enthält ein bin/selftest.php, das ein Token prüfen kann.

3. Das Portal für Ihren Endpunkt konfigurieren

Für diesen Fall hat der Tab Auto-Login des Shops einen eigenen Adapter.

Feld	Wert
Auto-Login aktivieren	An
Adapter	Eigener Adapter
Login-Pfad	Der Pfad Ihres Endpunkts, beginnend mit / (nicht // oder /\), zum Beispiel /punchout/login
Kundenreferenz	Kunden-ID, Kundennummer oder E-Mail-Adresse. Sie kommt als customer.kind an (id, number oder email); Ihr Endpunkt entscheidet, womit er sie abgleicht.

Dann:

• Fügen Sie jede Zeile aus dem Abschnitt Öffentliche Schlüssel in die Konfiguration Ihres Endpunkts ein und akzeptieren Sie Tokens, die mit einer davon signiert sind. Die Spezifikation beschreibt das Format der Zeilen.
• Geben Sie jedem Einkäufer-Zugang im Tab Einkäufer eine Shop-Kundenreferenz.
• Setzen Sie den Landing-Pfad im Tab Allgemein auf den vollständigen Pfad Ihrer Warenkorbseite. Er wird zum next des Tokens.

Der Login-Pfad wird an den ersten Eintrag des Shops unter Erlaubte Origins im Tab Allgemein angehängt. Der Adapter hält nur fest, welchen Endpunkt der Shop betreibt, und ändert nichts am Token.

Verwandte Seiten

• Shop-Plugins für Shopware, WooCommerce und Magento
• Auto-Login, einschließlich der Ablehnungsgründe, die die Plugins protokollieren
• Fehlersuche