将 MODX Revolution + miniShop2 网店接入 ILFF

下载模块 ilff-1.0.0-pl.transport.zip

«ILFF» 模块把您基于 MODX Revolution 和 miniShop2 的网店与 ILFF 服务连接起来：

• 下单流程中出现 ILFF 配送方式：快递上门、在地图上选择的自提点和俄罗斯邮政，带价格和时效；
• 使用 ILFF 配送的订单在进入您选定的状态时自动发送到 ILFF；
• 跟踪号和订单状态回传到网店；
• 商品的库存和重量从 ILFF 同步到网店；
• 在网店取消订单会取消 ILFF 中的发货申请。

数据交换始终由网店发起：模块使用 API 密钥主动访问 ILFF 服务，无需向我们开放网店。

您需要：

• MODX Revolution 2.8（暂不支持 MODX 3：miniShop2 4 只能在 MODX 2 上运行）；
• miniShop2 4 和 pdoTools（随 miniShop2 一起安装）；
• PHP 7.2 或更高版本，带 curl 扩展（已在 PHP 8.2 上测试）；
• 网店货币为俄罗斯卢布：ILFF 以卢布计算运费和订单金额；
• 使用 msOrder 片段构建的下单页面（miniShop2 的标准下单流程，详见第 4 步）；
• MODX 管理后台的管理员权限、服务器（或主机）cron 的访问权限以及 ILFF 客户后台的访问权限。

接入需要 20–30 分钟。

模块和 ILFF 客户后台均为俄语界面，下文按屏幕上的原文给出其名称，并在括号中附上译文。MODX 管理后台的菜单按英语给出。

第 1 步：在 ILFF 客户后台中接入

客户后台 → Интеграции（集成）标签页 → 展开 Интернет-магазин（网店）区块。

1. Платформа（平台）：选择 MODX (miniShop2)。
2. Адрес магазина（网店地址）：网站地址，例如 shop.ru。
3. 勾选项 Заказ с несвязанным товаром ждёт привязки（含未关联商品的订单等待关联）：启用后，如果订单中的商品尚未与您在 ILFF 中的商品关联，该订单在关联完成前不会被接收（见第 6 步）。建议保持勾选。
4. 点击 Подключить（接入）。后台会创建接入记录。此时后台不会访问网店：连接由模块在第 3 步检查。

Интеграции 标签页顶部显示 Ключ API（API 密钥）。如果没有，点击 Сгенерировать（生成）。第 3 步需要用到该密钥。不要转发给任何人：ILFF 服务凭它识别您的网店。自提点组件所需的 код клиента（客户代码）也在同一位置；请把网店域名加入 домены виджета（组件域名）列表。

第 2 步：安装模块

1. 从 ILFF 网站的模块页面下载安装包 ilff-1.0.0-pl.transport.zip，或向客户经理索取。不要解压安装包。
2. 在 MODX 管理后台打开 Extras → Installer，点击 Download Extras 按钮旁的箭头 → Upload a Package，选择文件并点击 Upload。
3. 在安装包列表的 ilff 一行点击 Install 并确认安装。

安装程序会自动：

• 创建订单队列表；
• 添加 ILFF 插件、ILFF 系统设置和菜单项 Extras → ILFF；
• 创建三种 miniShop2 配送方式：Курьер ILFF（ILFF 快递上门）、Пункт выдачи ILFF（ILFF 自提点）、Почта России (ILFF)（俄罗斯邮政），并为它们允许所有已启用的支付方式。

第 3 步：模块设置

Settings → System Settings，在命名空间筛选中选择 ilff。双击单元格即可修改值。

Подключение（连接）

1. Ключ API ILFF（ILFF API 密钥）：第 1 步中的密钥。
2. Адрес сервиса ILFF（ILFF 服务地址）：已填写，无需修改。
3. Код клиента для виджета（组件用客户代码）：客户后台中的代码。没有该代码时，无法在地图上选择自提点，«Пункт выдачи ILFF» 方式也不会计算。
4. Вариант настроек калькулятора（计算器设置方案）：ILFF 客户后台中的方案代码，例如 site2，适用于该网站有单独配送设置的情况。留空表示使用默认设置。免运费门槛（«Бесплатно для получателя от суммы товаров»）在 ILFF 客户后台中设置：商品金额达到门槛时，模块把运费显示为 «Бесплатно»（免费）。
5. Адрес подсказки городов（城市提示地址）：选填。留空表示使用 ILFF 服务地址旁的默认地址。

Заказы и статусы（订单和状态）。状态和支付方式按 miniShop2 设置（«Статусы» 和 «Способы оплаты» 标签页）中的编号（id）填写，多个用逗号分隔：

1. Статусы отправки заказа в ILFF（把订单发送到 ILFF 的状态）：默认是 2（«Оплачен»，已付款）。订单在转入该状态时发送。如果您人工审核订单，请填写审核后订单所转入的状态。
2. Статусы отмены（取消状态）：默认是 4（«Отменён»，已取消）。把已发送的订单转入此类状态会取消 ILFF 中的申请。
3. Способы оплаты при получении（货到付款的支付方式）：默认是 1。此类订单以货到付款方式发送到 ILFF，其他订单视为已预付。

ILFF 状态对应的订单状态。 留空表示不改变订单状态：

miniShop2 默认没有“已送达”状态：请在 «Статусы» 标签页添加该状态并填写其编号。状态变更时发给买家的邮件由 miniShop2 按状态本身的设置发送。

Остатки и вес（库存和重量）

1. Получать остатки из ILFF（从 ILFF 接收库存）：把可用库存写入商品的库存字段，即 ILFF 仓库库存减去预留量和尚未到达 ILFF 的订单。处于仓库收货区的商品在上架前不计入库存。
2. Получать вес товаров из ILFF（从 ILFF 接收商品重量）：把在 ILFF 仓库测得的重量（千克）写入商品的重量字段，仅限我们已填写该数据的商品。
3. Получать вес и габариты заказа（接收订单的重量和尺寸）：把已拣货订单的重量、尺寸和包裹数保存到订单属性中。

设置完成后打开 Extras → ILFF，点击 Проверить связь（检查连接）：出现 «Связь с ILFF есть»（已连接 ILFF）。然后点击 Передать товары в ILFF（把商品发送到 ILFF）：商品会发送到 ILFF 用于关联（第 6 步）。

第 4 步：配送方式和下单流程

配送方式。 在 miniShop2 设置的配送标签页：

• Курьер ILFF：由最便宜的物流公司送货上门，带价格和时效，例如 «Курьер ILFF — 603 ₽, СДЭК (от 2 до 3 дней)»。如果买家在组件的 «Курьер» 标签页选择了物流公司，则按该物流公司计算。
• Пункт выдачи ILFF：在地图上选择的自提点、自提柜和俄罗斯邮政网点。
• Почта России (ILFF)：俄罗斯邮政送到买家地址（按邮编寄到邮局的包裹或俄罗斯邮政快递上门），前提是 ILFF 服务为您的网店计算俄罗斯邮政运费。

可以修改配送方式的名称、描述、排序和图标；不要修改处理类字段（ilffDeliveryHandler）和属性字段（{"ilff":"door"}、{"ilff":"pickup"}、{"ilff":"post"}）：模块凭它们识别 ILFF 配送。不需要的方式请关闭。不要为 ILFF 方式填写价格、单位重量费用和“满额免运费”值：价格由 ILFF 计算。必填字段设置列出了计算该方式所必需的下单字段；可以添加字段，但不要删除城市。如果配送由 ILFF 完成，请关闭网店中固定价格的配送方式。

下单流程。 模块适用于标准下单页面：带 [[!msOrder]] 片段和 miniShop2 模板块中 #msOrder 表单的资源（城市、地区和邮编字段，带 delivery 字段的配送方式列表 #deliveries）。在这样的页面上，模块会自动加载自己的脚本和样式。网站模板中必须加载 jQuery（miniShop2 也使用它）。如果您的下单表单经过定制，请保留配送方式 <label> 内的 <input name="delivery" id="delivery_<编号>"> 字段以及同名的地址字段。

第 5 步：买家看到的内容

1. 买家填写城市（如有，还包括地区和邮编）。快递上门和自提点的价格按城市计算，街道不参与计算：它随订单一起发送到 ILFF。城市、地区或邮编变更后，ILFF 方式的价格会刷新。
2. Курьер ILFF：价格、物流公司和时效。
3. Пункт выдачи ILFF — выберите пункт на карте: от N ₽（请在地图上选择自提点，N ₽ 起）：选择自提点之前，显示该城市的最低价格。配送方式下方有醒目的蓝色按钮 Выбрать пункт на карте（在地图上选择自提点）。选择该方式时也会打开地图。
4. 在 ILFF 组件窗口中，买家在地图或列表中选择自提点、自提柜或邮政网点。选择后，自提点地址显示在配送方式下方，配送方式显示准确的价格和时效，订单总额重新计算。下方的按钮变为 Изменить пункт выдачи（更改自提点）。
5. 在组件的 «Курьер» 标签页，买家可以选择快递物流公司并填写地址：系统会选中该物流公司的 «Курьер ILFF» 方式，地址填入街道字段。
6. 如果买家更改城市，已选的自提点会被重置，配送方式重新提示在地图上选择自提点。
7. 未选择自提点时无法提交自提订单：会出现提示 «Выберите пункт выдачи»（请选择自提点）。如果该地址无法计算 ILFF 运费，配送方式显示 «не доставляем по этому адресу»（该地址不在配送范围内），使用该方式的订单无法提交。

如果买家所在城市没有自提点或邮政网点，组件会把地图定位到地址所在位置，并显示邻近城市中最近的网点及距离；价格按所选网点计算。

自提点、费率和网点代码保存在订单中。请下一个使用 ILFF 配送的测试订单，把它转入发送状态，并确认订单已进入 ILFF。

第 6 步：关联商品

在 ILFF 客户后台“Интернет-магазин”区块中，Товары магазина（网店商品）按钮显示模块发送的网店商品及其与您在 ILFF 中商品的关联。关联先按条码匹配，再按货号匹配：

• 条码：模板变量 ilff_barcode（或 barcode、ean），如果商品有该变量。miniShop2 没有条码字段：请创建 TV ilff_barcode（Text 类型），允许商品模板使用它并填写；
• 货号：miniShop2 商品的货号（article）字段。

miniShop2 的商品选项（颜色、尺码）不会作为单独的商品发送到 ILFF：如果不同尺码在仓库中是不同的货品，请在网店中把它们创建为带各自货号的单独商品。

如果有订单在等待关联，Интеграции 标签页顶部会出现带此类订单数量的提示条，“Интернет-магазин”区块中会显示订单和商品的表格。关联完成后，模块会自动重新发送订单。

网店中的订单

在 miniShop2 的订单窗口中，订单标签页的管理员备注字段会写入 «ILFF: создана заявка …»（已创建申请）、«ILFF: заказ ждёт привязки товаров …»（订单等待关联商品）、«ILFF: трек-номер …»（跟踪号）以及对取消操作的答复。ILFF 申请编号、交换状态、ILFF 状态、带链接的跟踪号、自提点和费率保存在订单属性中（ilff 键）。

取消订单

把订单转入取消状态（第 3 步）会取消 ILFF 中的申请，前提是申请尚未交给物流公司；已拣货的订单会重新入库存储。如果申请已交给支持取消的物流公司（Dalli、5Post），取消请求会转给该公司，订单退回仓库。对于其他物流公司，处理中的申请不会自动取消：管理员备注中会写入 «ILFF: Заявка уже в работе…»（申请已在处理中），请联系客户经理。

cron 任务

MODX 没有自带的计划任务程序：请在服务器 cron（或主机的计划任务）中添加任务，每 15–60 分钟运行一次，以网站文件所有者的用户身份运行。准确的命令显示在 Extras → ILFF 页面，例如：

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

该任务：

• 重新发送未能立即发出的订单（连接失败后或等待关联的订单）：间隔 1、5、15、60 和 180 分钟，但不会比任务本身的运行频率更高；
• 获取跟踪号和订单状态：跟踪号写入管理员备注和订单属性，状态按第 3 步的表格变更；
• 更新库存和重量；
• 每天一次发送商品列表并核对全部库存。

订单在状态变更时立即发送到 ILFF，即使没有该任务。最近几次运行的时间显示在 Extras → ILFF 页面；Выполнить обмен сейчас（立即执行交换）按钮也在这里。

更新模块

按安装时的方式上传新安装包（Extras → Installer → Upload a Package），并点击新版本的 Install。设置、配送方式、订单队列和订单数据都会保留。

删除模块

Extras → Installer → 在 ilff 一行点击 Uninstall。插件、设置和菜单项会被删除，ILFF 配送方式会被关闭（不会删除：订单引用了它们），订单中的申请编号、跟踪号和自提点会保留。服务器 cron 中的任务行请自行删除。

常见问题

模块把交换错误写入 MODX 错误日志（Reports → Error Log，带 [ILFF] 的行），其中不含 API 密钥和买家数据。其他问题请联系您的 ILFF 客户经理。