OCI – Configure Login

In the General tab, under "Login", all settings are listed that determine how the procurement system starts the punchout session.

HTTP Request Method

Option	Description
GET & POST	Both methods are accepted (default, recommended)
GET	Only GET requests allowed
POST	Only POST requests allowed

Variable Names

The procurement system passes user data and the return URL as URL parameters or POST body. The field names are defined in the OCI standard but may differ between systems.

Variable name	Default	Description
User variable name	USERNAME	Parameter name for email address or username
Password variable name	PASSWORD	Parameter name for the password
URL variable name	HOOK_URL	Parameter name for the return URL
Token variable name	TOKEN	Parameter name for a token (alternative to password)

Example

A SAP system may send ~username instead of USERNAME.

Empty parameters

A parameter that is sent empty counts as not supplied. Procurement systems often send every configured parameter and leave the unused ones blank — a blank TOKEN therefore no longer prevents login via username and password.

Control Parameters

The SAP control parameters ~target, ~OkCode and ~caller are returned to the procurement system unchanged. They are sent as hidden fields in the return form; their spelling is normalised to the form documented by SAP, regardless of how the procurement system sent them.

~target additionally determines which window the return form posts into. The keywords _top, _parent, _self and _blank are accepted, as are valid window names. If the parameter is missing or its value is unusable, _top is used.

Avoid duplicate transfer

If one of these parameters was previously mapped by hand via transmissionAdditionalDataField, it is sent twice as of 3.7.500 / 3.6.300. Remove that field from the field configuration.

Token Authentication

As an alternative to a password, a token can be used. The token is stored in a Shopware custom field on the customer profile.

Field	Description
Token variable name	Parameter name that the procurement system uses for the token
Token custom field	Technical name of the Shopware custom field on the customer profile where the token is stored

On login, the connector compares the submitted token with the value in the custom field of the matching Shopware customer.

As of 3.7.500 / 3.6.300

• A customer account deactivated in Shopware can no longer log in via token. Accounts that could still punch out despite being deactivated lose access.
• The token custom field has to be entered once for every system that uses the token login — the value could not be saved in earlier versions.

Additional Options

Option	Default	Description
Validate URL	on	Checks whether HOOK_URL is a valid HTTP/HTTPS URL. Turn off if the system passes a non-HTTP URL (e.g. SAPEVENT:POST for SAP).
Separate cart session	on	The punchout session gets its own empty cart; the customer's existing shop cart stays untouched. Customer-specific prices and discounts still apply. Leave it on if unsure. (called "Guest session" up to 3.7.400 / 3.6.200)
Close button behavior	Stay in shop	Defines where the user is directed when clicking Close. Stay in shop: returns to the shop home page. Redirect to hook: returns to the calling procurement system — only if a hook URL is known for the session, otherwise it automatically falls back to "Stay in shop".

Example Login URL (GET)

https://shop.example.com/AgiqonOciEntry/login
  ?USERNAME=buyer@company.com
  &PASSWORD=secret
  &HOOK_URL=https://procurement.company.com/oci/return

Example with Token

https://shop.example.com/AgiqonOciEntry/login
  ?TOKEN=abc123xyz
  &HOOK_URL=https://procurement.company.com/oci/return

Common Issues

Login fails — "URL validation"
If the procurement system passes a non-HTTP URL as the hook URL (e.g. SAPEVENT:POST), disable the Validate URL option.

Customer cannot log in

• Is the customer assigned to the system in the Customers tab?
• Is the system set to Active?
• Is the license key valid?
• Do the variable names match (e.g. ~username instead of USERNAME)?
• Does the customer assignment match the variable names that were sent? As of 3.7.500 / 3.6.300 a login is rejected when the customer is assigned to a system whose variable names the request does not send. The log entry names the candidate systems and the customer's system — see Customers & Units for details.