How do I connect an individual store?

Pro

Normally, a plugin is installed in the store to connect the configurator to a store. This provides an interface that the K3 can access. This is then used to implement the store connection.

This API can also be used for individual connections to your own stores or other backend systems. To do this, the following endpoints must be implemented in a plugin on the store side:

Authentication

The plugin calls API methods of the K3. It must be able to authenticate itself for this. Likewise, the endpoints of the plugin (exception: shopping cart) should not be openly accessible.

For this reason, K3 and the plugin are first connected to each other. The plugin is provisioned from K3: A token for using the K3 API and a secret for securing the plugin API are communicated to the plugin by the K3. In response, the plugin sends the K3 the URLs of its API endpoints (as these can be different for each store system). To do this, the K3 calls a fixed URL of the plugin via POST request.

POST <URL>

The URL must be specified in the configurator settings in K3. The following parameters are transferred:

token a K3 API token in plain text that the plugin must specify when calling the API.
secret a random string that the K3 specifies in the X-Secret header when the plugin is called. The plugin should check whether the secret is correct.

The following values must be returned in a JSON:

cart URL of the shopping cart API
articles URL of the article API

This call must also be secured with the secret as soon as one is set in the plugin. The old secret must therefore be set in the X-Secret header if a new one is to be set.

If this is implemented, you can already verbinden from K3.

Articles & prices

Under a defined URL, the plugin provides an endpoint with which all articles are delivered.

GET <articles>

the plugin determines all relevant articles and their prices in JSON as an array with the following entries:

no article number
name Name
description Description
category Category (as text)
deliveryTime (integer, optional): Number of days until delivery
stockQty (number, optional): current stock level
prices (array) with the following entries (like item price in K3):
- price (number): The amount of the price
- currency (string, optional): The currency of the price (currently not used)
- unit (String, optional): The unit of the price (not currently used)
- sort (number, default 0): Priority of the price for multiple valid ones
- displayOnly (string, optional): The price is only used for price calculation if this value is NULL. Otherwise these can be strike prices, for example. The type is then determined by the content of this field, e.g. 'strike'.
- fromDate (datetime, optional): Start of the valid period - NULL: always.
- toDate (datetime, optional): End of the valid time period - NULL: until eternity.
- fromQty (number, optional): Minimum valid number (quantity discount) - NULL: from 0.
- toQty (number, optional): Maximum valid number (quantity discount) - NULL: any number.
- toQty (number, optional): Maximum valid number (quantity discount) - NULL: any number.
- type (string, optional='fixed'): can have one of the following values:
  - fixed: fixed price
  - surcharge: surcharge - the article is shown to the customer, its price is the surcharge on the sum of all fixed prices
  - surchargeHidden: hidden surcharge - the item is not shown to the customer, all fixed prices are increased by the surcharge.

In the simplest case, the plugin provides such a document:

[
    {
        "no":"ART_0001",
        "name": "Erster Artikel",
        "description": "Ist länger…",
        "prices": [
            {"price":123.34}
        ],
    },
    ...
]

This call is secured with secret.

Shopping cart

The plugin provides an endpoint under a defined URL with which a configuration can be placed in the shopping cart. After calling

GET <cart>?cfg={code}

the plugin queries the Shop-API from K3. It then enters the data received into the shopping cart of the current user. **This endpoint must therefore be called from the frontend

How the configuration is stored in the shopping cart is a matter for the plugin. Several types are conceivable, if necessary this can be set in the plugin:

Each item in the configuration parts list is placed in the shopping cart individually.
A new item with name, description, price and image is created for each configuration and added to the shopping cart.
A specific item is placed in the shopping cart and the configuration data (description, price, image, code) is stored in metadata for the shopping cart item.
If the store has a set feature, a set can be added to the shopping cart with the items in the parts list.

In all cases, it should be possible to return from the shopping cart to the configurator with the configuration.

The endpoint can be opened directly, e.g. in a new tab: It returns an HTTP redirect to the shopping cart. This avoids possible CORS problems in the store.

This call is not secured with the secret.

K3 Shop API

This endpoint is provided by K3 and called by the store plugin:

GET https://k3-api.objectcode.de/api/v1.0/cfg/{cfg}/shop

As customer data may be included in the result, authentication is required: For this purpose, this header is set with the K3 API token provided in the Authentication:

Authorization: Bearer TOKEN

Parameter

cfg (string): The code of the configuration

Result

code (string): The code of the configuration
app (string): The name of the configurator
price (number): The total price
description (string): A description of the user selections - in HTML
image (string, optional): URL of the image of the configuration
frontendURL (string): Absolute URL to the frontend
adminURL (string): Absolute URL to the AdminPanel
customer (object, optional): Customer data - not normally recorded in the store context.
variables (optional): Product characteristics, should be stored as metadata at the shopping cart item if possible.
- variable: Feature - the same feature may appear more than once if it is a multiselect.
  - id: internal ID, do not use if possible
  - key: can be set on the feature in developer mode
  - label: Name of the variable
- value: Value entered or selected by the user
- selected: The option selected directly or indirectly by the user (e.g. the number interval for numbers)
  - id: internal ID, do not use if possible
  - key: can be set to the value in developer mode
  - label: Name of the value
- variables: If this characteristic value can be configured on its own (for a parts list), a list of characteristics can be found here, one level deeper. This can be nested to any depth.
bom (object): Parts list, formatted:
- qty (number): Quantity
- article (string): Article number
- main (boolean, optional): only one article may have main==true. If the store allows this, this article (with its quantity, which is normally 1) is placed in the shopping cart and all others are placed below it as sub-articles.
files (list, optional): Files for configuration
- key: A name key for the file, e.g. 'camera_1' or 'logo', can be ambiguous
- filename: File name during upload
- url: URL of the file

Example:

{
  "code": "TG7DTPR9CP",
  "app": "Chair",
  "price": 323,
  "frontendURL": "https://k3.objectcode.de/app/?code=GB1RCMQ749",
  "adminURL": "https://k3.objectcode.de/app/#/admin/apps/3/configurations/257",
  "customer": {
    "address": null,
    "dataPrivacy": "Die Datenschutzhinweise habe ich zur Kenntnis genommen und akzeptiere sie.",
    "name": "Mustermann",
    "email": "mustermann@test.test",
    "phone": null,
    "remark": null,
    "company": null,
    "taxID": null,
    "checkboxAccepted": true
  },
  "variables": [
    {
      "variable": {
        "id": 31,
        "key": null,
        "label": "Rest Leg"
      },
      "value": "Ohne Rest leg",
      "selected": {
        "id": 91,
        "key": null,
        "value": null,
        "label": "Ohne Rest leg"
      }
    },
    {
      "variable": {
        "id": 32,
        "key": null,
        "label": "Lederfarbe"
      },
      "value": "#dec7c7",
      "selected": {
        "id": 93,
        "key": null,
        "value": "#dec7c7",
        "label": "Grau"
      }
    }
  ],
  "bom": [
    {
      "article": "Test2",
      "qty": 1
    }
  ],
  "files": [
    {
      "key": "camera_0",
      "filename": "blob",
      "url": "http://k3.objectcode.de/data/client/2ee94f75-2a17-45d0-a17d-05ac99007499/app/3771b7e2-a799-4e32-93cc-bfb247116e1b/cfg/TG7DTPR9CP/hO0y2HhCv3RGLCeBeIzFx8mbCXkfdqak9yF12PqU.png"
    },
    {
      "key": "camera_1",
      "filename": "blob",
      "url": "http://k3.objectcode.de/data/client/2ee94f75-2a17-45d0-a17d-05ac99007499/app/3771b7e2-a799-4e32-93cc-bfb247116e1b/cfg/TG7DTPR9CP/hRDYMMJKBeOo4XclWsimGIQhnmVfmcJIBNqPB0gB.png"
    }
  ],
  "image": "http://k3.objectcode.de/data/client/2ee94f75-2a17-45d0-a17d-05ac99007499/app/3771b7e2-a799-4e32-93cc-bfb247116e1b/cfg/TG7DTPR9CP/hO0y2HhCv3RGLCeBeIzFx8mbCXkfdqak9yF12PqU.png"
}

Order

When a shopping cart is ordered, the plugin calls the Configuration API. The status of the configuration is set to ordered.

PUT https://k3-api.objectcode.de/api/v1.0/cfg/{cfg}/state

Saves a configuration change. Authentication is of course also required here.

Parameter

cfg (string): The code of the configuration

Body

state (string): One of: draft, basket, quoted, ordered

Programmatic shopping cart connection for iframe

If the configurator is already embedded in an IFrame in the store, opening the shopping cart in a new tab may not be desired new tab may not be desired.

In this case, the configuration can be transferred to the store invisibly for the user.

Click on the pencil icon on the block containing the price and order buttons
Remove the tick from Send to shop
Check the box next to Send JavaScript event

Now, as soon as the user presses the button, the configuration is saved (generating the configuration code) and then a JavaScript event is sent to the surrounding frame containing the configuration code.

The following code must now be inserted in the surrounding frame:

  window.addEventListener("message", function (event) {
      if(event.data.type == "K3ConfigurationSaved"){
          console.log("Received message: " + event.data.code);
          // hier den Event bearbeiten. Den Konfigurationscode findet man in: event.data.code
      }
  }, false);

The store should now retrieve the configuration data using the Shop API above and place it in the shopping cart.

Authentication​

Articles & prices​

Shopping cart​

K3 Shop API​

Order​

Programmatic shopping cart connection for iframe​