Das Open Catalog Interface (OCI) ist ein von SAP entwickelter Standard für die Anbindung von Online-Shops an Einkaufssysteme (ERP-/E-Procurement-Systeme). Es ermöglicht zwei zentrale Arbeitsabläufe:
- Katalogaufruf (Punch-out): Das ERP-System öffnet den Shop in einem Browser-Fenster. Der Nutzer sucht Artikel und übergibt den befüllten Warenkorb per Formular-POST zurück an das ERP-System.
- Warenkorb-Import (/oci/import): Das ERP-System übergibt Positionen direkt an den Shop-Warenkorb (umgekehrte Richtung), z.B. um eine Bestellung im Shop abzuschließen.
Der Shop unterstützt OCI in Version 4.0. Da die Versionen weitgehend kompatibel sind, wird die Version beim Aufruf nicht geprüft.
Der Einstiegspunkt für den Katalogaufruf ist /oci/hook (alternativ /oci/new/hook).
Das ERP-System konfiguriert den Shop als externen Katalog mit folgender URL:
https://<shop-url>/oci/hook?USERNAME=<Benutzername>&PASSWORD=<Passwort>&HOOK_URL=<Rückgabe-URL>
Alle Parameter werden als GET- oder POST-Parameter übergeben. Die wichtigsten Parameter beim Hook-Aufruf:
| Parameter | Bedeutung |
|---|---|
USERNAME |
Benutzername / E-Mail-Adresse des Shop-Nutzers |
PASSWORD |
Passwort des Shop-Nutzers (URL-kodiert übergeben) |
HOOK_URL |
Rückgabe-URL des ERP-Systems. Der Shop sendet den Warenkorb per Formular-POST an diese URL. Fehlt der Parameter, wird automatisch /oci/debug als Fallback gesetzt. |
TARGET |
Ziel-Frame für das POST-Formular (z.B. _top, _parent). |
FUNCTION |
Optionale Funktion, die direkt beim Hook-Aufruf ausgeführt wird
(z.B. SOURCING, DETAIL, VALIDATE,
BACKGROUND_SEARCH). Ohne diesen Parameter landet der Nutzer
auf der Warenkorb-Seite.
|
START |
Relative URL, auf die nach dem Hook-Aufruf weitergeleitet wird
(nur wenn kein FUNCTION-Parameter gesetzt ist). Beispiel: START=/start
leitet nach dem Login direkt zur Startseite weiter statt zum Warenkorb.
|
COMMISSION |
Wird als Warenkorb-Bezeichnung / Kommission an den Warenkorb gesetzt. |
HYBRID |
true = Hybrid-OCI-Modus aktivieren (s.u.).
|
DIV |
true = Das ERP-System unterstützt freie Positionen
(Divers-Artikel). Überschreibt die Shop-Konfiguration
oci.transmitDivItems = true.
|
TARGET_URL |
Wird an die HOOK_URL angehängt, falls das ERP-System eine
zusätzliche Ziel-URL für die Rückgabe benötigt.
|
Über den Parameter FUNCTION kann beim Hook-Aufruf direkt eine bestimmte Funktion ausgelöst werden:
| Funktion | Bedeutung |
|---|---|
SOURCING |
Öffnet den Shop mit vorausgefülltem Suchbegriff aus dem Parameter SEARCHSTRING. Leitet je nach Konfiguration zum Navigator oder zur alten Suche weiter. |
DETAIL |
Öffnet direkt die Artikel-Detailseite für die Artikelnummer aus PRODUCTID. |
VALIDATE |
Validiert einen Artikel (PRODUCTID) mit optionaler Menge (QUANTITY) und gibt die aktuelle OCI-Position mit Preis zurück – ohne den Shop zu öffnen. |
BACKGROUND_SEARCH |
Führt eine Suche anhand von SEARCHSTRING durch und gibt die Ergebnisse direkt als OCI-Export-Formular zurück – ohne den Shop im Vordergrund zu öffnen. |
Wird beim Hook-Aufruf kein HOOK_URL-Parameter übergeben, setzt der Shop automatisch /oci/debug als Rückgabe-URL in die Session. Schließt der Nutzer dann den Kauf ab und übergibt den Warenkorb, wird das OCI-POST-Formular an /oci/debug gesendet – der Browser zeigt dort die übertragenen OCI-Felder im Klartext an.
Um die Rückübermittlung ohne ein echtes ERP-System zu testen, reicht es, den Hook-Aufruf ohne HOOK_URL im Browser zu starten:
https://<shop-url>/oci/hook?USERNAME=...&PASSWORD=...
Nach dem Übermitteln des Warenkorbs landet man auf /oci/debug und sieht alle übertragenen OCI-Felder (z.B. NEW_ITEM-DESCRIPTION[1],
NEW_ITEM-MATNR[1], NEW_ITEM-PRICE[1] usw.).
Bei Problemen mit dem Session-Zustand (z.B. wenn der Nutzer nach einem OCI-Aufruf nicht eingeloggt ist oder eine alte Session den neuen Aufruf überlagert) kann die Session manuell zurückgesetzt werden:
https://<shop-url>/session/reset
Dieser Aufruf löscht die aktuelle Browser-Session vollständig – inklusive der
gespeicherten HOOK_URL und des TARGET. Danach kann ein
neuer OCI-Aufruf gestartet werden. Dies ist häufig der erste Diagnoseschritt, wenn
der Nutzer nach einem OCI-Aufruf nicht korrekt eingeloggt erscheint oder kein
OCI-Button sichtbar ist.
OCI-Profile ermöglichen es, das Verhalten der Rückübermittlung pro Kunde anzupassen. Sie sind relevant, wenn das Shop-Merkmal OCI-Schnittstelle aktiviert ist und dem Kunden ein Profil zugewiesen wurde. Beispielsweise können darüber bestimmte Felder mit vom Standard abweichenden Werten befüllt werden. Auch können Mengeneinheiten auf andere gemappt werden.
Ist dem eingeloggten Kunden kein Profil zugewiesen, greift ein automatisch aus der Shop-Konfiguration erzeugtes Standard-Profil mit folgenden Einstellungen:
| Konfigurationsschlüssel | Bedeutung |
|---|---|
oci.externalClassificationFeature |
Artikelmerkmal, dessen Wert als EXT_CATEGORY_ID übertragen wird
(Fallback, falls kein Klassifizierungssystem-Treffer).
|
oci.defaultClassificationSystem |
Klassifizierungssystem, aus dem die EXT_CATEGORY_ID bezogen wird
(z.B. UNSPSC, eCl@ss).
|
oci.fillMatNr |
true = Artikelnummer wird im Feld MATNR statt
VENDORMAT übertragen.
|
oci.transmitLongtext |
true = Langtext des Artikels wird übertragen. |
Hinweis
Mengeneinheiten-Mapping: Verschiedene ERP-Systeme erwarten unterschiedliche
Codes für Mengeneinheiten im Feld NEW_ITEM-UNIT. Das Mapping bildet den
internen Mengeneinheiten-Code des Shops auf den vom ERP erwarteten Code ab.
Das Mapping wird pro OCI-Profil gepflegt und nach Priorität angewendet.
Typisches Szenario: Der Shop verwendet ST für Stück, das ERP erwartet
jedoch C62. Mit einem Eintrag ST -> C62 im
Profil-Mapping wird der Code automatisch umgeschlüsselt.
EXT_CATEGORY_ID: Das OCI-Feld NEW_ITEM-EXT_CATEGORY_ID enthält
die Warengruppe / Kategorie des Artikels im externen Klassifizierungssystem des ERP.
Der Shop befüllt dieses Feld in folgender Priorität:
-
Klassifizierung des Artikels anhand des im OCI-Profil konfigurierten
Klassifizierungssystems (z.B.
eCl@ssoderUNSPSC). -
Fallback: Wert des im OCI-Profil konfigurierten
Artikel-Merkmals (
oci.externalClassificationFeature). - Ist keines von beidem vorhanden, bleibt das Feld leer.
Das zugehörige Schema (NEW_ITEM-EXT_SCHEMA_TYPE) wird ebenfalls
aus dem OCI-Profil übertragen.
Im Hybrid-Modus kann der Nutzer im Shop bestellen und den Warenkorb gleichzeitig an das ERP-System zurückübermitteln. Der Modus wird aktiviert, wenn beim Hook-Aufruf der Parameter HYBRID=true übergeben wird – oder wenn die Shop-Konfiguration oci.enforceHybridPermission = "enabled" gesetzt ist.
Typischer Ablauf:
- ERP-System öffnet den Shop via
/oci/hookmit HOOK_URL und HYBRID=true. - Nutzer sucht Artikel und legt sie in den Warenkorb.
- Nutzer schließt den Kauf im Shop ab.
- Bestellung wird normal ausgeführt nachdem alle Checkout Felder gefüllt sind
- Nutzer kann den Warenkorb zusätzlich per OCI übermitteln
Standard-Warenkorbtitel im Hybrid-Modus
Symptom: Der Shop öffnet sich, aber der Nutzer landet auf der Login-Seite oder ist nicht eingeloggt, obwohl Zugangsdaten übergeben wurden.
Mögliche Ursachen und Lösungen:
- USERNAME oder PASSWORD sind falsch. -> Zugangsdaten prüfen.
- Das Kundenkonto existiert nicht oder ist gesperrt. -> Konto im Backend prüfen.
-
URL-Encoding-Problem: Sonderzeichen im Passwort nicht korrekt kodiert.
-> Passwort URL-enkodieren (z.B.
@->%40,#->%23). - Alte Browser-Session überlagert den neuen Login. -> /session/reset aufrufen, dann erneut versuchen.
- Ist USERNAME nicht übergeben worden, wird kein Login versucht – der Nutzer bleibt anonym. -> Parameter-Übergabe prüfen.
Symptom: Der Nutzer sieht im Shop andere Preise als erwartet, oder das ERP-System erhält beim Rückempfang falsche Preise.
Mögliche Ursachen und Lösungen:
- Preismodus prüfen: Der angezeigte und übertragene Preis hängt vom eingeloggten Konto und dem zugewiesenen Preismodus ab (z.B. Listenpreise, Nettopreise, keine Preise). -> Im Frontend den Preismodus ändern (falls möglich) oder im Backend am Kunden den Preismodus prüfen.
- Der Nutzer ist nicht korrekt eingeloggt und erhält öffentliche Preise statt Kundenpreise. -> Login-Zustand prüfen (s.o.).
- Artikel ohne Preis werden nicht übertragen, wenn oci.transmitUnpricedItems = true nicht aktiviert ist. -> Konfiguration und Preiszuweisung prüfen.
Symptom: Im Warenkorb ist keine Schaltfläche zum Übertragen der Positionen an das ERP-System sichtbar.
Mögliche Ursachen und Lösungen:
- Keine aktive OCI-Session: Der OCI-Button wird nur angezeigt, wenn der Shop über /oci/hook geöffnet wurde und dabei eine HOOK_URL in die Session gespeichert wurde. Direkter Aufruf des Shops im Browser erzeugt keine OCI-Session. -> Sicherstellen, dass der Shop vom ERP-System über die korrekte OCI-URL geöffnet wird.
- Nutzer ist nicht eingeloggt. -> Login-Zustand prüfen (s.o.).
- Session ist abgelaufen oder veraltet. -> /session/reset aufrufen und den OCI-Aufruf neu starten.
Damit ein OCI-Problem schnell und effizient bearbeitet werden kann, sollte bei jeder Supportanfrage zu OCI Folgendes mitgeteilt werden:
- Shop: URL oder Name des betroffenen Shops
- Kundennummer: Die Kundennummer des betroffenen Nutzers im Shop
- ERP-System / Software: Name des eingesetzten ERP- oder E-Procurement-Systems
- Artikel / Angebot / Use-Case: Welcher Artikel ist betroffen? Was genau wurde versucht (z.B. Warenkorb übertragen, VALIDATE-Aufruf, Hybrid-Modus)?
- Fehlerbeschreibung: Was passiert tatsächlich? Was wurde erwartet?
- Screenshot / Fehlermeldung: Falls vorhanden