PunchOut-Integrationsspezifikation für individuelle Shops

1. Einrichtung in PunchOut Rocket

E-Commerce-Website

Endpunktpfade werden unverändert an Site URL angehängt und müssen deshalb mit / beginnen. Beispiel: Site URL https://your-store.example.com + /api/punchout/clone → https://your-store.example.com/api/punchout/clone.

Bestellungen (Abschnitt 6) und vordefinierte Warenkörbe sind im Premium-Tarif enthalten, auch während der kostenlosen Testphase: Ihr Tarif aktiviert sie für die Website, und die Endkundenseite zeigt dann die Abschnitte Orders und Predefined Carts. Auftragsbestätigungen und Versandmeldungen (Abschnitte 7–8) benötigen zusätzlich die Option OC & ASN.

Endkunde

Jedes Kundenunternehmen ist ein Endkunde Ihrer Website. Neben seinen Protokoll-Zugangsdaten (cXML-Identitäten und Shared Secret oder OCI-Benutzername und Passwort) betreffen diese Felder Ihren Shop:

Die übrigen Website- und Endkundenseiten funktionieren wie bei den anderen Plattformen: siehe Dokumentation.

2. Klon-Endpunkt

Standardpfad: /api/punchout/clone. Wird aufgerufen, wenn ein Kunde Ihren Shop aus dem Einkaufssystem öffnet. Ihr Shop erstellt einen aus username geklonten Benutzer (oder verwendet ihn erneut), bindet ihn an diese PunchOut-Sitzung und gibt eine SSO-URL zurück, die ihn anmeldet (Abschnitt 3).

Anfrage-Body

quantity und price sind Zeichenketten: Vor der Verwendung umwandeln.

Anfrage: create, mit gewähltem Artikel

{
  "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"
  }
}

Anfrage: edit, mit dem wiederherzustellenden Warenkorb

{
  "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": "Example description", "currency": "EUR"},
    {"sku": "XYZ-002", "product_id": "19854", "quantity": "1", "price": "249.00",
     "description": "Another example description", "currency": "EUR"}
  ]
}

Erfolgsantwort

HTTP 2xx

HTTP 200
{
  "status": "success",
  "sso_url": "https://your-store.example.com/punchout/sso?token=eyJ..."
}

sso_url ist das einzige gelesene Feld: Es ist erforderlich und muss eine absolute http://- oder https://-URL sein. PunchOut Rocket leitet den Browser des Kunden dorthin (bei cXML über das Einkaufssystem, bei OCI direkt).

Fehlerantworten

Jeder Status außerhalb von 2xx oder eine Antwort ohne gültige sso_url lässt den PunchOut scheitern: Der Kunde erhält einen Fehler im Einkaufssystem. Ihre Antwort (Status und Body) wird im PunchOut-Sitzungsprotokoll gespeichert; erläutern Sie deshalb den Grund in der Meldung.

4. Warenkorbübertragung (automatisch gesendetes Formular)

Bei PunchOut-Benutzern darf die Checkout-Schaltfläche nicht Ihren Checkout starten: Sie sendet stattdessen den Warenkorb an PunchOut Rocket. Ihr Shop gibt eine HTML-Seite zurück, die ein verborgenes Formular automatisch absendet, idealerweise mit einer Ladeanzeige.

• URL: {gateway_base_url}/start-sso-checkout (gateway_base_url aus der Klonanfrage)
• Methode: POST, application/x-www-form-urlencoded (normales Absenden eines Browserformulars)
• Kein api_key: Die Sitzung wird durch session_token und end_customer_id identifiziert.

i beginnt bei 0 und ist lückenlos: PunchOut Rocket beendet das Lesen beim ersten fehlenden Index. Denken Sie daran, die Werte für HTML zu maskieren.

Beispielseite, die beim Checkout zurückgegeben wird

<!doctype html>
<html>
<body>
<p>Sending your cart to your procurement system…</p>
<form id="punchout_repost" method="post" action="https://middleware.example.com/start-sso-checkout">
  <input type="hidden" name="session_token" value="sess-012345"/>
  <input type="hidden" name="end_customer_id" value="2"/>
  <input type="hidden" name="products[0][sku]" value="ABC-001"/>
  <input type="hidden" name="products[0][product_id]" value="19852"/>
  <input type="hidden" name="products[0][description]" value="Example description"/>
  <input type="hidden" name="products[0][quantity]" value="2"/>
  <input type="hidden" name="products[0][price]" value="15.95"/>
  <input type="hidden" name="products[0][currency]" value="EUR"/>
  <input type="hidden" name="products[0][unit_of_measure]" value="EA"/>
  <input type="hidden" name="products[0][manufacturer_name]" value="3M"/>
  <input type="hidden" name="products[0][category_ids]" value="1145,3398"/>
  <input type="hidden" name="products[1][sku]" value="XYZ-002"/>
  <input type="hidden" name="products[1][product_id]" value="19854"/>
  <input type="hidden" name="products[1][description]" value="Another example description"/>
  <input type="hidden" name="products[1][quantity]" value="4"/>
  <input type="hidden" name="products[1][price]" value="10.90"/>
  <input type="hidden" name="products[1][currency]" value="EUR"/>
  <input type="hidden" name="products[1][manufacturer_name]" value="DEWALT"/>
  <input type="hidden" name="products[1][category_ids]" value="2146"/>
</form>
<script>document.getElementById('punchout_repost').submit();</script>
</body>
</html>

PunchOut Rocket sendet den Warenkorb dann an das Einkaufssystem und beendet die Sitzung. Eine Sitzung akzeptiert nur einen Warenkorb:

7. Auftragsstatus-Endpunkt

Standardpfad: /api/punchout/order-status. Wird nur für Endkunden mit aktiviertem „Send order status updates“ und für Aufträge aus Abschnitt 6 aufgerufen: stündlich für 60 Tage ab Auftrag und sofort nach einer Benachrichtigung (Abschnitt 8). Erfordert die Option OC & ASN. Aus der Antwort sendet PunchOut Rocket an das Einkaufssystem des Kunden:

• eine Auftragsbestätigung (cXML ConfirmationRequest), einmalig, wenn der Auftrag angenommen oder storniert wird;
• eine Versandmeldung (cXML ShipNoticeRequest) für jede neue Sendung eines bestätigten Auftrags.

PunchOut Rocket merkt sich seine Sendungen: Antworten Sie immer mit dem aktuellen Auftragszustand, und PunchOut Rocket ermittelt die Änderungen.

Anfrage: order_id ist die von Ihrem Endpunkt zur Auftragserstellung zurückgegebene ID

{"api_key": "site-api-key-abc", "order_id": "100045"}

Erfolgsantwort

HTTP 200

HTTP 200
{
  "status": "success",
  "order_status": "shipped",
  "items": ["5501", "5502"],
  "quantities": [
    {"order_item_id": "5501", "quantity": 2},
    {"order_item_id": "5502", "quantity": 1}
  ],
  "shipments": [
    {
      "id": "SH-1",
      "shipped_at": "2026-11-12T09:30:00+01:00",
      "carrier": "UPS",
      "tracking": "1Z999AA10123456784",
      "items": [{"order_item_id": "5501", "quantity": 2}]
    }
  ]
}

Die Bestätigung wird einmalig gesendet, wenn der Auftrag erstmals processing, shipped oder delivered ist:

• Sie akzeptiert den gesamten Auftrag, wenn jede PO-Zeile vollständig enthalten ist;
• sonst akzeptiert sie jede Zeile mit der im Auftrag enthaltenen Menge und lehnt den Rest ab (entfernte Artikel, reduzierte Mengen). Eine über die PO hinaus erhöhte Menge wird mit der PO-Menge bestätigt;
• wenn keine Zeile mehr vorhanden ist, wird nichts gesendet: Verwenden Sie cancelled, um den Auftrag abzulehnen.

Spätere Artikeländerungen werden nicht erneut bestätigt: Bearbeiten Sie den Auftrag vor der Annahme.

Melden Sie eine Sendung erst nach dem Versand. Änderungen nach ihrer Meldung werden nicht erneut gesendet. Lehnt das Einkaufssystem eine Bestätigung oder Versandmeldung ab, sendet PunchOut Rocket sie bei der nächsten Prüfung erneut; bis zur Annahme werden keine nachfolgenden Meldungen gesendet.

9. Checkliste für den Produktivstart

1. Konfigurieren Sie die Website (Abschnitt 1) und tragen Sie denselben API-Schlüssel in Ihrem Shop ein.
2. Erstellen Sie einen Endkunden und setzen Sie dessen „E-commerce User to Clone“.
3. Klicken Sie in seinem Category Mapping auf „Update from e-commerce“ und ordnen Sie die Kategorien zu; setzen Sie einen Default UNSPSC.
4. Testen Sie einen PunchOut mit dem cXML-Testformular im Adminbereich: create, dann edit mit einem Warenkorb und anschließend den Warenkorb zurücksenden.
5. Für Bestellungen (Premium-Tarif): Senden Sie einen Test-OrderRequest und prüfen Sie den Auftrag in Ihrem Shop.
6. Für Statusaktualisierungen (Option OC & ASN): Aktivieren Sie „Send order status updates“ beim Endkunden, lassen Sie den Testauftrag Ihre Zustände durchlaufen und prüfen Sie, ob das Kundensystem Bestätigung und Versandmeldungen erhält.

Beachten Sie:

• PunchOut-Benutzer dürfen keinen Checkout in Ihrem Shop abschließen: Ihr Warenkorb geht zurück an das Einkaufssystem (Abschnitt 4), und der Auftrag kommt später über Abschnitt 6.
• Über Abschnitt 6 empfangene Aufträge sind bereits vom Einkaufssystem des Kunden freigegeben: Sie benötigen keine Onlinezahlung.

Sie brauchen einen Testkunden oder eine Prüfung Ihrer Implementierung? Sprechen Sie mit unseren Entwicklern, oder lassen Sie uns die Integration mit Go-Live Assist umsetzen.