# Eigene Integration

Wie Entwickler von Shops auf anderen Plattformen den Warenkorb mit data-punchout-cart markieren und mit dem eigenen Adapter einen Login-Endpunkt für Auto-Login bauen.

URL: https://punchout.dev/de/docs/plugins/custom/

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](https://punchout.dev/de/docs/getting-started/install-the-tag/) und [Warenkorb-Erkennung](https://punchout.dev/de/docs/getting-started/cart-detection/).

## 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:

```html
<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:

```html
<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](https://punchout.dev/de/docs/plugins/auto-login/).

Maßgeblich ist die [Spezifikation des Login-Tokens](https://punchout.dev/de/docs/plugins/custom/login-token/) (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](https://punchout.dev/de/docs/plugins/custom/login-token/) 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](https://punchout.dev/de/docs/plugins/) für Shopware, WooCommerce und Magento
- [Auto-Login](https://punchout.dev/de/docs/plugins/auto-login/), einschließlich der Ablehnungsgründe, die die Plugins protokollieren
- [Fehlersuche](https://punchout.dev/de/docs/troubleshooting/)