Setting up PunchOut for OCI
In this section you'll learn how PunchOut works using OCI, and which configurations and parameters to use for setting it up.
How PunchOut works using OCI
Known as OCI in SAP, you can jump from your e-procurement system to Unite.
A button will be set up in your e-procurement system containing a URL with parameters you can configure, including access data. When clicked, the jump to Unite is triggered.
Choose the items you want and add them to your shopping basket. When you’re done, proceed to check out. Click on the return button on the shopping basket page.
The purchase request will be transferred back to your ERP system as a quote.
If you have stored master data such as address, cost centre or cost type in your system, these will be added automatically (data enrichment).
Start your internal approval processes.
Once the quote is approved, the order is transferred from your system to Unite.
Unite processes the order and forwards it to the supplier, who ships the goods directly to you.
Configurations and parameters for setting up OCI
How to configure OCI URL parameters correctly
Here are some useful tips for configuring your URLs correctly:
The URL that performs the jump to the Unite platform contains parameters that are assigned certain values. The following example contains the mandatory parameters:
https://www.mercateo.com/basket/oci?USERNAME=YourUSERNAME&PASSWORD=YourPASSWORD&HOOK_URL=https://www.mercateo.com/basket/httpecho(Unite used to be called Mercateo. For technical reasons, we keep using the Mercateo URLs for the time being.)
If multiple parameters are included in the URL they should be linked by an ampersand (&). Each parameter consists of a name and an assigned value, connected by an equal symbol (=), as shown in the example URL above.
Generally, OCI fields are limited to 255 characters. If more than 255 characters are required, use the parameter
NEW_ITEM-CUST_FIELDx(where x can stand for 1 to n options), as this field supports 1,000 characters.Parameters starting with
‘NEW_ITEM-’can be added flexibly. Alternatively,‘NEW_ITEM-’can also be replaced by ‘NI-’.
For example:
NEW_ITEM-CUST_FIELDxNEW_ITEM-MatGroupNEW_ITEM-SomeName
Unite can loop through fixed parameter values (e.g. shippingMatGroup=99009900) and transfer variable values (e.g. NEW_ITEM-MATGROUP=__CUSTCLASSSYS__). Variable parameter values are indicated by double underscores ‘__’.
When you’ve entered URL parameters into your system for direct entry to Unite, these parameters will overwrite any preset values.
In some procurement systems, such as SAP, the parameters can also be entered into a table. The figure below shows an example of such a table.
Mandatory parameters (minimum requirements)
The following parameters meet Unite’s minimum requirements and are mandatory:
Mandatory parameters | Description |
PunchOut-URL | Use this target address for accessing the catalogue: |
USERNAME | This parameter is for authentication and typically contains the customer number assigned by Unite. |
PASSWORD | Unite assigns a unique password. If specific views are created, Unite will assign additional passwords. The password for each view must be included as parameter value 'n' in the URL and is the only distinguishing feature between the views. Note: This password is different from the password for logging in to Unite. |
HOOK_URL | This parameter sets the return address for your e-procurement system. In SAP systems, this is created automatically. Example: In the example URL above, the HOOK_URL is defined as Note: If using SAP systems, this parameter should be placed in the last position otherwise any subsequent parameters may not be transmitted correctly. |
Automatically transferred item information
The following item information is transmitted automatically:
item number (
NEW_ITEM-EXT_PRODUCT_ID)price (
NEW_ITEM-PRICE)price unit (
NEW_ITEM-PRICEUNIT)quantity (
NEW_ITEM-QUANTITY)item unit (
NEW_ITEM-UNIT)item description (
NEW_ITEM-DESCRIPTION)item long description (
NEW_ITEM-LONGTEXT)currency (
NEW_ITEM-CURRENCY)offer number/basket ID (
NEW_ITEM-EXT_QUOTE_ID)delivery time (
NEW_ITEM-LEADTIME; in days)
Parameters for basic settings
Use the following parameters to configure basic settings:
Basic settings parameters | Description |
externalUserId | The user identification must be transmitted in the field externalUserId to personalise individual users when jumping to Unite and in partner webshops. |
externalUserIdParam | If the user identification cannot be transmitted in the field externalUserId and is instead transmitted in the field USER, use externalUserIdParam to specify this: Example: |
~TARGET |
The target attribute is set in the <form> tag for the return. If the parameter is not set, the default '_top' is used as the default value. For 'frameset', please provide the ID of the desired frame to which the return should be directed. |
NEW_ITEM mappings for standard Unite features
NEW_ITEM mappings | Description |
NEW_ITEM-CUST_FIELD3=__TAX__ | With this parameter the Value added tax (VAT) of the item is transmitted. The VAT rate is product-dependent – in Germany it’s either 7% or 19%.
|
NEW_ITEM-CUSTOM1=__DELIVERYDATE__ | This parameter returns the delivery date (DD-MM-YYYY). Note: Keep in mind that time passes during your internal approval process that you will have to add to the above delivery date. Additionally, stock levels and therefore the delivery time may have changed. |
NEW_ITEM-CUST_FIELD2=__RCDESC__ | This parameter transmits the return conditions as plain text. We recommend adding this information to the |
NEW_ITEM-…=__MANUFACTURER__ | The manufacturer name is transmitted using this parameter. |
NEW_ITEM-…=__MANUFACTURER_AID__ | The manufacturer item number is transmitted using this parameter. |
NEW_ITEM-…=__EAN__ | The EAN code is transmitted using this parameter. |
NEW_ITEM mappings for commodity groups
NEW_ITEM mappings | Description |
NEW_ITEM-MATGROUP=__CUSTCLASSSYS__ | Use this parameter to specify the product group. The classification system is set by the OCI configuration in your specific view. Unite supports the ECLASS and UNSPSC classification systems per default. If you prefer a customised product group mapping, please contact your Unite technical consultant. |
NEW_ITEM-EXT_SCHEMA_TYPE | Use this parameter to transmit the classification standard of the product group. The spelling of the classification standard can be customised as needed. Example: If the item does not contain any information about the classification system, a default classification standard can be used with parameter 'defaultMaterialGroupType'. Example: |
shippingMatgroup | If you want to transmit a fixed product group for shipping costs, such as 99009900, set the parameter as follows: Note: This parameter can only be used if the shipping costs are sent as a separate line item (see section ‘Parameters for shipping costs’ below). |
NEW_ITEM mappings for G/L accounts relating to items and shipping costs
NEW_ITEM mappings | Description |
NEW_ITEM-xxx[P]=__FEATURE[K-YourCompanyNameSK]__ | Use this parameter to specify the G/L account. |
NEW_ITEM-xxx[S]=0815 | If the shipping costs are transmitted as a separate line item, this parameter allows a fixed G/L account value to be determined. For example:
([P] = product / [S] = shipping costs) If you wish to transmit the G/L account, please contact your Unite technical consultant. |
Fixed and variable values from the Buyer AID for Exclusive Catalogues
With this option a variable value can be read from your Exclusive Catalogue. The value is defined in the BUYER_AID field. If there is no value in the catalogue, a predefined fixed value is transmitted.
NEW_ITEM-CONTRACT=__FEATURE[variable-exclusive-catalog-Buyer_AID_value, default-fixed-value]__
For example:
NEW_ITEM-CONTRACT=__FEATURE [YourCompanyName_Contract_ID,4600020310]__NEW_ITEM-CONTRACT_ITEM=__FEATURE [YourCompanyName_Contract_Pos,10]__
Separator = comma (,)
If you want to transmit these values, please contact your Unite technical consultant who will coordinate the necessary setup.
Parameters for shipping costs
Shipping costs can be transmitted as a separate item or added to the percentile item price (shipping cost splitting). Shipping cost splitting is configured by your designated Unite technical consultant as part of your system setup.
Parameters for shipping costs | Description |
skipZeroShippings |
|
shippingMatGroup | If you receive shipping costs as a separate line item, you can define a fixed product group for shipping costs, e.g. 99009900: You can find more information about the product group in section |
ociItemserviceMode |
Use this parameter to configure whether the item is a product or shipping costs.
|
NEW_ITEM mappings for attachments
NEW_ITEM mappings | Description |
NEW_ITEM-SIDAB=__SIDAB__ | If a safety data sheet is available, the parameter will return the value ‘1’. In this case, the URL to the safety data sheet will be sent in the field The parameter returns a value of ‘0’ if there is no safety data sheet. |
NEW_ITEM-ATTACHMENT=__MIME__ | This parameter allows access to URLs of images, data sheets, and safety data sheets. For example:
|
allowAttachments |
|
Parameters for transmitting search keywords
Use the parameter routing=category&id=xx to transmit the user’s search keywords to Unite. When accessing via OCI, the corresponding Unite page for the search term will open directly.
Please transmit umlauted letters such as ä, ö, ü as ae, oe, ue and ß as double-s.
Example:
User entry: ‘Bürobedarf’
Transmitting to Unite:
routing=category&id=Buerobedarf
Shopping lists feature
The parameter externalUserId=xx is required so that Unite can activate the shopping list feature for you.
Modifying a shopping basket
This function allows the user to modify shopping baskets or purchase order requests after transmitting the basket but before transmitting the order.
Changes must only be made using this function, as item prices and shipping costs can change depending on order quantities. Modifying the shopping basket solely within your system could lead to errors during the ordering process.
During this process, a new (!) shopping basket is created and exported. The old shopping basket must be deactivated in your system.
This can be done in two ways:
Manual entry
The requester manually enters the offer or shopping basket ID manually in the search field. This will take the requester to the existing offer where the required adjustments can be made.
Automated
The existing shopping basket is automatically called up via a dynamic URL using the parameter routing=basket&id=<Id>.
This parameter sends the ID of the existing offer or shopping basket to Unite. For example, shopping basket xyz0815 is called up using the parameter routing=basket&id=xyz0815.
In this case, the ID readout from the OCI return value NI-EXT_QUOTE_ID must take place in your system.
Information about the existing shopping basket is contained in the relevant OCI return fields:
OCI return field | Description |
NI-EXT_QUOTE_ID | Parameter value: __EXPORTID__ |
EXT_QUOTE_ITEM | Parameter value: (no value required) |
Your Unite technical consultant can answer any questions related to modifying the shopping basket.
Resending the shopping basket
This function allows the requester to create a new offer or shopping basket based on a previously approved purchase order request (containing the same items). The new request must go through approval again and be sent as an order.
Similar to the two ways of modifying a shopping basket, the process involves accessing the original, already-ordered offer, making the necessary changes, and submitting a new order based on the updated request.
For questions about the resending the shopping basket function, your designated Unite technical consultant will be happy to support you.
If you are using a specific webshop and need to transmit the item offer number directly to your supplier, your Unite technical consultant can also provide guidance.
Parameters set by Unite
The following parameters are set by Unite and do not need to be configured by you:
http_content_charset
NEW_ITEM-VENDOR
priceUnitIsQuantity
ociButtonName
hideCheckoutButton
hideSendBasketButton
punchoutFormAutoCommit
keepBasketAtExport
addViewOptions
enableShoppingLists
Technical support
The setup of the interfaces initially requires a technical implementation project. If you’re an administrator responsible for configuring PunchOut, please contact Unite’s Technical Support.