PunchOut - Technische Informationen: OCI

Parameter zur Konfiguration der OCI-URL

Der Link, der den Sprung zum Unite-Shop ermöglicht, enthält Parameter mit bestimmten Wertbelegungen (Unite hieß früher Mercateo. Aus technischen Gründen nutzen wir vorerst die alten URLs).

Ein Beispiel für die Pflichtparameter ist:
https://www.mercateo.com/basket/oci?USERNAME=IhrUSERNAME&PASSWORD=IhrPASS-WORD&HOOK_URL=https://www.mercateo.com/basket/httpecho

Weitere Parameter können durch ein kaufmännisches „Und“ („&“) hinzugefügt werden. Ein Parameter in der URL besteht aus einem Namen und einem Wert, der durch ein Gleichheitszeichen zugewiesen wird (siehe oben).

Der Feldinhalt bei OCI-Parametern wird generell auf 255 Zeichen begrenzt. Sollten mehr als 255 Zeichen notwendig sein, verwenden Sie den Parameter NEW_ITEM-CUST_FIELDx (wobei x für eine beliebige Zahl steht), da dieses Feld 1.000 Zeichen unterstützt.

Parameter, die mit „NEW_ITEM-“ beginnen, können flexibel ergänzt werden. Alternativ kann „NEW_ITEM-“ auch durch „NI-“ ersetzt werden.

Beispielsweise:

• NEW_ITEM-CUST_FIELDx

• NEW_ITEM-MatGroup

• NEW_ITEM-IrgendEinName

Das System kann sowohl feste Parameterwerte (z.B. shippingMatGroup=99009900) als auch variable Werte (z.B. NEW_ITEM-MATGROUP=CUSTCLASSSYS) übergeben. Variable Parameterwerte sind durch doppelte Unterstriche „__“ gekennzeichnet.

Wenn Sie URL-Parameter in Ihrem System für den Einsprung gepflegt haben, überschreiben diese die Voreinstellungen in unserem System.

Je nach ERP-System können die Parameter auch in eine Tabelle eingetragen werden (z.B. bei SAP). Die Abbildung „Muster OCI SAP“ zeigt ein Tabellenbeispiel aus SAP.

Pflichtparameter (Minimalanforderung)

Die folgenden Parameter sind notwendig und stellen die Minimalanforderung dar.

Einsprungs-URL

Die Zieladresse für den Katalogaufruf lautet je nach ERP-System und Version:

• https://www.shop.com/basket/oci?

• https://www.shop.com/basket/oci

USERNAME

Dieser Parameter dient zur Authentifizierung und enthält normalerweise die von uns vergebene Kundennummer.

PASSWORD

Ein eindeutiges Passwort wird vergeben. Sollten spezifische Sichten erstellt werden, gibt es zusätzliche Passwörter. Das Passwort für die jeweilige Sicht ist das einzige Unterscheidungsmerkmal und wird als Parameterwert n in die URL eingetragen.

Hinweis: Dieses Passwort unterscheidet sich vom Passwort für das Login auf der Website.

HOOK_URL

Hier wird die Rücksprungadresse für Ihr E-Procurement-System angegeben. Bei SAP-Systemen wird diese automatisch erstellt.

Beispiel: Im Beispiel-Link ist die HOOK_URL mit &HOOK_URL=https://www.mercateo.com/basket/httpecho angegeben. Dies dient der Überprüfung, da die Rückgabewerte im Browser angezeigt werden, statt die Bestellung ins ERP-System zu übergeben.

Hinweis: Bei SAP-Systemen sollte dieser Parameter zuletzt stehen.

Automatisch übertragene Artikelinformationen

Folgende Artikelinformationen werden automatisch übertragen:

·         Artikelnummer (NEW_ITEM-EXT_PRODUCT_ID)

·         Preis (NEW_ITEM-PRICE)

·         Preiseinheit (NEW_ITEM-PRICEUNIT)

·         Menge (NEW_ITEM-QUANTITY)

·         Mengeneinheit (NEW_ITEM-UNIT)

·         Artikelname (NEW_ITEM-DESCRIPTION)

·         Artikellangbeschreibung (NEW_ITEM-LONGTEXT)

·         Währung (NEW_ITEM-CURRENCY)

·         Angebotsnummer / Warenkorb-ID (NEW_ITEM-EXT_QUOTE_ID)

·         Lieferzeit (NEW_ITEM-LEAD-TIME; in Tagen)

Parameter für Grundeinstellungen

Mit den folgenden Parametern können verschiedene Grundeinstellungen vorgenommen werden.

http_content_charset

• Standardwert: iso-8859-15

• Gültige Werte: UTF-8, iso-8859-15

Dieser Parameter setzt das accept-charset-Attribut im <form>-Tag für den Rücksprung. Ist der Parameter nicht gesetzt, wird der Standardwert UTF-8 verwendet.

Wenn beim Katalogaufruf der Parameter http_content_charset=UTF-8 übertragen wird, setzt unser System im Formular der OCI-Daten das Attribut accept-charset="UTF-8", um dem Browser die gewünschte Kodierung der Parameter für den HTTP-Request mitzuteilen. Beachten Sie jedoch, dass nicht alle Browser dies unterstützen.

Achtung: Sollten die Zeichen dennoch nicht korrekt dargestellt werden, verwenden Sie zusätzlich den Parameter NEW_ITEM-IEHACK=&#9760;

externalUserId (alt slGroupParam)

Das Feld externalUserId muss die Benutzerkennung zur Personalisierung einzelner Nutzer beim Sprung auf die Plattform und in die Partner-Webshops übertragen.

externalUserIdParam (vormals slGroupParam)

Wenn die Benutzerkennung nicht im Feld externalUserId, sondern z.B. im Feld BENUTZER übertragen wird, muss angegeben werden, in welchem Parameter die benutzerspezifische Kennung übertragen wird. Dies kann über den Parameter externalUserIdParam eingestellt werden:

• Beispiel: externalUserIdParam=BENUTZER

NEW_ITEM-VENDOR

Der Kunde hinterlegt die Kreditorennummer im Parameter NEW_ITEM-VENDOR. Wenn dieser Parameter in der OCI-URL gesetzt ist (z.B.: NEW_ITEM-VENDOR=08154711), wird für die ausgewählten Artikel aus dem öffentlichen Shop der Wert 08154711 zurückgegeben. Bei Artikeln aus Exklusivkatalogen wird 08154711 durch die entsprechende Kreditorennummer des Exklusivkatalogs ersetzt.

priceUnitIsQuantity

• Standardwert: true

• Gültige Werte: true, false

Dieser Parameter steuert, ob im Feld NEW_ITEM-PRICE der Einzelpreis (bzw. der Preis für eine gegebenenfalls bestehende PriceQuantity) oder der Gesamtpreis auf die Bestellmenge bezogen übertragen wird.

Bei priceUnitIsQuantity=true wird der Gesamtpreis übertragen und der Wert von NEW_ITEM-PRICEUNIT auf NEW_ITEM-QUANTITY gesetzt.

Achtung: Sollte für den Kunden Versandkostensplitting eingestellt sein, wird dieser Parameter ignoriert.

~TARGET

• Standardwert: _top

• Gültige Werte: top, parent, _main, frameset

Im <form>-Tag für den Rücksprung wird das target-Attribut gesetzt. Wenn der Parameter nicht gesetzt ist, wird _top als Standardwert genommen. Für frameset geben Sie bitte die ID des gewünschten Frames an, zu dem der Rücksprung erfolgen soll.

Systemparameter für die Plattform

ociButtonName

Dieser Parameter erlaubt die Beschriftung des "OCI-Export"-Buttons auf der Warenkorbseite. Es sind maximal 30 Zeichen erlaubt. Leerzeichen und Umlaute sollten vermieden werden.

• Beispiel: ociButtonName=SAP-Sprung

 hideCheckoutButton

• Standardwert: false

• Gültige Werte: true, false

Bei true wird der normale „Zur Kasse gehen“-Button auf der Warenkorbseite ausgeblendet.

hideSendBasketButton

• Standardwert: false

• Gültige Werte: true, false

Dieser Parameter blendet den Button „Warenkorb versenden“ auf der Warenkorbseite aus, wenn der Wert true übergeben wird.

punchoutFormAutoCommit

• Standardwert: false

• Gültige Werte: true, false

Die zweite Abfrage zur Warenkorbübertragung wird bei dem Wert true automatisch durchgeführt.

keepBasketAtExport

• Standardwert: false

• Gültige Werte: true, false

Bei false wird im Moment des Klicks auf den OCI-Export-Button per JavaScript unser Warenkorb-Cookie („korb2“) im Browser gelöscht.

addViewOptions

• Gültige Werte: uiLanguage.LÄNDERKÜRZEL (z.B. de, gb, fr, es, hu)

Die Benutzeroberfläche (GUI), Kategorien und Such-Filter werden in der angegebenen Sprache dargestellt; alle Inhalte wie Artikel, Markenwelten und Fachberichte bleiben in der Landessprache der Plattform.NEW_ITEM-Belegungen für Standardfeatures

NEW_ITEM-CUST_FIELD3=TAX

Der Mehrwertsteuersatz ist produktabhängig – in Deutschland 7% oder 19%.

·         a) Mit NEW_ITEM-CUST_FIELD3=__TAX__ wird konfiguriert, dass der Mehrwertsteuersatz des Produktes übertragen wird. Die Übertragung ergibt NEW_ITEM-CUST_FIELD3=0.19 oder NEW_ITEM-CUST_FIELD3=0.07.

·         b) Mit NEW_ITEM-CUST_FIELD3=__TAX100__ wird der Mehrwertsteuersatz des Produktes in Prozent übertragen.

·         c) Mit NEW_ITEM-CUST_FIELD3=__TAX[0.07=a,0.19=b,*=c]__ kann kundenspezifisch konfiguriert werden, welcher Wert für den jeweiligen Mehrwertsteuersatz übertragen wird (z.B. 7% auf „a“, 19% auf „b“ und alles andere auf „c“ gemappt).

NEW_ITEM-CUSTOM1=DELIVERYDATE

Mit dem Parameter NEW_ITEM-CUSTOM1=__DELIVERYDATE__ wird das Lieferdatum (TT-MM-JJJJ) zurückgegeben.

Achtung: Berücksichtigen Sie, dass während Ihres internen Genehmigungsprozesses Zeit vergeht, die Sie zum Liefertermin hinzurechnen müssen. Zudem kann sich der Lagerbestand und damit die Lieferzeit verändern.

NEW_ITEM-CUST_FIELD2=RCDESC

Die jeweiligen Retourenbedingungen werden als Klartext übergeben. Es wird empfohlen, diese Information im Artikel Langtext (NEW_ITEM-CUST_FIELD) anzufügen, da dieses Feld bis zu 1.000 Zeichen unterstützt.

NEW_ITEM-…=MANUFACTURER

Mit dem Parameter NEW_ITEM-…=__MANUFACTURER__ wird der Hersteller übergeben.

NEW_ITEM-…=MANUFACTURER_AID

Mit dem Parameter NEW_ITEM-…=__MANUFACTURER_AID__ wird die Hersteller-Artikelnummer übergeben.

NEW_ITEM-…=EAN

Mit dem Parameter NEW_ITEM-…=__EAN__ wird die EAN-Nummer übergeben.

Parameter und NEW_ITEM-Belegungen für Warengruppen

NEW_ITEM-MATGROUP=CUSTCLASSSYS

Mit dem Parameter NEW_ITEM-MATGROUP=__CUSTCLASSSYS__ adressiert der Kunde die Warengruppe. Das Klassifikationssystem wird von der OCI-Konfiguration in die kundenspezifische Sicht eingestellt. Als Standard-Warengruppen können eClass und UNSPSC übermittelt werden. Bei Bedarf eines kundenspezifischen Warengruppen-Mappings wenden Sie sich bitte an Ihren Projektmanager bei uns.

NEW_ITEM-EXT_SCHEMA_TYPE

Dieser Parameter ermöglicht die Angabe des Klassifikationsstandards der übertragenen Warengruppe.

• Beispiel: NEW_ITEM-EXT_SCHEMA_TYPE=__CUSTCLASSSYSTYPE__

• Oder: NEW_ITEM-EXT_SCHEMA_TYPE=__CUSTCLASSSYSTYPE[UNSPSC=Unspsc]__

Ist am Artikel keine Klassifikationsinformation hinterlegt, kann mit dem Parameter defaultMaterialGroupType ein Standard-Klassifikationsstandard definiert werden.

• Beispiel: defaultMaterialGroupType=ECLASS

shippingMatgroup

Soll für die Versandkosten eine feste Warengruppe übertragen werden, wie z.B. 99009900, so ist der Parameter wie folgt zu setzen: shippingMatGroup=99009900.

Dieser Parameter kann nur verwendet werden, wenn die Versandkosten als separate Bestellposition übertragen werden.

NEW_ITEM-Belegungen für Sachkonten bzgl. Produkte und Versandkosten

NEW_ITEM-xxx[P]=FEATURE[K-KundennameSK] (alt NEW_ITEM-MATGROUP1)

Mit dem Parameter NEW_ITEM-xxx[P]=__FEATURE[K-KundennameSK1]__ adressiert der Kunde das Sachkonto.

NEW_ITEM-xxx[S]=0815

Wenn die Versandkosten als separate Position übertragen werden, kann hierüber ein fester Sachkontowert festgelegt werden.

• Beispiel: NEW_ITEM-SACHKONTO[P]=__FEATURE[K-KundennameSK1]__

• Beispiel: NEW_ITEM-SACHKONTO[S]=0815

([P] = Produkt)

([S] = Versandkosten/Shipping Costs)

Für die Übertragung des Sachkontos wenden Sie sich bitte an Ihren Projektmanager bei uns.

Fixe und variable Werte aus der Buyer-AID für Exklusivkataloge

Diese Option ermöglicht das Auslesen eines variablen Wertes aus Ihrem Exklusivkatalog. Der Wert wird im Feld BUYER_AID hinterlegt. Ist kein Wert vorhanden, wird ein fixer Wert übertragen.

NEW_ITEM-CONTRACT = _ FEATURE[variabler-Exklusivkatalog-BuyerAID_Wert, Default-Festwert]_ _

• Beispiel: NEW_ITEM-CONTRACT=__FEATURE[Kundenname_Contract_ID,4600020310]__

• Beispiel: NEW_ITEM-CONTRACT_ITEM=__FEATURE[Kundenname_Contract_Pos,10]__

Trennzeichen: , (Komma)

Für die Übertragung wenden Sie sich bitte an Ihren Mercateo-Projektmanager.

Parameter für Versandkosten

Die Versandkosten können als separate Position übertragen oder auf den prozentualen Artikelpreis aufgeschlagen werden (Versandkostensplitting). Das Versandkostensplitting wird vom Mercateo-Projektmanager in der Kundenkonfiguration eingestellt.

skipZeroShippings

• Standardwert: false

• Gültige Werte: true, false

Der Parameter konfiguriert das Übertragen bzw. Unterdrücken von Versandkostenpositionen mit 0€. Ist kein Versandkostensplitting eingestellt, muss der Parameter auf true gesetzt werden.

shippingMatGroup

Für Versandkosten als separate Bestellposition können Sie eine feste Warengruppe hinterlegen, z.B. 99009900:

• Beispiel: shippingMatGroup=99009900

Weitere Informationen zu Warengruppen finden Sie unter Punkt 3.6.

ociItemserviceMode

• Standardwert: ZERO_ONE

• Gültige Werte: OMIT, TRUE_FALSE, ZERO_ONE, ONE_ZERO, X

Konfigurieren Sie mit diesem Parameter, ob es sich bei der Position um ein Produkt oder Versandkosten handelt.

• OMIT: Positionszeile wird ausgelassen

• TRUE_FALSE: true für Versand, false für Produkt

• ZERO_ONE: 0 für Versand, 1 für Produkt

• ONE_ZERO: 1 für Versand, 0 für Produkt

• X: leer für Versand, X für Produkt

Parameter und NEW_ITEM-Belegungen für Attachments

NEW_ITEM-SIDAB=SIDAB

Wenn ein Sicherheitsdatenblatt vorhanden ist, wird der Wert 1 zurückgegeben, und die URL zum Sicherheitsdatenblatt wird im Feld NEW_ITEM-ATTACHMENT übergeben. Der Rückgabewert 0 bedeutet, dass kein Sicherheitsdatenblatt vorhanden ist.

NEW_ITEM-ATTACHMENT=MIME

Dieser Parameter ermöglicht den Zugriff auf URLs von Bildern, Datenblättern und Sicherheitsdatenblättern.

• Beispiel: NEW_ITEM-ATTACHMENT=__MIME[image]__

• Beispiel: NEW_ITEM-ATTACHMENT2=__MIME[datasheet]__

• Beispiel: NEW_ITEM-ATTACHMENT3=__MIME[safetyDatasheet]__

allowAttachments

• Standardwert: true

• Gültige Werte: true, false

Mit allowAttachments=false kann die standardmäßige Übertragung der Anhänge deaktiviert werden.

Parameter zur Übertragung des Suchbegriffes

Mit dem Parameter routing=category&id=xx können Sie die Sucheingabe des Users an die Beschaffungsplattform übertragen. Beim OCI-Einsprung öffnet sich direkt die entsprechende Seite des Suchbegriffes.

Bitte übergeben Sie die Umlaute ä, ö, ü als ae, oe, ue und ß als ss.

Beispiel:

• Usereingabe: Bürobedarf

• Übergabe an Mercateo: routing=category&id=Buerobedarf

Einkaufslisten / Multi-User-Fähigkeit / Sprung in Partner-Webshops

Mit den nachfolgenden Parametern aktivieren Sie die Einkaufslistenfunktion auf Ihrer Beschaffungsplattform oder können zu anderen Zwecken Logindaten übergeben.

Voraussetzung ist die Übergabe der benutzerspezifischen Kennung im Parameter externalUserId=xx!

enableShoppingLists

• Standardwert: false

• gültige Werte: true, false

enableShoppingLists=true ist Voraussetzung für die Nutzung der Einkaufslisten-Funktion.

Warenkorbänderung

Diese Funktion ermöglicht es dem Anwender, Warenkörbe oder Bestellanforderungen nach der Übertragung des Warenkorbs und vor der Bestellübermittlung zu ändern.

Die Änderungen dürfen nur über diese Funktion erfolgen, da Artikelpreise und Versandkosten von den Bestellmengen abhängen können. Wenn der Warenkorb nur in Ihrem System geändert wird, kann es zu Fehlern bei der Bestellung kommen.

Bei diesem Vorgang wird ein neuer Warenkorb erstellt und exportiert. Der alte Warenkorb muss in Ihrem System deaktiviert werden.

Sie können diese Funktion auf zwei Arten nutzen: durch die manuelle Eingabe der Angebotsnummer oder Warenkorbnummer durch den Bestellanforderer, oder automatisiert durch einen dynamischen Sprung zum Aufruf des bestehenden Warenkorbs.

Die Informationen für den bestehenden Warenkorb sind in den jeweiligen OCI-Rücksprungfeldern enthalten:

• NI-EXT_QUOTE_ID (alt: NEW_ITEM-EXT_QUOTE_ID)

  • Parameter-Wert: EXPORTID

  • Die erstellte Angebotsnummer kann aus dem OCI-Rückgabefeld NI-EXT_QUOTE_ID entnommen werden.

• EXT_QUOTE_ITEM

  • Parameter-Wert: (kein Wert erforderlich)

  • Die Artikelpositionsnummer des Warenkorbs kann aus dem OCI-Rückgabefeld EXT_QUOTE_ITEM entnommen werden.