Dieses Dokument beschreibt, was die individuelle E-Commerce-Implementierung bereitstellen muss, damit sie in den Admin-Feldern konfiguriert werden kann:

• „Custom Clone Endpoint“
• „Custom Categories Endpoint“

Außerdem beschreibt es:

• Autologin-/SSO-Verhalten
• Auto-Post-Formular (Warenkorb zurück an die Middleware posten)

Es enthält erforderliche HTTP-Verben, Parameter, Parameterbedeutungen und mögliche Werte, erwartete Antworten (Erfolg & Fehler) sowie konkrete Beispiele.

1) Custom Clone Endpoint
Wird von der Middleware verwendet, um:

• Eine neue Bestellung/Sitzung im Remote-Store zu erstellen („create“-Flow), oder
• Eine bestehende Bestellung/einen bestehenden Warenkorb zu bearbeiten/zu befüllen (EDIT-Flow). Der Endpunkt muss entweder Folgendes zurückgeben:
• Eine SSO-URL, die den Käufer mit einem Einmal-Token auf der Remote-Website anmeldet. Dort kann der Nutzer – wenn es sich um den EDIT-Flow handelt und der Warenkorb befüllt ist – zum Warenkorb weitergeleitet werden, kann zum ausgewählten Produkt weitergeleitet werden (falls dies während des „create“-Flows übermittelt wird), andernfalls wird er zur Startseite weitergeleitet.

Empfohlener URL-Pfad (Beispiel):

• POST https://your-store.example.com/api/punchout/clone

HTTP-Verb

• POST (verpflichtend). Verwenden Sie einen JSON-Body (application/json). Die Middleware ruft POST auf.

Request Body (JSON)
Basisfelder (immer vorhanden)

• • username (string) — Benutzername im E-Commerce des zu klonenden Nutzers, um einen neuen, an die Punchout-Session gebundenen Nutzer zu erzeugen.
  • api_key (string) — API-Key, der mit dem in Punchout Rocket für das aktuelle E-Commerce hinterlegten übereinstimmen muss
  • end_customer_id (integer) – Endkundenkennung in der Punchout-Rocket-Middleware für das E-Commerce der aktuellen Punchout-Anfrage
  • session_token (string) — eindeutiges Buyer-Cookie im Fall von CXML oder eindeutige UUID o. Ä. im Fall von OCI
  • operation (string) — „create“ oder „edit“ oder „inspect“ im Fall von CXML, „create“ im Fall von OCI. Im Fall von „edit“ oder „inspect“ kann eine Liste von Warenkorbpositionen übergeben werden
  • gateway_base_url (string) — URL der Middleware, an die der Warenkorb später gepostet werden soll

Protokollspezifische Ergänzungen

• Wenn das aufgelöste Protokoll CXML ist, können diese zusätzlichen Felder hinzugefügt werden:

selected_item (object) — Identifikation des Produkts, zu dem der Nutzer weitergeleitet werden soll; optional im Fall der Operation „create“:

• supplier_part_id (string) — Kennung der SKU (Produktcode) im E-Commerce (falls vorhanden)
• supplier_part_auxiliary_id (string) — Kennung der Produkt-ID im E-Commerce (falls vorhanden)

Beispiel: json

{  
  „selected_item“:  
  {  
  „supplier_part_id“: „ABC-001“,  
  „supplier_part_auxiliary_id“: „19852“  
  }  
}

cart_items (array) — die Liste der Warenkorbpositionen, die dem Warenkorb der aktuellen Session erneut hinzugefügt werden sollen. Jedes Element in cart_items enthält typischerweise:

• sku (string) — Kennung der SKU (Produktcode) im E-Commerce (falls vorhanden)
• product_id (string) — Kennung der Produkt-ID im E-Commerce (falls vorhanden)
• quantity (integer) – Menge des Artikels im Warenkorb
• price (Dezimalzahl mit Punkt als Dezimaltrennzeichen) – Stückpreis des Artikels im Warenkorb. Beachten Sie, dass beim Weiterleiten zum Warenkorb der aktuelle Preis aktualisiert wird
• description (string) – Beschreibung des Produkts
• currency (string) — ISO-4217-Währungscode

Beispiel-Payload (create, CXML, Selected Item vorhanden)

{
  „username“: „buyer123“,
  „api_key“: „site-api-key-abc“,
  „session_token“: „sess-012345“,
  „operation“: „create“,
  „end_customer_id“ : 2,
  „gateway_base_url“: „https://middleware.example.com“,
  „selected_item“: {
  „supplier_part_id“: „X-100“,
  „supplier_part_auxiliary_id“: „19853“
  }
}

Beispiel-Payload (edit, CXML, Warenkorb befüllt)

{
  „username“: „buyer123“,
  „api_key“: „site-api-key-abc“,
  „session_token“: „sess-67890“,
  „operation“: „edit“,
  „end_customer_id“ : 2,
  „gateway_base_url“: „https://middleware.example.com“,
  „cart_items“: [
  {
  „sku“: „ABC-001“,
  „product_id“: „19852“,
  „quantity“: 2,
  „price“: 15.95,
  „description“ : „Beispielbeschreibung“,
  „currency“: „EUR“
  },
  {
  „sku“: „XYZ-002“,
  „product_id“: „19854“,
  „quantity“: 1,
  „price“: 249.00,
  „description“ : „Eine weitere Beispielbeschreibung“,
  „currency“: „EUR“
  }
  ]
}

Erfolgsantwort(en)
Option A — Eine direkte SSO-URL bereitstellen (JSON) – HTTP 200 – Content-Type: application/json – Body:

{
  „status“:“success“,
  „sso_url“:“https://your-store.example.com/sso?token=eyJ…“
}

Verhalten: Die Middleware leitet den Käufer zu sso_url (GET) weiter und sendet sie im Fall von CXML an die Beschaffungsplattform zurück oder im Fall von OCI direkt. Der Remote-Store muss das Token konsumieren, den Nutzer anmelden und dann:

• Wenn die Aktion „edit“ oder „inspect“ ist: Die Remote-Website sollte die Warenkorbinformationen lesen und den Warenkorb befüllen, sodass der Nutzer im Store auf der Warenkorbseite landet, mit Artikeln im Warenkorb in den passenden Mengen.
• Wenn die Aktion „create“ ist: Die Remote-Website sollte zum ausgewählten Artikel weiterleiten, sofern übergeben und gefunden; andernfalls landet der Nutzer einfach im Storefront

Fehlerantworten
HTTP 400 — Bad Request (fehlende Pflichtfelder) json

{  
  „status“:“error“,  
  „error_code“:“invalid_request“,  
  „message“:“Missing field: action“  
}

HTTP 422 — SSO kann nicht erstellt werden (z. B. fehlende Käuferidentität) json

{  
  „status“:“error“,  
  „error_code“:“sso_unavailable“,  
  „message“:“Cannot generate SSO token for this user“  
}

HTTP 500 — Interner Fehler json

{  
  „status“:“error“,  
  „error_code“:“internal_error“  
}

2) Autologin-&-SSO-Workflow (wie der Käufer angemeldet und der Warenkorb befüllt wird)
Bei einer Antwort mit sso_url sollte der Store:

• Das Token konsumieren (damit es nicht zweimal verwendet werden kann) und den Käufer mit dem geklonten Nutzer anmelden.
• Nach dem Login:
  • Wenn die Aktion „edit“ ist:
    • Den Warenkorb des Nutzers mit den exakt bereitgestellten Produkten und Mengen als Warenkorbpositionen befüllen.
    • Den Nutzer zur Warenkorb-/Checkout-Seite weiterleiten, wo er vor dem Checkout bearbeiten kann.
  • Wenn die Aktion „create“ ist:
    • Optional zum als Selected Item angegebenen Produkt weiterleiten. Wenn die Middleware kein Selected Item bereitgestellt hat oder es im E-Commerce nicht mehr gefunden wird, landet der Nutzer auf der Store-Startseite.

Sicherheit:

• Nur HTTPS verwenden.
• Tokens müssen nur einmal verwendbar sein.

3) Auto-Post-Formular (Warenkorbübertragung)
Wenn der Store den Warenkorb/die Warenkorbbestätigung an die Middleware zurücksenden muss (nach SSO-Login, Hinzufügen von Produkten zum Warenkorb oder Bearbeiten), wenn der Nutzer auf die Schaltfläche klickt (normalerweise im Warenkorb), die den Checkout starten sollte, dann sollte er stattdessen – im Fall geklonter Nutzer von Punchout-Sessions – ein Formular (Content-Type: application/x-www-form-urlencoded) an die Middleware-URL posten, die in der Anfrage an den Clone-Endpunkt im relativen Pfad „/start-sso-checkout“ übermittelt wurde. Bevorzugte UX: Der Store liefert eine HTML-Seite mit einem Loader aus, die ein verborgenes Formular automatisch an den Middleware-Endpunkt sendet (dadurch ist SSO nahtlos).

Von der Middleware erwartete Formularfelder:

• session_token (string) — Session-Token, das das E-Commerce während der Clone-Anfrage erhalten hat
• end_customer_id (integer) — Endkundenkennung, die das E-Commerce während der Clone-Anfrage erhalten hat
• Für jeden Artikel im Warenkorb sollten wir Formulardaten mit nullbasiertem Index haben, z. B. mit dem Schlüssel products[0][product_id] für die Produkt-ID des ersten Artikels im Warenkorb. Für jeden Artikel im Warenkorb ist die Liste der Felder:
  • sku (string) — Kennung der SKU (Produktcode) im E-Commerce (falls vorhanden)
  • product_id (string) — Kennung der Produkt-ID im E-Commerce (falls vorhanden)
  • description (string) — Beschreibung des Produkts
  • quantity (integer) — Menge des Produkts im Warenkorb
  • price (Dezimalzahl mit Punkt als Dezimaltrennzeichen) — Stückpreis
  • currency (string) — ISO-4217-Währungscode
  • manufacturer_name (string) – Produkthersteller
  • category_ids (string) — Liste, durch Komma getrennt, der Kategorie-Integer-IDs im E-Commerce der Kategorien, zu denen das Produkt direkt gehört (in der Regel Blatt in der Kategorienbaumstruktur)

Beispiel-HTML-Auto-Post-Formular (der Store liefert es an den Browser des Nutzers zurück und sendet es automatisch an die Middleware):

Verhalten:

• Der Browser postet automatisch an middleware_callback.
• Die Middleware empfängt den Warenkorb und setzt ihren Workflow fort, indem sie Kategoriecodes (z. B. UNSPSC) hinzufügt, die durch Abgleich von E-Commerce-Kategorien mit neu zugeordneten Kategoriecodes berechnet werden.

4) Custom Categories Endpoint
Wird von Middleware/Admin verwendet, um Kategorien aus dem Remote-Store abzurufen und die Zuordnung zu Standard-Kategoriecodes (z. B. UNSPSC) zu ermöglichen.

Empfohlener URL-Pfad (Beispiel):

• POST https://your-store.example.com/api/punchout/categories

HTTP-Verb

• POST (verpflichtend). Optionale Query-Parameter sind erlaubt (siehe unten).

Body

• api_key (string) — API-Key, der mit dem in Punchout Rocket für das aktuelle E-Commerce hinterlegten übereinstimmen muss

Erfolgsantwort
HTTP 200
Content-Type: application/json
Body:

{
  „status“:“success“,
  „categories“:[
  {"id":1345,"name":"Bürobedarf","parent_id":0},
  {"id":1847,"name":"Stifte","parent_id":1345},
     {"id":2345,"name":"Elektronik","parent_id":0}
  ]
}

Semantik:

• id (integer) — eindeutige Kennung (normalerweise Integer-ID der Kategorie in der Kategorientabelle im E-Commerce) der Kategorie, die die Middleware später beim Senden des Warenkorbs an das Beschaffungssystem mit neu zugeordneten Kategorien (z. B. UNSPSC-Code) verwendet.
• name (string) — Anzeigename
• parent_id (integer) — eindeutige Kennung (normalerweise Integer-ID der Kategorie in der Kategorientabelle im E-Commerce) der übergeordneten Kategorie der aktuellen Kategorie. Normalerweise „0“, wenn sie keine übergeordnete Kategorie hat

Fehlerantworten:

• HTTP 400 — ungültige Query
• HTTP 500 — interner Fehler

Beispielanfrage: POST /api/punchout/categories

  {‘api_key’: ‘site-api-key-abc’}

Beispielantwort:

{
  „status“:“success“,
  „categories“:[
  {"id":1345,"name":"Bürobedarf","parent_id":0},
  {"id":1847,"name":"Stifte","parent_id":1345},
     {"id":2345,"name":"Elektronik","parent_id":0}
  ]
}

5) Implementierungshinweise

• Verwenden Sie immer HTTPS.
• Verwenden Sie nur einmal verwendbare SSO-Tokens.
• Behalten Sie beim Posten von Warenkorbzeilen die Indexreihenfolge bei (sku[], product_id[], quantity[], unit_price[], extended_price[], categories[]). Die Middleware ordnet die Artikel nach Index zu.