PunchCommerce unterstützt Vendure über ein offizielles Community-Plugin im Gateway Mode. Das Plugin wurde vom Vendure-Team entwickelt und gemeinsam mit PunchCommerce getestet.

Überblick

Eigenschaft	Wert
Betriebsmodus	Gateway Mode
Protokolle	OCI, cXML, IDS Connect
Plugin	`@vendure-community/punchout-gateway-plugin`
Quellcode	github.com/vendurehq/community-plugins
Vendure-Dokumentation	docs.vendure.io – PunchOutGatewayPlugin
Demo-Storefront	github.com/vendurehq/punchcommerce-storefront-demo
Mindestversion Vendure	3.x

Funktionsweise

PunchCommerce fungiert als Protokoll-Gateway zwischen dem Beschaffungssystem des Einkäufers und dem Vendure-Shop. Der Ablauf:

Das Beschaffungssystem sendet einen PunchOut-Request (cXML, OCI oder IDS Connect) an PunchCommerce.
PunchCommerce verarbeitet den Request und leitet den Einkäufer an die konfigurierte Entry Address des Vendure-Storefronts weiter. Dabei werden die Parameter sID (Session-ID) und uID (Kunden-Kennung) als Query-Parameter übergeben.
Der Einkäufer authentifiziert sich über das Plugin, stöbert im Shop und füllt den Warenkorb.
Der Storefront übergibt den Warenkorb per transferPunchOutCart-Mutation an PunchCommerce.
PunchCommerce übersetzt den Warenkorb in das Zielformat des Beschaffungssystems.

Unterstützte PunchCommerce-Funktionen

Protokolle

Alle drei PunchCommerce-Protokolle werden unterstützt:

OCI – für SAP-Umgebungen und ERP-Systeme im DACH-Raum
cXML – für SAP Ariba, Coupa, Jaggaer und andere E-Procurement-Netzwerke
IDS Connect – für den deutschen Großhandel (SHK, Elektro) und Handwerkersoftware

Die Protokollwahl erfolgt in der Kundenkonfiguration im PunchCommerce-Dashboard. Das Vendure-Plugin ist protokollunabhängig – die Übersetzung findet vollständig auf PunchCommerce-Seite statt.

Field-Mapping

Das Field-Mapping im PunchCommerce-Dashboard funktioniert mit der Vendure-Integration wie gewohnt:

Zuordnung von Shop-Attributen (EAN, SKU, Beschreibungen, Preise) zu PunchOut-Feldern per Drag & Drop
Transformationen (AppendTo, If-Bedingungen)
Fallback-Werte für leere Pflichtfelder

Zusätzlich unterstützt das Vendure-Plugin ein eigenes Product-Field-Mapping auf Plugin-Seite. Damit lassen sich PunchOut-spezifische Felder (Mengeneinheit, Verpackungseinheit, Gewicht) auf Vendure-Custom-Fields der ProductVariant mappen. Details dazu: Vendure-Dokumentation – Product Field Mapping.

PunchOut-Simulator

Der PunchOut-Simulator in PunchCommerce kann für die Vendure-Integration verwendet werden. Er simuliert eine vollständige Session (Weiterleitung → Authentifizierung → Warenkorb-Transfer) und eignet sich zur Validierung der Konfiguration, bevor die Anbindung mit dem Beschaffungssystem des Kunden getestet wird.

Parallele Sessions

Das Plugin ordnet Warenkörbe über eine eigene ActiveOrderStrategy der jeweiligen PunchOut-Session (sID) zu. Mehrere gleichzeitige Sessions desselben Kunden sind möglich – jede mit einem eigenen, isolierten Warenkorb.

Warenkorb-Mapping

Das Plugin übergibt die Warenkorbpositionen als multipart/form-data an den PunchCommerce-Endpunkt /gateway/v3/return. Dabei gelten folgende Konventionen:

Preise: price = Bruttopreis, price_net = Nettopreis
Alle Geldbeträge werden von Vendures Integer-Cent-Format in Dezimalwerte umgerechnet (÷ 100)
Versandkosten werden als separate Position mit type: 'shipping-costs' übertragen (konfigurierbar über shippingCostMode)
Produktbeschreibungen: description = Plaintext (HTML entfernt), description_long = mit HTML

Order Lifecycle

Nach einem erfolgreichen Warenkorb-Transfer wechselt die Bestellung in Vendure in den Status Transferred. Die Bestellung wird inaktiv, der Warenkorb bleibt zur Nachverfolgung im Vendure-Admin erhalten.

Derzeit nicht unterstützt

Funktion	Status
Actions (`detail`, `search`, `background-search`)	Geplant für ein kommendes Release
Order-Hub	Nicht unterstützt
Hosted Catalog	Nicht anwendbar (Vendure stellt den Shop bereit)

Einrichtung

Die Einrichtung gliedert sich in zwei Bereiche: die Plugin-Installation in Vendure und die Kundenkonfiguration im PunchCommerce-Dashboard.

Vendure-Seite

Die vollständige Anleitung zur Plugin-Installation, Konfiguration und Storefront-Anpassung finden Sie in der Vendure-Dokumentation. Die wesentlichen Schritte:

1. Plugin installieren

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

2. Plugin registrieren

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

export const config: VendureConfig = {
    plugins: [
        PunchOutGatewayPlugin.init({}),
    ],
};

3. Kunden-Zuordnung herstellen

Das Plugin fügt dem Vendure-Customer-Objekt ein Custom Field „PunchOut Customer ID (uID)" hinzu. Der Wert muss mit der „Customer Identification" im PunchCommerce-Dashboard übereinstimmen.

4. Storefront anpassen

Da Vendure headless arbeitet, erfordert der Storefront drei Anpassungen:

Landing Page (/punchout): Liest sID und uID aus der URL, speichert die sID in sessionStorage und führt die Authentifizierung über die authenticate-Mutation mit der punchout-Strategie durch.
Session-gebundener Warenkorb: Alle Order-Mutations und -Queries müssen activeOrderInput: { punchout: { sID } } übergeben.
Warenkorb-Transfer: Ein Button ruft die Mutation transferPunchOutCart(sID) auf und ersetzt den normalen Checkout-Flow.

Eine funktionierende Referenz-Implementierung steht als Demo-Storefront zur Verfügung.

PunchCommerce-Seite

1. Kunden anlegen

Erstellen Sie im PunchCommerce-Dashboard einen neuen Kunden. Die „Customer Identification" muss mit dem Wert im Vendure-Custom-Field PunchOut Customer ID (uID) übereinstimmen.

2. Entry Address konfigurieren

Tragen Sie die URL der PunchOut-Landing-Page Ihres Vendure-Storefronts ein, z. B.:

https://ihr-shop.de/punchout

PunchCommerce hängt die Parameter ?sID={UUID}&uID={Kennung} automatisch an.

3. Protokoll wählen

Wählen Sie das Protokoll, das das Beschaffungssystem des Kunden erwartet:

cXML – SAP Ariba, Coupa, Jaggaer
OCI – SAP-Beschaffungssysteme
IDS Connect – Handwerkersoftware, SHK- und Elektro-Großhandel

4. Field-Mapping konfigurieren

Ordnen Sie die relevanten Shop-Attribute den PunchOut-Feldern zu. Konfigurieren Sie Fallback-Werte für Pflichtfelder, die im Shop leer sein könnten.

5. Konfiguration testen

Nutzen Sie den PunchOut-Simulator, um eine vollständige Session zu simulieren und die korrekte Übertragung von Produktdaten, Preisen und Versandkosten zu prüfen.

iFrame-Modus

Wenn das Beschaffungssystem den Vendure-Storefront in einem iFrame einbettet, sind auf Storefront-Seite zwei zusätzliche Anpassungen erforderlich:

Session-Cookies auf SameSite=None; Secure setzen
X-Frame-Options-Header während PunchOut-Sessions entfernen

Details: Vendure-Dokumentation – iFrame Support.

Plugin-Konfigurationsoptionen

Option	Typ	Standard	Beschreibung
`apiUrl`	`string`	`https://www.punchcommerce.de`	Basis-URL der PunchCommerce-Instanz. Nur bei Staging- oder Self-Hosted-Setups ändern.
`shippingCostMode`	`'all' \\| 'nonZero' \\| 'none'`	`'nonZero'`	Steuert, wann Versandkosten als Position übertragen werden: immer, nur bei Betrag > 0, oder nie.
`productFieldMapping`	`ProductFieldMappings`	–	Mapping von PunchOut-Produktfeldern auf statische Werte oder Vendure-Custom-Fields.

Vollständige Referenz: PunchOutGatewayPluginOptions.

Fehlersuche

Problem	Mögliche Ursache
Authentifizierung schlägt fehl (`InvalidCredentialsError`)	`uID` im Vendure-Custom-Field stimmt nicht mit der Customer Identification in PunchCommerce überein.
Warenkorb ist leer nach Artikelzugabe	`activeOrderInput` wird nicht an die Order-Mutation übergeben – Artikel landen im regulären Warenkorb statt in der PunchOut-Session.
Transfer gibt Fehler zurück	Bestellung wurde bereits transferiert (Status `Transferred`). Pro Session ist nur ein Transfer möglich.
Shop wird im iFrame nicht geladen	Session-Cookies sind nicht auf `SameSite=None; Secure` gesetzt oder `X-Frame-Options`-Header blockiert das Embedding.
Parallele Sessions überschreiben sich	`sID` wird in einem Cookie statt in `sessionStorage` gespeichert. Cookies sind domainweit, `sessionStorage` ist tab-spezifisch.

Vendure Erweiterung