It is possible to create and update customer accounts via the account API. In addition, the customer can be logged into the webshop via this interface. The access rights to the individual areas of the customer data can be configured individually.

Technical specification

The interface to WEBSALE is implemented as a REST interface with a single access point, data is transferred as a payload in a JSON WebToken (JWT) via POST.

The REST interface can only be called via SSL (transport security), authentication via authorisation token is waived. Validation is carried out by signing the JSON WebToken, for which a separate SharedSecret is stored for each connector, and the permissions of the connector are configured by WEBSALE.

A call of the REST interface must always be made with an associated shop domain.

Interface behaviour

If address data and/or customer account data are transferred, it is checked whether the connector has the authorisation to check or set the data for the specified customer account. If no authorisation exists for at least one data field, no action is performed and a corresponding error is returned. No partial updates are carried out.

Addressing of the customer account by means of the e-mail address:

If a customer account with the specified email address already exists, the stored data from the customer database is merged with the transferred data and address data is validated against the checks configured in the webshop. When merging the data, the values in the transferred fields overwrite the existing data. Only if the validation is positive will the address data, as well as all other transferred data, be updated in the customer database.
If no customer account exists with the specified e-mail address, a new customer account is created after a positive check of any address data transferred. Optionally, data specified during connector configuration can be preset, e.g. a separate customer discount rate per connector.

Addressing of the customer account on the basis of a user index:

In this case, only an update or check of an existing customer account is possible analogous to addressing by means of the e-mail address.

For the address data check, the configuration of the associated subshop is determined based on the domains of the REST call.

Multiple accounts (different accounts for one e-mail address) cannot be created via the REST interface. An update or login for multiple accounts is only possible by specifying the user index.

Permissions

For each connector, WEBSALE defines the corresponding permissions. The following applies: Permissions must always be set explicitly.

The following permissions can be set:

Creating or updating an account
- List of permissible domains for which a new creation/update of e-mail addresses is possible (also applies to updates with UserIndex)
  Setting of customer-dependent discount rates
  Setting of subshop authorisations/main subshop
  Setting the customer number
  Setting of payment methods
  Setting the SuperUserID
  Setting the use of the order generator
  Setting a new password in combination with automatic, mandatory setting of a new password at next login
  Changing the e-mail address
Billing address data (with the exception of email address and customer number):
- General authorisation to transfer invoice address data
- Authorisation at field level:
  - Explicit specification of which fields may be set (individually)
  - General release of all fields (incl. simple WildCard support)
Data request:
- Connector may query login deeplink for forwarding a customer incl. automatic login

In addition, specific data fields can be set, which are automatically set when a new customer account is created and/or updated. These are applied independently of the permissions granted:

Creating or updating an account
- Customer-dependent discount rate
- Subshop authorisations/main subshop
- Payment methods
- Use of the order generator
Billing address data (except for e-mail address and customer number):
- Any values per address data field

The following applies:
If address data is to be preset, a valid address must also be created in combination with the preset values when a new account is created. If this is not the case, no new customer account will be created.

General rule:

As soon as data is to be transferred or taken over (automatically set/preset), a valid data record must be created after merging this data with the existing data. If this is not the case, no data is transferred or new data records are created and the interface returns an error code.

Availability and power consumption:

The account API is activated by WEBSALE AG following an application by the shop operator. The number of usable connectors is defined; this can be increased or reduced later by application. The configuration of the individual connectors can be done by the shop operator himself. The use of the account API results in increased performance consumption.

Configuration

The configuration is done in the global configuration file account-api-access.config.json.

The configuration is done in JSON format, the accesses are created as a JSON array.

A separate access object is specified for each access.

Access object

Field	Value	Required	Description

Field	Value	Required	Description
connectorid	alpha-num String	x	Any, but unique technical ID of the connector
secret	String	x	Password, shared secret for JWT
description	String		Description of the connector
permissions	Permission object	x	Authorisations/restrictions of the connector
data	Data update object		Rule set for automatically setting or updating customer data when called via this connector

Permission object

Field	Value	Required	Description

Field	Value	Required	Description
accountrestrictions	Object	x	Access restrictions
accountrestrictions/createaccount	Boolean		Connector may create new accounts
accountrestrictions/updateaccount	Boolean		Connector may update existing accounts
accountrestrictions/alloweddomains	String-Array	x	List of permitted domains of the account email address. The connector may perform actions on all associated accounts contained in this list. An asterisk can be specified as any part (= part of the domain separated by a dot): "domain.de": Authorisation for accounts: @domain.de no authorisation for accounts: @sub.domain.de ".domain.de": Authorisation for accounts: @domain.de, @sub.domain.de, @sub2.domain.de no authorisation for accounts: @sub2.sub.domain.de "domain.": Authorisation for accounts: @domain.de, @domain.at, @domain.xyz no authorisation for accounts: @domain.domain2.de, @domain.co.uk "*": Authorisation for all accounts
accountdata	Object		Authorisations, which data of the customer account the connector is allowed to set
accountdata/surchargelimit	Boolean		Set customer-specific assessment limit for minimum quantity surcharge
accountdata/surcharge	Boolean		Set customer-specific amount of the minimum quantity surcharge
accountdata/userdiscount	Boolean		Set customer-specific discount rate or list
accountdata/mainsubshop	Boolean		Set main subshop
accountdata/subshoplist	Boolean		Set subshop access authorisations
accountdata/customernumber	Boolean		Set customer number
accountdata/allowedpayments	Boolean		Set list of allowed payment methods
accountdata/superuserid	Boolean		Set SuperUserID
accountdata/superuseridlist	Boolean		Set SuperUserIDList
accountdata/superuserrestricted	Boolean		Set restricted SuperUser
accountdata/subvention	Boolean		Set subsidy amount
accountdata/usergroup	Boolean		Set customer groups
accountdata/ordergenerator	Boolean		Allow order generator
accountdata/setpassword	Boolean		Set new password with automatic forced setting of a new password at next login
accountdata/changeemail	Boolean		Change email address
addressdata	Object		Authorisations, which invoice address data fields the connector is allowed to set
addressdata/transfer	Boolean		Connector is (generally) authorised to transfer invoice address data
addressdata/ignorechecksoncreate	Boolean		Ignores all address entry checks of the billing address if a new account has been created and billing address data has been transferred. ATTENTION: If this switch is set, inconsistent data records may result!
addressdata/ignorechecksonupdate	Boolean		Ignores all address entry checks of the billing address when an existing account has been updated and billing address data has been transferred. ATTENTION: If this switch is set, inconsistent data records may result!
addressdata/fields	Object		Authorisation per field (or field group)
addressdata/fields/<id>	Boolean		Authorisation at field level. An asterisk can be specified at the end of an ID: "FirstName": Authorisation for the first name "Suffix": Authorisation for all suffix fields (Suffix1, Suffix2, ..., Suffix 12, ...) "": All fields (ATTENTION! This also includes critical fields)
return	Object		Authorisation which data the connector is allowed to query
return/loginlink	Boolean		Authorisation to return a DeepLink incl. automatic login of the customer to the shop
return/loginlinkvalidforseconds	Integer		Validity of the login link in seconds. Default: 300 Max: 3600

Data update object

Field	Value	Required	Description

Field	Value	Description
preset	Object	Data presetting when creating a new customer account via the connector
preset/accountdata	Object	Customer account data preset (only part of the data such as the accountdata object as described under REST API is supported).
preset/accountdata/surchargelimit	String	Customer-specific assessment limit for minimum quantity surcharge
preset/accountdata/surcharge	String	Customer-specific amount for minimum quantity surcharge
preset/accountdata/userdiscount	String	Customer-specific discount (in percent)
preset/accountdata/userdiscountlist	String	List of customer-specific and product-dependent discount rates (see import data structure)
preset/accountdata/mainsubshop	String	Main subshop ID of the customer
preset/accountdata/subshoplist	String	comma-separated list of subshop permissions
preset/accountdata/allowedpayments	String	Comma-separated list of assigned payment type codes
preset/accountdata/ordergenerator	Boolean	Authorisation to use the order generator
preset/accountdata/usergroup	String	Comma-separated list of customer group indices
preset/addressdata	Object	Data default billing address (data fields analogous to the description as under REST API)
preset/addressdata/fields	Object	Data fields
preset/addressdata/fields/<id>	String	Value
overwrite	Object	Data update on update/query of a customer account via the connector
overwrite/accountdata	Object	Data update customer account (only a part of the data like the accountdata object as described under REST-API is supported)
overwrite/accountdata/surchargelimit	String	Customer-specific assessment limit for minimum quantity surcharge
overwrite/accountdata/surcharge	String	Customer-specific amount for minimum quantity surcharge
overwrite/accountdata/userdiscount	String	Customer-specific discount (in percent)
overwrite/accountdata/userdiscountlist	String	List of customer-specific and product-dependent discount rates (see import data structure)
overwrite/accountdata/mainsubshop	String	Main subshop ID of the customer
overwrite/accountdata/subshoplist	String	comma-separated list of subshop permissions
overwrite/accountdata/allowedpayments	String	Comma-separated list of assigned payment type codes
overwrite/accountdata/ordergenerator	Boolean	Authorisation to use the order generator
overwrite/accountdata/usergroup	String	Comma-separated list of customer group indices
overwrite/addressdata	Object	Data update billing address (data fields analogous to the description as under REST API)
overwrite/addressdata/fields	Object	Data fields
overwrite/addressdata/fields/<id>	String	Value

Beispiel

[
{
  "connectorid": "connectorA",
  "secret": "sharedSecret",
  "description": "Beispielconnector A: Volle Berechtigung",
  "permissions":
  {
    "accountrestrictions":
    {
      "createaccount": true,
      "updateaccount": true,
      "alloweddomains":
      [ "*", "testshop.de", "testshop.*" ]
    },
    "accountdata":
    {
      "userdiscount": false,
      "mainsubshop": false,
      "subshoplist": false,
      "customernumber": false,
      "allowedpayments": false,
      "superuserid": false,
      "ordergenerator": false,
      "setpassword": false,
      "changeemail": false
    },
    "addressdata":
    {
      "transfer": true,
      "fields":
      {
        "id": true,
        "suffix*": true
      }
    },
    "return":
    {
      "loginlink": true
    }
  },
  "data":
  {
    "preset":
    {
      "accountdata":
      {
        "userdiscount": "5",
        "mainsubshop": "deutsch",
        "subshoplist": "deutsch,englisch",
        "allowedpayments": "5,6,7",
        "ordergenerator": true
      },
      "addressdata":
      {
        "fields":
        {
          "suffix11": "asdf",
          "suffix12": "wert"
        }
      }
    },
    "overwrite":
    {
      "accountdata":
      {
        "userdiscount": "5",
        "mainsubshop": "deutsch",
        "subshoplist": "deutsch,englisch",
        "allowedpayments": "5,6,7",
        "ordergenerator": true
      },
      "addressdata":
      {
        "fields":
        {
          "suffix12": "wert"
        }
      }
    }
  }
},
{
  "connectorid": "connectorB",
  "secret": "sharedSecret2",
  "description": "Beispielconnector B: nur Login bestehender Kunden von xyz.de. Setzen von 3% wenn über Konnektor kam",
  "permissions":
  {
    "accountrestrictions":
    {
      "alloweddomains":[ "xyz.de"]
    },
    "return":
    {
      "loginlink": true
    }
  },
  "data":
  {
    "overwrite":
    {
      "accountdata":
      {
        "userdiscount": "3"
      }
    }
  }
}
]

REST-API

JSON-WebToken (JWT)

Endpoint: /_api/shop/Account

The REST API is called with a POST request to the endpoint. A JSON WebToken with the corresponding payload is transferred as POST data:

Header:
Signature algorithm used: HS256
Type used: JWT

Payload:
(see description below)

Verify-Signature:
HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), <sharedSecret of the connector>)

Beispielanfrage:

Payload:

{
  "hello": "world"
}

SharedSecret: secretly

Decoded JWT:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "hello": "world"
}.HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),secretly
)

Encoded JWT (POST-Data):

PayLoad

Field	Value	Required	Description

Field	Value	Required	Description
iss	String	X	ID of the connector
exp	NumericDate/String		Expiry date
email	String	X*	E-mail address of the customer account E-mail address OR UserIndex must be specified.
userindex	String	X*	UserIndex of the customer account Email address OR UserIndex must be specified
return	Object		Indication of the information requested
return/loginlink	Boolean		Request DeepLink for automatic login of the customer account to the shop
data	Object		Customer account data to be updated or set
data/accountdata	Object		Data update customer account (only a part of the data like the accountdata object as described under REST-API is supported)
data/accountdata/surchargelimit	String		Customer-specific assessment limit for minimum quantity surcharge
data/accountdata/surcharge	String		Customer-specific amount for minimum quantity surcharge
data/accountdata/userdiscount	String		Customer-specific discount (in percent)
data/accountdata/userdiscountlist	String		List of customer-specific and product-dependent discount rates (see import data structure)
data/accountdata/mainsubshop	String		Main subshop ID of the customer
data/accountdata/subshoplist	String		comma-separated list of subshop permissions
data/accountdata/allowedpayments	String		comma-separated list of payment type codes
data/accountdata/customernumber	String		Customer number
data/accountdata/superuserid	String		SuperUserID
data/accountdata/superuseridlist	String		SuperUserID-List
data/accountdata/superuserrestricted	Boolean		Restricted SuperUser
data/accountdata/usergroup	String		Comma-separated list of customer group indices
data/accountdata/subvention	String		Subvention
data/accountdata/ordergenerator	Boolean		Set authorisation to use the order generator
data/accountdata/setpassword	String		new password (a new password is automatically set for the next login!)
data/accountdata/changeemail	String		new e-mail address
data/addressdata	Object		Data Update/Set Billing Address
data/addressdata/fields	Object		Data fields
data/addressdata/fields/<id>	String		Value
data/addressdata/fields/TitleCode	String		Title code as defined in title.dat. Technical field Title is not supported.
data/addressdata/fields/SalutationCode	String		Salutation code as defined in salutation.dat. Technical field Salutation is not supported.
data/addressdata/fields/CountryCode	String		Country code as defined in country.dat. Technical field Country is not supported.

PayLoad example:

Update the customer account with the e-mail address "test@domain.de". 5% customer discount and set field Suffix12 of the billing address to "conA", have LoginLink returned on reply:

Response

In the event of an error, the interface responds with the HTTP status codes 401/403, if applicable, otherwise with HTTP status code 400. In addition, a JSON object is returned with the corresponding error code and error message, if applicable.

Beispiel:

If successful, the interface responds with HTTP status code 200. In addition, a JSON object is returned with code and an optional return object containing the requested data.