将 Joomla + JoomShopping 网店接入 ILFF

下载模块 ilff-joomla.zip

扩展包 «ILFF: доставка и фулфилмент»（ILFF：配送与仓配一体化）把您基于 Joomla 和 JoomShopping 的网店与 ILFF 服务连接起来：

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

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

您需要：

• Joomla 5 和 JoomShopping 5（已在 Joomla 5.4.10 和 JoomShopping 5.10.0 上测试）；
• PHP 8.1 或更高版本，带 curl 扩展；
• 网店主货币为俄罗斯卢布，重量单位为 kg：ILFF 以卢布计算运费和订单金额；
• JoomShopping 中有国家“俄罗斯”：ILFF 配送方式仅在俄罗斯境内有效；
• JoomShopping 的标准分步下单流程（默认模板或基于其结构的模板）；
• 网站管理员权限、Joomla 计划任务、服务器 cron 或主机计划任务的访问权限以及 ILFF 客户后台的访问权限。

接入需要 15–20 分钟。

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

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

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

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

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

第 2 步：安装扩展包

1. 从 ILFF 网站的模块页面下载压缩包 ilff-joomla.zip，或向客户经理索取。不要解压压缩包。
2. 请确认已安装 JoomShopping 5：没有它扩展包无法安装，并提示 «сначала установите JoomShopping 5»（请先安装 JoomShopping 5）。
3. 在 Joomla 管理后台打开 System → Install → Extensions，在 Upload Package File 标签页选择压缩包。

扩展包会安装并立即启用两个插件：

• Система - ILFF（系统 - ILFF）：模块的全部功能及其设置；
• Задача - ILFF（任务 - ILFF）：Joomla 计划任务 «ILFF: обмен с сервисом»（ILFF：与服务交换数据）。

首次安装时，模块会自动为俄罗斯创建 JoomShopping 配送方式 Курьер ILFF（ILFF 快递上门）、Пункт выдачи ILFF（ILFF 自提点）和 Почта России (ILFF)（俄罗斯邮政）。它们的价格由 ILFF 计算。

第 3 步：模块设置

打开 System → Plugins，找到 Система - ILFF 插件。

«Связь с ILFF» 标签页（与 ILFF 的连接）

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

«Заказы» 标签页（订单）

1. Статусы отправки заказа в ILFF（把订单发送到 ILFF 的状态）：默认是 Confirmed 和 Paid。订单在转入其中任一状态时发送。停留在 Pending 状态的订单不会发送到 ILFF：审核后请把它转入 Confirmed。
2. Статусы отмены（取消状态）：默认是 Cancelled。把已发送的订单转入此类状态会取消 ILFF 中的申请。
3. Оплата при получении（货到付款）：买家收货时付款所用的支付方式（默认是 pm_bank）。此类订单以货到付款方式发送到 ILFF，其他订单视为已预付。请确认这里选中的正是您的货到付款支付方式。

ILFF 状态对应的订单状态。 «Не менять»（不改变）表示保持订单状态不变：

«Остатки и вес» 标签页（库存和重量）

1. Получать остатки из ILFF（从 ILFF 接收库存）：把可用库存写入商品（或变体）的数量，即 ILFF 仓库库存减去预留量和尚未到达 ILFF 的订单。处于仓库收货区的商品在上架前不计入库存。数量不限的商品不会被修改。
2. Получать вес товаров（接收商品重量）：把在 ILFF 仓库测得的重量（kg）写入商品和变体。JoomShopping 没有商品尺寸字段，因此不传递尺寸。
3. Получать вес и габариты заказа（接收订单的重量和尺寸）：已拣货订单的重量、尺寸和包裹数显示在订单的 ILFF 区块中。

点击 Save：顶部出现 «ILFF: связь есть.»（已连接）。如果没有连接，原因显示在同一位置（见“常见问题”）。

«Состояние обмена» 标签页（交换状态）显示 ILFF 配送方式，等待发送、等待关联商品、已发送和已取消的订单数量，最近几次交换运行的时间以及交换任务的地址。点击 Передать товары в ILFF（把商品发送到 ILFF）：商品会发送到 ILFF 用于关联（第 5 步）。这些按钮使用已保存的设置，因此请先保存修改。

第 4 步：配送方式和买家看到的内容

Components → JoomShopping → Options → Shipping methods：可以重命名 ILFF 配送方式，修改其排序和描述；不要为它们设置价格，价格由 ILFF 计算。不需要的方式请关闭。如果配送由 ILFF 完成，请关闭您自己的固定价格配送方式。ILFF 配送方式凭别名识别（sf_ilff_door、sf_ilff_pickup、sf_ilff_post）：不要修改别名。

买家在配送步骤（填写地址之后）看到：

1. Курьер ILFF：价格，方式下方是物流公司和时效。价格按买家地址中的城市计算，街道随订单一起发送到 ILFF。
2. Пункт выдачи ILFF：选择自提点之前，显示 «Выберите пункт на карте: от N ₽»（请在地图上选择自提点，N ₽ 起）和按钮 Выбрать пункт на карте。选择该方式时也会打开地图。选择自提点后该步骤页面会刷新：方式下方显示自提点地址，方式显示准确的价格和时效，按钮变为 Изменить пункт выдачи（更改自提点）。
3. Почта России (ILFF)：俄罗斯邮政送到买家地址，前提是 ILFF 服务为您的网店计算俄罗斯邮政运费。
4. 在组件的 «Курьер» 标签页，买家可以选择快递物流公司：系统会选中 «Курьер ILFF» 方式，并显示该物流公司的价格。
5. 未选择自提点时无法完成配送步骤：会出现提示 «Выберите пункт выдачи: нажмите «Выбрать пункт на карте» под способом доставки»（请选择自提点：点击配送方式下方的按钮）。

如果买家所在城市没有自提点，组件会显示邻近城市中最近的网点及距离；价格按所选网点计算。不向买家地址配送的 ILFF 方式不会出现在列表中。

请下一个使用 ILFF 配送方式的测试订单，把它转入发送状态，并确认订单已进入 ILFF。

第 5 步：关联商品

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

• 条码：商品或变体的 EAN 字段；
• 货号：商品代码（或变体代码）。

带变体（依赖属性：尺码、颜色）的商品按变体发送：每个变体有自己的代码和条码，库存和订单按变体处理。如果变体的代码或条码未填写，则取商品的值。

如果有订单在等待关联，Интеграции 标签页顶部会出现带此类订单数量的提示条。关联完成后，模块会自动重新发送订单。

网店中的订单

JoomShopping 管理后台的订单页面有 ILFF 区块：ILFF 申请编号、交换状态（«передан» 已发送、«ждёт привязки товаров» 等待关联商品、«ждёт отправки» 等待发送）、ILFF 状态、带跟踪链接的跟踪号、自提点和物流公司；启用相应勾选项后，还显示重量、尺寸和包裹数；如有交换错误也会显示。下方是带日期的交换记录：跟踪号、等待关联、对取消操作的答复。

当 ILFF 状态改变订单状态时，带跟踪链接的跟踪号会作为备注添加到状态变更中，买家会在状态变更邮件中收到它。自提点、物流公司和时效可在订单和发给买家的邮件中看到。

取消订单

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

交换任务

交换任务需要每 15–60 分钟运行一次。请选择以下方式之一：

1. Joomla 计划任务。 打开 System → Scheduled Tasks，点击 New 并选择任务 ILFF: обмен с сервисом，间隔例如 15 分钟。为了让任务按时运行，而不是仅在有访客访问网站时运行，请在服务器 cron 中添加 Joomla 计划任务的启动命令。命令显示在 «Состояние обмена» 标签页，例如 */15 * * * * php /var/www/shop/cli/joomla.php scheduler:run --all。
2. 用于主机计划任务的地址。 «Состояние обмена» 标签页显示带密钥令牌的交换任务地址。请把它添加到主机的计划任务中（每 15–60 分钟请求一次该地址）。不要公开该地址：没有令牌任务不会运行。

该任务重新发送未能立即发出的订单（间隔 1、5、15、60 和 180 分钟），获取跟踪号和状态，更新库存和重量，并每天一次发送商品列表并核对全部库存。订单在状态变更时立即发送到 ILFF，即使没有该任务。最近几次运行的时间显示在 «Состояние обмена» 标签页；Выполнить обмен сейчас（立即执行交换）按钮也在这里。

更新和删除

更新：按安装时的方式安装新的扩展包压缩包（System → Install → Extensions）。Joomla 会更新文件，设置和数据都会保留。

删除（System → Manage → Extensions，ILFF 扩展包 → Uninstall）：ILFF 配送方式会被关闭（您的订单引用了它们），订单中的 ILFF 数据会保留。

常见问题

模块把交换错误写入 Joomla 日志，即网站日志文件夹（administrator/logs）中的 ilff.php 文件，其中不含 API 密钥和买家数据。其他问题请联系您的 ILFF 客户经理。