Connecting a MODX Revolution + miniShop2 store to ILFF

Download the module ilff-1.0.0-pl.transport.zip

The «ILFF» module links your store on MODX Revolution with miniShop2 with the ILFF service:

• ILFF delivery methods appear in the checkout: courier to the door, a pickup point chosen on a map and Russian Post, with the price and delivery time;
• an order with ILFF delivery goes to ILFF on its own when it gets the status you chose;
• the tracking number and order status are returned to the store;
• stock and weight of products are passed from ILFF to the store;
• cancelling an order in the store cancels the request in ILFF.

The store always starts the exchange: the module itself calls the ILFF service with the API key, and you do not need to open the store to us.

You need:

• MODX Revolution 2.8 (MODX 3 is not supported yet: miniShop2 4 works only on MODX 2);
• miniShop2 4 and pdoTools (installed together with miniShop2);
• PHP 7.2 or newer with the curl extension (tested on PHP 8.2);
• the store currency is the Russian rouble: ILFF calculates delivery and order amounts in roubles;
• the checkout built with the msOrder snippet (the standard miniShop2 checkout, details in step 4);
• access to the MODX manager with administrator rights, to the cron of the server (or hosting) and to the ILFF client account.

The connection takes 20–30 minutes.

The module and the ILFF client account are in Russian, so their labels are given below as they appear on the screen, with a translation in brackets. MODX manager menus are named in English.

Step 1. Connection in the ILFF client account

Client account → the Интеграции (Integrations) tab → expand the Интернет-магазин (Online store) block.

1. Платформа (Platform): choose MODX (miniShop2).
2. Адрес магазина (Store address): the site address, for example shop.ru.
3. The Заказ с несвязанным товаром ждёт привязки (An order with an unlinked product waits for linking) checkbox: when it is on, an order with a product that is not yet linked to your product in ILFF is not accepted until you link it (step 6). We recommend leaving the checkbox on.
4. Press Подключить (Connect). The account creates the connection. It does not call the store at this point: the module checks the link at step 3.

The Ключ API (API key) is shown at the top of the Интеграции tab. If it is missing, press Сгенерировать (Generate). You will need the key at step 3. Do not send it to anyone: the ILFF service recognises your store by it. The код клиента (client code) for the pickup point widget is in the same place; add the store domain to the домены виджета (widget domains) list.

Step 2. Installing the module

1. Download the package ilff-1.0.0-pl.transport.zip from the module page on the ILFF site or get it from your manager. Do not unpack the package.
2. In the MODX manager open Extras → Installer, press the arrow next to the Download Extras button → Upload a Package, choose the file and press Upload.
3. In the package list press Install in the ilff row and confirm the installation.

The installer itself:

• creates the order queue table;
• adds the ILFF plugin, the ILFF system settings and the menu item Extras → ILFF;
• creates three miniShop2 delivery methods: Курьер ILFF (ILFF courier), Пункт выдачи ILFF (ILFF pickup point), Почта России (ILFF) (Russian Post), and allows all enabled payment methods for them.

Step 3. Module settings

Settings → System Settings, choose ilff in the namespace filter. A value is changed by double-clicking the cell.

Подключение (Connection)

1. Ключ API ILFF (ILFF API key): the key from step 1.
2. Адрес сервиса ILFF (ILFF service address): already filled in, no need to change it.
3. Код клиента для виджета (Client code for the widget): the code from the client account. Without the code the choice of a pickup point on the map does not work and the «Пункт выдачи ILFF» method is not calculated.
4. Вариант настроек калькулятора (Calculator settings profile): the profile code from the ILFF client account, for example site2, if this site has its own delivery settings. Empty means the default settings. Free delivery thresholds («Бесплатно для получателя от суммы товаров») are set in the ILFF client account: when the goods total reaches the threshold, the module shows delivery as «Бесплатно» (Free).
5. Адрес подсказки городов (City suggestion address): optional. Empty means it is taken from the ILFF service next to the service address.

Заказы и статусы (Orders and statuses). Statuses and payment methods are given by their numbers (ids) from the miniShop2 settings (the «Статусы» and «Способы оплаты» tabs), several separated by commas:

1. Статусы отправки заказа в ILFF (Statuses that send the order to ILFF): 2 («Оплачен», Paid) by default. The order goes when it moves to this status. If you check the order manually, enter the status you move the order to after the check.
2. Статусы отмены (Cancellation statuses): 4 («Отменён», Cancelled) by default. Moving a sent order to such a status cancels the request in ILFF.
3. Способы оплаты при получении (Cash on delivery payment methods): 1 by default. Such orders go to ILFF with cash on delivery, the others are treated as prepaid.

Order statuses by ILFF statuses. Empty means the order status is not changed:

miniShop2 has no "delivered" status by default: add it on the «Статусы» tab and enter its number. Emails to the shopper on a status change are sent by miniShop2 according to the settings of the status itself.

Остатки и вес (Stock and weight)

1. Получать остатки из ILFF (Receive stock from ILFF): free stock is written to the stock field of the product, that is the stock at the ILFF warehouse minus the reserve and the orders that have not reached ILFF yet. Goods in the receiving area of the warehouse are not part of the stock until they are put away.
2. Получать вес товаров из ILFF (Receive product weight from ILFF): the weight measured at the ILFF warehouse is written to the weight field of the product (in kilograms), only where we have it filled in.
3. Получать вес и габариты заказа (Receive order weight and dimensions): the weight, dimensions and number of packages of the picked order are saved in the order properties.

After the setup open Extras → ILFF and press Проверить связь (Check the connection): «Связь с ILFF есть» (connected to ILFF) appears. Then press Передать товары в ILFF (Send products to ILFF): the products go to ILFF for linking (step 6).

Step 4. Delivery methods and the checkout

Delivery methods. In the miniShop2 settings, the delivery tab:

• Курьер ILFF: door delivery by the cheapest carrier with the price and delivery time, for example «Курьер ILFF — 603 ₽, СДЭК (от 2 до 3 дней)». If the shopper chose a carrier on the «Курьер» tab of the widget, that carrier is calculated.
• Пункт выдачи ILFF: pickup points, parcel lockers and Russian Post offices chosen on a map.
• Почта России (ILFF): Russian Post to the shopper's address (a parcel to the post office by postcode or a Russian Post courier), if the ILFF service calculates Russian Post for your store.

You can change the name, description, order and logo of a method; do not change the handler class field (ilffDeliveryHandler) and the properties field ({"ilff":"door"}, {"ilff":"pickup"}, {"ilff":"post"}): the module uses them to recognise ILFF delivery. Switch off a method you do not need. Do not fill in the price, the cost per unit of weight and the "free from" value for ILFF methods: ILFF calculates the price. The required fields setting lists the checkout fields without which the method cannot be calculated; you can add fields, but do not remove the city. Switch off the store delivery methods with a fixed price if ILFF does the delivery.

Checkout. The module works with the standard checkout page: a resource with the [[!msOrder]] snippet and the #msOrder form from the miniShop2 chunk (the city, region and postcode fields, the delivery method list #deliveries with delivery fields). On such a page the module connects its script and styles itself. jQuery must be connected in the site template (miniShop2 uses it too). If your checkout form is customised, keep the <input name="delivery" id="delivery_<number>"> field inside <label> for delivery methods and the address fields with the same names.

Step 5. What the shopper sees

1. The shopper fills in the city (and, if present, the region and postcode). The price of the courier and of pickup points is calculated by city, the street is not used in the calculation: it goes to ILFF together with the order. The prices of ILFF methods are refreshed after the city, region or postcode changes.
2. Курьер ILFF: the price, the carrier and the delivery time.
3. Пункт выдачи ILFF — выберите пункт на карте: от N ₽ (choose a point on the map, from N ₽): before a point is chosen, the lower bound of the price for the city is shown. Under the method there is a visible blue button Выбрать пункт на карте (choose a point on the map). Choosing this method also opens the map.
4. In the ILFF widget window the shopper chooses a pickup point, a parcel locker or a post office on the map or in the list. After the choice the address of the point appears under the method, the method shows the exact price and delivery time, and the order total is recalculated. The button under it becomes Изменить пункт выдачи (change the pickup point).
5. On the «Курьер» tab of the widget the shopper can choose a courier carrier and enter the address: the «Курьер ILFF» method of that carrier is selected, and the address is put into the street field.
6. If the shopper changes the city, the chosen point is reset, and the method again offers to choose a point on the map.
7. An order with a pickup point cannot be placed without a chosen point: the message «Выберите пункт выдачи» (choose a pickup point) appears. If ILFF delivery is not calculated for the address, the method says «не доставляем по этому адресу» (we do not deliver to this address), and an order with it is not placed.

If the shopper's city has no pickup points or post offices, the widget opens the map at the address point and shows the nearest points of neighbouring cities with the distance; the price is calculated to the chosen point.

The pickup point, the rate and the point code are saved in the order. Place a test order with ILFF delivery, move it to the sending status and make sure the order has arrived in ILFF.

Step 6. Linking products

In the ILFF client account the Товары магазина (Store products) button in the "Интернет-магазин" block shows the store products sent by the module and their link to your products in ILFF. The link is matched first by barcode, then by SKU:

• barcode: the template variable ilff_barcode (or barcode, ean), if products have it. miniShop2 has no barcode field: create the TV ilff_barcode (the Text type), give it access to the product template and fill it in;
• SKU: the article field of the miniShop2 product.

miniShop2 product options (colour, size) are not passed to ILFF as separate products: if sizes are different goods at the warehouse, create them as separate store products with their own SKUs.

If an order is waiting for linking, a banner with the number of such orders appears at the top of the Интеграции tab, and the "Интернет-магазин" block shows a table with the orders and products. After linking, the module resends the order itself.

The order in the store

In the order window of miniShop2, on the order tab, the manager comment field gets the entries «ILFF: создана заявка …» (request created), «ILFF: заказ ждёт привязки товаров …» (the order waits for product linking), «ILFF: трек-номер …» (tracking number) and the reply to a cancellation. The ILFF request number, the exchange state, the ILFF status, the tracking number with a link, the pickup point and the rate are stored in the order properties (the ilff key).

Order cancellation

Moving an order to a cancellation status (step 3) cancels the request in ILFF until it has been handed over to the carrier; a picked order goes back to storage. If the request is already with a carrier that accepts cancellation (Dalli, 5Post), the cancellation is passed to it and the order returns to the warehouse. With other carriers a request in work is not cancelled on its own: the manager comment gets the entry «ILFF: Заявка уже в работе…» (the request is already in work), contact your manager.

The cron task

MODX has no scheduler of its own: add a task to the server cron (or the hosting scheduler) every 15–60 minutes, as the user who owns the site files. The exact command is on the Extras → ILFF page, for example:

*/15 * * * * php /var/www/shop/core/components/ilff/cron/cron.php

The task:

• resends orders that did not go at once (after a connection failure or from waiting for linking): after 1, 5, 15, 60 and 180 minutes, but not more often than the task runs;
• fetches tracking numbers and order statuses: the tracking number is written to the manager comment and the order properties, and the status changes by the table from step 3;
• updates stock and weight;
• once a day sends the product list and reconciles all stock.

Orders go to ILFF at once when the status changes, even without the task. The time of the last runs is shown on the Extras → ILFF page; the Выполнить обмен сейчас (Run the exchange now) button is there too.

Updating the module

Upload the new package the same way as on installation (Extras → Installer → Upload a Package) and press Install for the new version. The settings, delivery methods, order queue and order data are kept.

Removing the module

Extras → Installer → Uninstall in the ilff row. The plugin, the settings and the menu item are removed, the ILFF delivery methods are switched off (not deleted: orders refer to them), and request numbers, tracking numbers and pickup points in the orders stay. Remove the task line from the server cron yourself.

If something does not work

The module writes exchange errors to the MODX error log (Reports → Error Log, lines with [ILFF]), without the API key and shopper data. For other questions contact your ILFF manager.