Vendure Erweiterung | OCI und cXML PunchOut-Kataloge erstellen | PunchCommerce ![](//analytics.punchcommerce.de/matomo.php?idsite=1&rec=1) Vendure Erweiterung =================== PunchCommerce unterstützt [Vendure](https://vendure.io) über ein offizielles Community-Plugin im **Gateway Mode**. Das Plugin wurde vom Vendure-Team entwickelt und gemeinsam mit PunchCommerce getestet. --- Überblick --------- EigenschaftWert**Betriebsmodus**Gateway Mode**Protokolle**OCI, cXML, IDS Connect**Plugin**[`@vendure-community/punchout-gateway-plugin`](https://www.npmjs.com/package/@vendure-community/punchout-gateway-plugin)**Quellcode**[github.com/vendurehq/community-plugins](https://github.com/vendurehq/community-plugins/tree/main/packages/punchout-gateway-plugin)**Vendure-Dokumentation**[docs.vendure.io – PunchOutGatewayPlugin](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin)**Demo-Storefront**[github.com/vendurehq/punchcommerce-storefront-demo](https://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: 1. Das Beschaffungssystem sendet einen PunchOut-Request (cXML, OCI oder IDS Connect) an PunchCommerce. 2. 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. 3. Der Einkäufer authentifiziert sich über das Plugin, stöbert im Shop und füllt den Warenkorb. 4. Der Storefront übergibt den Warenkorb per `transferPunchOutCart`-Mutation an PunchCommerce. 5. 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](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin#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 ------------------------- FunktionStatus**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](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin). Die wesentlichen Schritte: **1. Plugin installieren** ```bash npm install @vendure-community/punchout-gateway-plugin ``` **2. Plugin registrieren** ```typescript 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](https://github.com/vendurehq/punchcommerce-storefront-demo) 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](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin#4-iframe-support-if-applicable). --- Plugin-Konfigurationsoptionen ----------------------------- OptionTypStandardBeschreibung`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](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin/punch-out-gateway-plugin-options). --- Fehlersuche ----------- ProblemMögliche UrsacheAuthentifizierung 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ückBestellung wurde bereits transferiert (Status `Transferred`). Pro Session ist nur ein Transfer möglich.Shop wird im iFrame nicht geladenSession-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. [ PunchCommerce® ist ein Produkt der ![Netzdirektion GmbH](https://www.punchcommerce.de/static/netzdirektion-logo.png "PunchCommerce® ist ein Produkt der netzdirektion | Gesellschaft für digitale Wertarbeit mbH") ](https://netzdirektion.de) [Feedback erwünscht - Ihre Meinung hilft uns, noch besser zu werden!](https://easy-feedback.de/umfrage/1883200/5FuM95 "Ihre Meinung hilft uns, noch besser zu werden!")