Good to know PunchOut für Vendure einrichten – der komplette Guide

Wenn Sie noch nicht wissen, was PunchOut ist oder wie der Gateway Mode funktioniert: Lesen Sie zuerst unsere Ankündigung der Vendure-Integration – dort erklären wir den Ablauf auf einen Blick.

Voraussetzungen

Bevor Sie starten, brauchen Sie drei Dinge:

• Einen laufenden Vendure-Shop (v3.x oder neuer) mit einem Storefront, das Sie anpassen können.
• Einen PunchCommerce-Account. Noch keinen? 30 Tage kostenlos testen.
• Die Information, welches Protokoll Ihr Kunde erwartet – in der Regel cXML (SAP Ariba, Coupa, Jaggaer), OCI (SAP-Umgebungen im DACH-Raum) oder IDS Connect (deutscher Großhandel, z. B. SHK und Elektro).

Teil 1: Vendure-Plugin installieren und konfigurieren

Schritt 1 – Plugin installieren

Installieren Sie das offizielle Community-Plugin über den Paketmanager Ihrer Wahl:

npm install @vendure-community/punchout-gateway-plugin

Schritt 2 – Plugin in die Vendure-Konfiguration aufnehmen

Fügen Sie das Plugin in Ihre vendure-config.ts ein:

import { PunchOutGatewayPlugin } from '@vendure-community/punchout-gateway-plugin';

export const config: VendureConfig = {
    plugins: [
        PunchOutGatewayPlugin.init({
            // Standardwerte funktionieren sofort –
            // optionale Anpassungen siehe unten
        }),
    ],
};

Das Plugin bringt alles mit, was die Integration braucht: eine eigene Authentifizierungsstrategie für PunchOut-Sessions, eine aktive Warenkorb-Zuordnung pro Session und eine GraphQL-Mutation für den Warenkorb-Transfer.

Schritt 3 – Optionale Konfiguration

In den meisten Fällen reichen die Standardwerte. Drei Optionen können Sie bei Bedarf anpassen:

Ein Beispiel für das Product-Field-Mapping: Angenommen, Sie verkaufen sowohl Einzelteile als auch Schüttgut. Dann können Sie die Mengeneinheit pro Produkt aus einem Vendure-Custom-Field lesen:

PunchOutGatewayPlugin.init({
    productFieldMapping: {
        unit: { customField: 'punchOutUnit', default: 'PCE' },
        unit_name: { customField: 'punchOutUnitName', default: 'Piece' },
        weight: { customField: 'productWeight', default: 0 },
    },
})

Wenn das Custom-Field bei einem Produkt leer ist, greift der konfigurierte Fallback-Wert – ein Prinzip, das Sie auch aus dem Field-Mapping in PunchCommerce kennen.

Schritt 4 – Kunden in Vendure zuordnen

Das Plugin fügt dem Vendure-Kundenobjekt ein neues Feld hinzu: „PunchOut Customer ID (uID)". Öffnen Sie den Kunden im Vendure-Admin und tragen Sie dort die gleiche Kennung ein, die Sie später im PunchCommerce-Dashboard als „Customer Identification" vergeben.

Über dieses Feld erkennt das System, welcher Vendure-Kunde zu welcher PunchOut-Session gehört.

Teil 2: Storefront anpassen

Da Vendure headless arbeitet, braucht Ihr Frontend drei Anpassungen. Wir beschreiben hier das Konzept – die vollständigen Code-Beispiele mit GraphQL-Mutations finden Sie in der offiziellen Plugin-Dokumentation.

Noch schneller geht es mit dem fertigen Demo-Storefront des Vendure-Teams: vendurehq/punchcommerce-storefront-demo. Es enthält alle drei Anpassungen als funktionierende Referenz-Implementierung.

Anpassung 1 – PunchOut-Landing-Page

Erstellen Sie eine Route (z. B. /punchout), an die PunchCommerce den Einkäufer weiterleitet. Diese Seite muss drei Dinge tun:

• Die Parameter sID (Session-ID) und uID (Kunden-Kennung) aus der URL lesen.
• Die sID für die Dauer der Session speichern – am besten in sessionStorage, damit parallele Browser-Tabs eigene Sessions behalten.
• Die authenticate-Mutation mit der PunchOut-Strategie aufrufen und bei Erfolg auf die Shop-Startseite weiterleiten.

Anpassung 2 – Session-gebundener Warenkorb

Alle Warenkorb-Operationen – Artikel hinzufügen, Menge ändern, entfernen, Warenkorb anzeigen – müssen den Parameter activeOrderInput mit der aktuellen sID mitgeben. Das stellt sicher, dass der Warenkorb der richtigen PunchOut-Session zugeordnet bleibt.

Das betrifft die Mutations addItemToOrder, adjustOrderLine, removeOrderLine sowie die Query activeOrder. Ohne diesen Parameter landen Artikel im regulären Warenkorb statt in der PunchOut-Session.

Anpassung 3 – Warenkorb-Transfer statt Checkout

Ersetzen Sie den normalen Checkout-Flow durch einen „Warenkorb übertragen"-Button. Dieser ruft die Mutation transferPunchOutCart auf und übergibt die sID. Nach erfolgreichem Transfer wechselt die Bestellung in Vendure in den Status „Transferred" – der Warenkorb wird archiviert, eine neue Session startet mit einem leeren Warenkorb.

Hinweis: iFrame-Modus

Wenn das Beschaffungssystem Ihren Shop in einem iFrame einbettet (statt in einem neuen Fenster zu öffnen), müssen Sie zusätzlich die Session-Cookies auf SameSite=None; Secure setzen und den X-Frame-Options-Header während PunchOut-Sessions entfernen. Details dazu finden Sie in der Plugin-Dokumentation.

Teil 3: PunchCommerce-Dashboard konfigurieren

Schritt 1 – Kunden anlegen

Erstellen Sie im PunchCommerce-Dashboard einen neuen Kunden. Vergeben Sie eine eindeutige „Customer Identification" – das ist die uID, die auch im Vendure-Admin beim Kundenobjekt hinterlegt sein muss.

Schritt 2 – Entry Address eintragen

Tragen Sie die URL Ihrer PunchOut-Landing-Page ein, z. B. https://ihr-shop.de/punchout. PunchCommerce leitet den Einkäufer an diese Adresse weiter und hängt die Parameter sID und uID automatisch an.

Schritt 3 – Protokoll wählen und Field-Mapping konfigurieren

Wählen Sie das Protokoll, das Ihr Kunde erwartet:

• cXML für SAP Ariba, Coupa oder Jaggaer
• OCI für SAP-Beschaffungssysteme im DACH-Raum
• IDS Connect für den deutschen Großhandel (SHK, Elektro) und Handwerkersoftware

Anschließend ordnen Sie im Field-Mapping die Shop-Attribute (EAN, SKU, Kurzbeschreibung, Preis) den PunchOut-Feldern zu. Das funktioniert per Drag & Drop. Wenn ein Pflichtfeld im Shop leer ist, greift ein konfigurierbarer Fallback-Wert – so bleibt die Datenqualität gewährleistet, ohne dass Sie Ihr Quellsystem anpassen müssen.

Schritt 4 – Testen mit dem PunchOut-Simulator

Bevor Sie auf Ihren Kunden zugehen: Nutzen Sie den integrierten PunchOut-Simulator in PunchCommerce. Er simuliert eine komplette Session – von der Weiterleitung über den Warenkorb bis zum Transfer zurück ins Beschaffungssystem. Sie sehen sofort, ob Mapping, Preise und Produktdaten korrekt ankommen.

Das spart erfahrungsgemäß mindestens eine Abstimmungsrunde mit der IT-Abteilung Ihres Kunden.

Zusammenfassung: Was wo passiert

Die Konfiguration auf der PunchCommerce-Seite dauert unter 30 Minuten. Der größte variable Faktor ist die Storefront-Anpassung – hier beschleunigt das Demo-Storefront den Start erheblich.

Nächster Schritt

Sie möchten die Integration an Ihrem konkreten Setup durchsprechen – oder direkt loslegen? Wir zeigen Ihnen in einem kurzen Gespräch, wie die Einrichtung in der Praxis aussieht.

Jetzt Termin buchen →

Wenn Sie Fragen oder Anregungen haben, schreiben Sie uns einfach eine E-Mail an hallo@punchcommerce.de oder rufen Sie uns an unter 06142 / 953 80 - 60. Wir freuen uns über Ihr Feedback!