Sitoo

Sitoo Integration with Omnium

Omnium has a comprehensive integration with Sitoo which includes products, customers, orders, stores, and inventory. For a better understanding of the omnichannel features, refer to the Sitoo Omni Sales Guide.

Basic setup

1. Global Sitoo Connector

First, ensure that the global Sitoo connector is defined under Configuration -> Settings -> Advanced -> Connectors.

If not, click on the three dots in the top right corner to edit the JSON list of connectors and add the following:

{
    "name": "sitoo",
    "type": "pos",
    "isAuthenticatedManually": true,
    "timeOut": "00:00:00",
    "implementations": [
        "IOrderExporter",
        "ICartExporter"
    ],
    "properties": [
        {
            "key": "SitooOrderType",
            "value": "PosSitoo",
            "editKey": true
        }
    ],
    "customHeaders": [],
    "disableStandardErrorPolicy": false,
    "enabledForMarkets": [],
    "disabledForMarkets": []
}

The "SitooOrderType" property determines the order type for orders originating from Sitoo and should correspond to something under Configuration -> Settings -> Orders -> Order Types.

2. Obtain API Keys

Next, obtain your Sitoo API keys (preferably at least three) and insert them into the Sitoo integration GUI. The API-key should be in the format: base64_encode("{API ID}" + ":" + "{password}"), which is found under "Add Request Header", when you obtain the API key from Sitoo. Along with the base URL, account number, and e-shop ID (usually 1), you need to select the market corresponding to the Sitoo back office. Each Sitoo back office per market allows for product databases with different languages and currencies.

3. Configure Stores and Warehouses

Next, we need to connect/map the warehouses in Sitoo and Omnium. In Sitoo, warehouses is an entity seperate from stores, while in Omnium, all warehouse is a store. In the Sitoo integration GUI, there is a panel you can use. However, it is still under development and often not sufficient.

The connection between warehouses should be both ways, with an external ID in Omnium with key "SitooWarehouseId": ../_images/sitoo-store-ids.png

And an external ID in Sitoo:

In addition, we need to specify in Omnium the Sitoo warehouse type using a property with the key "SitooWarehouseType":

We recommend using virtual, as Omnium is the master of stock levels. See https://developer.sitoo.com/guides/stores-and-warehouses#warehouses.

With the warehouses being one to one between Sitoo and Omnium, the next step is stores in Sitoo. These need to have their external Id set to the Id of the corresponding store in Omnium:

The store's external ID is used by the integration to set the correct store on the order. This value is not used for stockkeeping, but it is still crucial to set it correctly.

4. Store Mapping

In Omnium, ensure the store’s external ID matches the corresponding store in Sitoo. This external ID is used by the integration to assign the correct store to the order.

Order Flow

The order flow is based on an event subscription, where Sitoo notifies event subscribers about changes in orders. To register the Omnium connector as an event subscriber, navigate to Settings -> Event Subscription in the Sitoo back office and use the following JSON configuration:

{
    "event_subscriptions": [
        {
            "base_url": "https://apitest.omnium.no/api/sitoowebhook/DevShop/NOR/",
            "api_token": "stupidSecret",
            "event_types": [
                "order",
                "order-delivery",
                "warehouse-transaction"
            ]
        }
    ]
}

Replace "DevShop" with your tenant ID, "NOR" with your market ID, and provide an actual api_token that corresponds to the WebhookApiKey property in the Sitoo connector.

Product Sync

Sitoo and Omnium have different ways of storing and structuring product data, and due to rate limits in Sitoo's API, product data export from Omnium to Sitoo can take time.

Product Sync Considerations

• Ensure all SKUids and EAN numbers are unique for a given language/market.
• Variants should not be separate products but should exist under a parent product.
• Products should be available on the specific market corresponding to the Sitoo back office.
• Images should have the correct file extension in Omnium.

Product Sync Settings

Specify product sync settings for the global and market connectors as properties. For example, to display color, name, and size on product variants in Sitoo, add the following:

{
    "key": "SitooVariantGroupProperty",
    "value": "Color|Name|Size"
}

Also, set the maximum image size:

{
    "key": "MaxImageSize",
    "value": "2000|2000|4000000"
}

Scheduled Tasks

To export products to Sitoo, add the following scheduled tasks in Configuration -> Settings -> Advanced -> Scheduled Tasks:

1. Sitoo Product Exporter Task:

   {
       "schedule": "*/45 * * * *",
       "implementationType": "SitooProductExporterScheduledTask",
       "isDisabled": false
   }

2. Sitoo Full Product Export Task:

   {
       "schedule": "* * * * *",
       "implementationType": "SitooFullProductExportScheduledTask",
       "isDisabled": true
   }

The SitooProductExporterScheduledTask exports only the changed products, while the SitooFullProductExportScheduledTask exports all products. You can trigger the full product export manually via the scheduled tasks GUI.