Runtime integrations

Runtime integrations is our name for configurable services, that are being activated by one of our apps. For instance the POS can perform an E-com Product Search and the Stock app can perform an External Product Lookup.

Common to these are that they can all be implemented by adding HTTP(S) endpoints that can be called from the Ka-ching system. This means that commonly, they are configured with a set of HTTP request parameters as well as a transformation on the returned data (if the format does not already match what is expected by the integration).

E-commerce products in the Ka-ching system can either be imported directly into the system using the online channel, or they can be left out of the system and only be added directly to the basket through an online e-com product search.

The e-com product format differs slightly from the regular product format in that the returned products cannot have variants. In other words, the returned products are concrete instances of a product or a specific product variant that can be added to the basket directly.

Here is the full E-com product model:

{
    "id": "<string, optional>",
    "variant_id": "<string, optional>",
    "name": "<L10nString, optional>",
    "variant_name": "<L10nString, optional>",
    "description": "<L10nString, optional>",
    "barcode": "<string, optional>",
    "image_url": "<string, optional>",
    "product_group": "<string, optional>",
    "retail_price": "<number, required>",
    "sale_price": "<number, optional>",
    "cost_price": "<number, optional>",
    "taxes": "<array of taxes, optional>"
}

Please refer to the general Product model in the Models document for details about each of the properties.

Stock: External Product Lookup

When registering received goods in the Stock app, the registered products must usually already exist in the Ka-ching system.

But you can create an integration to look up product details in an external system. If you do this, then the product details can automatically get imported while you are registering the received goods.

As an example, Saxo already has product details and price information for a wealth of books, so for a Saxo shop, an integration can look up these details through an API at Saxo.com and have them being imported simply by scanning the received books.

The format of the returned Product is described in the Models document.

Customer Lookup

In the Ka-ching POS, a customer can be added to a sale. Doing this allows for some interesting functionality.

First and foremost, the customer id will be available on the exported sale data, so that you may register these details in your own system.

Secondly, if your system contains information about the customer address, phone, email, etc., this can be used for pre-filling shipping details for e-commerce orders, and pre-filling email address for the receipt.

Thirdly, you can create discount campaign rules that only trigger when a customer is added to the basket, so this can be used to create customer discounts.

[
{
    "identifier": "<string, required>",
    "name": "<string, optional>",
    "street": "<string, optional>",
    "city": "<string, optional>",
    "postal_code": "<string, optional>",
    "country": "<string, optional>",
    "country_code": "<string, optional>",
    "phone": "<string, optional>",
    "email": "<string, optional>",
    "additional_info": "<string, optional>",
    "balance": { // optional
        "identifier": "<string, required>",
        "balance": <number, required>
    }
},
...
]

As can be seen, all properties other than the identifier are optional. The more of the properties that are filled out, the better the integration will be.

Notice the country_code field. This may be used in conjunction with the Shipping Options integration, where the integration can limit the accepted country codes for shipping.

Customer Specific Discounts

It is possible to configure the system with discounts that only apply for a specific customer.

If customer specific discount are enabled, the Ka-ching system will ask for a list of discounts for a given customer id. Other parameters available to the endpoint are: the current market and the currency_code of the current base currency.

The response from this web service should be a json-encoded array of discount objects - similar to those described in the Discount Campaign Import Endpoint chapter. But since the request is for a specific market and a specific currency code, it is only needed to send new prices and the like for the specific market:

[
    {
            "id": "0003",
            "type": "new_price_discount-single_product",
            "product_id": "abc",
            "new_price_per_item": 42,
            "name": "New price discount",
            "display_name": "New price discount",
            "priority": 80
    }
    ...
]

Shipping Options

When adding e-commerce products to the basket, the cashier will need to enter shipping details, that are included in the sale.

By creating a shipping options integration, your server will be called with the address of the customer, the shop id and the currency code of the base currency in the shop. Your server can then reply with a list of shipping options, where each option contains a price for the delivery, an identifier of your own choice, a title and some details.

The selected option will be included in the sale, and this allows your servers to process the delivery options when placing an order in your e-com system.

[
    {
        "id": "<string, required>",
        "price": "<number, required>",
        "title": "<string, required>",
        "subtitle": "<string, required>"
    },
    ...
}

Gift card

The current gift card integration consists of four actions: create, activate, read and pay. These will be called at appropriate times and allow for your server to control the creation and payment flow.

All four integrations should return a full Giftcard entity with the new state:

{
    "amount": "<number, required>",
    "code": "<string, required>",
    "create_date": "<unix time stamp with decimals, number, required>",
    "currency_code": "<string, required, ISO 4217 currency code>",
    "expiry_date": "<unix time stamp with decimals, number, required>",
    "id": "<string, required>",
    "status": "<number, required, may be 1=created, 2=active or 3=used>",
    "external_giftcard": "<json object, optional>"
}

Here amount is the currently available amount, code is the customer-displayed id of the gift card, which is used to create bar codes for printing, create_date and expiry_date are pretty self-explanatory, currency_code is required in order to prevent usage in the wrong market, id is an internal identification of the gift card, status is the current state of the gift card, and external_giftcard may be used by you to carry any information that is not directly relevant to the Ka-ching system, but may be required by your integration.

Create

From an action in the Ka-ching POS, you can create a gift card and add it to the basket. The gift card will be created in an inactive state, and only activated once the sale has been fully paid.

Activate

Called with the details of an inactive gift card once the gift card has been paid.

Read

Called from an action in the Ka-ching POS to let the customer know the balance.

Pay

Called from the Ka-ching POS when a gift card is being used for payment in the POS.

Customer account payment

The current customer account integration consists of two actions:read and pay. These will be called at appropriate times and allow for your server to control the payment flow.

Both integrations should return an entity containing an amount:

{
    "amount": "<number, required>",
}

For the customer account read action, the amount should refer to the current balance of the customer account.

For the pay action, the amount should contain the actual amount that was used. This could be different than the amount requested to be used, but if it is not possible to pay with the desired amount, a better option is probably to let the payment fail.

Any non-200 response from the server will be treated as a failure to perform the payment.

Read

Called from an action in the Ka-ching POS to get the current balance. Parameters are customer_id and currency_code.

Pay

Called from the Ka-ching POS when a customer account is being used for payment in the POS. Parameters are amount, customer_id and currency_code.