Configuration - OneStock [internal]

To correctly use the connector you’ll have to configure your OneStock instance with few things:

ACLs - mandatory

The connector needs the bellow ACLs to run correctly.

You will have to add those rules in your Configuration > Security > ACL rules

{
  "policies": [
    {
      "actions": [
        "GET",
        "POST",
        "PATCH",
        "DELETE"
      ],
      "description": "allow *",
      "effect": "allow",
      "resources": [
        "orders<.*>",
        "line_items<.*>",
        "parcels<.*>",
        "pieces<.*>",
        "check",
        "configurations<.*>",
        "delivery_configs",
        "delivery_promises",
        "items",
        "translators",
        "requests<.*>",
        "sales_channels",
        "webhooks<.*>",
        "rulesets",
        "ruleset_chainings<.*>",
        "endpoints",
        "stock_export"
      ],
      "subjects": [
        "api_user"
      ]
    }
  ]
}

You then have to create an API user for the client an transfer him the username and password.

Stock export - optional

If you are using the connector to synchronise stock you will need to configure :

• an SFTP server on OneStock for stock export.

• a translator

• webhook topic

• a stock export full and diff key request

SFTP

You can set this up from the Configuration > Data Exchange page.

Exemple of configuration:

{
  "sftp": {
    "shopify_sftp": {
      "address": "sftp4-preprod.onestock-retail.com:22",
      "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBKEoi/03XRG7kcd3yVd+thSczTVw7n5dDtxCD30E3eFKC+4reSp1S1JnJr3GQeknGXtqym6L7d5g962pJWe5dBY=",
      "user": "shopify-sftp",
      "working_directory": "/qualif/shopify"
    }
  },
  "default_sftp_name": "shopify_sftp"
}

Translator

The translator for stock export to the shopify connector needs to be similar to this one : the connector will only read stock files in csv with semi colon separator and with item_id and quantity headers

Example:

{
    "name": "export_stock_unified",
    "headers": [
        "item_id",
        "quantity"
    ],
    "omit_headers": false,
    "separator": ";",
    "qualifier": "\"",
    "end_line": "\n",
    "transformators": {
        "item_id": "item_id",
        "quantity": {
            "type": "max_int",
            "fields": [
                {
                    "type": "to_int",
                    "fields": [
                        "raw:0"
                    ]
                },
                "quantity"
            ]
        }
    }
}

Webhook topics

A stock_export_completed webhook topic needs to be created.

To do so, you have to create a notification on the Configuration > Outbound Messages > Notifications page

"stock_export_completed": {
    "media": {
      "webhook_topic": [
        "stock_export_completed"
      ]
    },
    "time_type": "duration",
    "time_value": "0s"
  }

Then you have to create the webhook topic

POST /webhook_topics

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "webhook_topic": {
    "ordered": true,
    "topic": "stock_export_completed"
  }
}

Key requests

Define your usual unify stock export request for full and diff. The connector has a configuration page to select the stock request that will be used for both.

The connector will call the POST /stock_export api with the configured values for the request names and SFTP. Once the file is available, it will receive the stock_export_completed webhook and fetch the file on the sftp server to update stock on shopify.

Installation

The OneStock connector is available on the Shopify marketplace. To install the OneStock connector, you need a Shopify Plus shop.

https://apps.shopify.com/onestock

You’ll be redirected on your shop admin and asked to install the connector.

Configuration - Connector

The configuration of the connector is done directly on the shop admin page.

General API configuration

Go to your ocnfiguration page and fill the mandatory fields:

• site id : your OneStock site id

• host : should be either:

  • https://api.onestock-retail.com

  • https://api-qualif.onestock-retail.com

• user id and password : the api user that has been created for the project.

• Synchronise order : check if your project needs order synchronization

Order synchronization

If checked, the connector will listen to all orders created in shopify to create them in OneStock.

It will also subscribe to 3 webhooks:

• order_state_changed

• parcel_state_changed

• line_item_group_state_changed

Those 3 webhooks let the connector update the order on Shopify when a line item is removed or when a parcel is dispatched.

Extra configurations

Once the general configuration is set, the user gets access to more configurations

Sales channel (optional)

A dropdown will reveal available saleschannel configured in OneStock. This value will be used for order creation but also for the delivery promise calls.

SFTP Configuration (optional)

This is where you have to configure the sftp for stock export from OneStock to Shopify.
The values to enter will be specified by the owner of the SFTP that you are using.

Location & Stock request mapping (optional)

This is to configure the stock export from OneStock to Shopify for full stock and delta stock.

Values to input here will be given by your OneStock Project manager.

Timezone (optional)

This is to configure the timezone you are using for your scheduled stock imports

Rulesets Mapping (optional)

You’ll have to map each Shopify delivery rate to an existing ruleset chaining in OneStock if you are synchronizing your orders through the connector. This is usefull if you have multiple ruleset chainings configured in OneStock.

Delivery promises Mapping (optional)

If you have subscribed to OneStock delivery promise, you can display the delivery promise result on your checkout page under every Shopify delivery rate.

If click and collect is selected, we will display a store selection in your checkout with all stores having click and collect enabled with the delivery promise response.

Default location for Delivery Promise (demo, don’t use)

The connector is shipped with a theme block to display every delivery promise configured on the delivery promise mapping. This bloc is used to call the delivery promise with the country and zip inputted here when the theme block is activated on the product and basket page.

Synchronization

This page allows you to trigger a product synchronization or to trigger a stock import (full or diff).

Carrier services

This page allows you to create a new delivery option based on a delivery promise route from OneStock.

The standard delivery rate from Shopify doesn’t allow the connector to “hide” the delivery option based on the delivery promise response.

Thus, if a delivery option should be available to your customer only if our delivery promise says so (e.g. click and collect express), you have to create the rate from this page.

Create a rate

First, you have to make sure that the delivery promise route is configured and exists in OneStock.

Parameters to input:

• Default Service name : the name that your customers will see in the checkout page.

• Translations : if your shop supports multiple langages, you can translate the delivery option name that will be displayed on the checkout page here

• Code : required by Shopify, this will be the rate code that is saved in the Shopify Order

• Is C&C : if set to true, a list of stores that can fulfill the order will be displayed

• Cost : you can set a fixed cost here. If not filled, we will use the cost returned by the delivery promise

• Currency : set the currency of the cost

• Delivery Promise Route : select the delivery route that is configured in OneStock

• Ruleset (optional) : the ruleset chaining that will be posted to OneStock with the order.

Translation

The connector displays the delivery promise for two types of messages on the checkout page: click and collect and home delivery.

You can customize those messages from this configuration page.

There is an helper on the top right that explains the variables you can use but also some text transformers to display the dates in different formats

Documentation

This page explains the two proxy routes opened by the connector. This is used so that you system integrator can make a custom implementation of the delivery promise and do extra stock check before checkout.

Checkout extension

To display the delivery promise on your checkout page, you have to add our app block in your checkout page.

1. On the bottom left click on Add app block

2. Select the `delivery-promise` app

3. Don’t forget to save on the top right