How do I integrate a custom online store?

Pro

Typically, a plugin is installed in the online store to connect the configurator to it. This plugin provides an interface that K3 can access. This is how the store integration is implemented.

This API can also be used for custom integrations with 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 K3 API methods. To do so, it must be able to authenticate itself. Likewise, the plugin’s endpoints (with the exception of the 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: K3 provides the plugin with a token for using the K3 API and a secret to secure the plugin API. In response, the plugin sends K3 the URLs of its API endpoints (since these can vary depending on the shop system). To do this, K3 sends a POST request to a fixed URL of the plugin.

POST <URL>

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

token: a K3 API token in plain text that the plugin must provide when calling the API.
secret: A random string that K3 specifies in the X-Secret header when calling the plugin. The plugin should verify that the secret is correct.

The following values must be returned in a JSON object:

cart URL of the shopping cart API
articles URL of the product API

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

Once this is implemented, you can already access verbinden from K3.

Products & Prices

The plugin provides an endpoint at a defined URL that returns all products.

GET <articles>

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

no Product 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 (as item price in K3):
- price (number): The price amount
- currency (string, optional): The currency of the price (currently not used)
- unit (string, optional): The unit of the price (currently not used)
- sort (number, default 0): Priority of the price when multiple valid prices exist
- displayOnly (string, optional): Only if this value is NULL is the price used for price calculation. Otherwise, these can be, for example, strike-through prices. The type is then determined by the content of this field, e.g., 'strike-through'.
- fromDate (datetime, optional): Start of the validity period—NULL: always valid.
- toDate (datetime, optional): End of the validity period—NULL: valid indefinitely.
- fromQty (number, optional): Minimum valid quantity (volume discount) - NULL: 0 or higher.
- toQty (number, optional): Maximum valid quantity (volume discount) - NULL: unlimited.
- toQty (number, optional): Maximum valid quantity (volume discount) - NULL: any number.
- type (string, optional='fixed'): can take one of the following values:
  - fixed: Fixed price
  - surcharge: Surcharge—the item is shown to the customer; its price is the surcharge added to 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 returns a document like this:

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

This call is protected by secret.

Shopping Cart

At a defined URL, the plugin provides an endpoint that allows a configuration to be added to the shopping cart. After calling

GET <cart>?cfg={code}

the plugin queries the Shop API in K3. It then adds the retrieved data to the current user’s shopping cart. Therefore, this endpoint must be called from the frontend.

How the configuration is added to the shopping cart is up to the plugin. Several approaches are possible, and this can be configured within the plugin if necessary:

Each item in the configuration’s bill of materials is added to the shopping cart individually.
For each configuration, a new item with a name, description, price, and image is created and added to the shopping cart.
A specific item is added to the shopping cart, and the configuration data (description, price, image, code) is stored as metadata for the shopping cart item.
If the store has a “set” feature, a set containing the items from the bill of materials is added to the shopping cart.

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

The endpoint can be opened directly, e.g., in a new tab: It returns an HTTP redirect back to the shopping cart. This allows us to bypass potential CORS issues on the store.

This call is not protected by secret.

K3 Shop API

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

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

Since the response may include customer data, authentication is required: To do this, set this header with the K3 API token provided in the Authentication section:

Authorization: Bearer TOKEN

Parameters

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
currency (string): Currency
description (string): A description of the user selections—in HTML
image (string, optional): URL of the configuration image
frontendURL (string): Absolute URL to the frontend
adminURL (string): Absolute URL to the admin panel
pdf (string): Absolute URL for the PDF download
customer (object, optional): Customer data—typically not collected in a store context.
variables (optional): Product attributes; should be stored as metadata for the shopping cart item whenever possible.
- variable: Attribute—the same attribute may appear multiple times, for example, in component lists.
  - id: Internal ID; avoid using if possible
  - key: Can be set on the attribute in developer mode
  - label: Name of the variable
- value: Value entered or selected by the user. For a Mehrfachauswahl-Merkmal (type multiSelect), this is an array with one entry per checked option, in the order they were selected. If nothing is checked, the attribute—like any other unselected attribute—does not appear at all.
- selected: The option selected directly or indirectly by the user (for numbers, e.g., possibly the number range). For a multiple-selection attribute, this is also an array.
  - id: internal ID; avoid using this if possible
  - key: can be set to the value in developer mode
  - label: Name of the value
- variables: If this attribute value can be configured independently (e.g., in a parts list), an attribute list is found here, one level deeper. This can be nested to any depth.
bom (object): Bill of materials, formatted as follows:
- article (string): Item number
- articleName (string): Item name
- qty (number): Quantity
- amount (number, optional): Quantity
- priceUnit (number): Item price
- priceTotal (number): Price of the line item
- unit (string, optional): Unit
- main (boolean, optional): Only one item may have main==true. If the store allows it, this item (with its quantity, which is normally 1) is added to the shopping cart, and all others are placed below it as sub-items.
files (list, optional): Configuration files
- key: A name key for the file, e.g., 'camera_1' or 'logo'; may be ambiguous
- filename: File name upon 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 configuration status is set to ordered.

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

Saves a configuration change. Authentication is required here as well, of course.

Parameters

cfg (string): The code of the configuration

Body

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

Programmatic Shopping Cart Integration with an IFrame

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

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

Click the pencil icon on the block containing the price and Order buttons
Uncheck the box next to Send to Store
Check the box next to Send JavaScript Event

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

The following code must now be inserted into 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 shop should now use the Shop API above to retrieve the configuration data and add it to the shopping cart.

Authentication​

Products & Prices​

Shopping Cart​

K3 Shop API​

Order​

Programmatic Shopping Cart Integration with an IFrame​