将 WordPress + WooCommerce 网店接入 ILFF

下载模块 ilff-woocommerce.zip

插件«ILFF: доставка и фулфилмент»（ILFF：配送和履约）把您的 WooCommerce 网店与 ILFF 服务连接起来：

• 下单流程中出现 ILFF 配送方式：快递上门（每家物流公司单独显示）和自提点，带价格和时效；自提点由买家在地图上选择；
• 使用 ILFF 配送的订单在进入您选定的状态时自动发送到 ILFF；
• 跟踪号和订单状态回传到网店；
• 商品的库存、重量和尺寸从 ILFF 同步到网店；
• 在网店取消订单会取消 ILFF 中的发货申请。

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

您需要：

• WordPress 6.2 或更高版本以及 WooCommerce 8 或更高版本；
• PHP 7.4 或更高版本（已在 PHP 8.2 上测试）；
• 网店货币为俄罗斯卢布：ILFF 以卢布计算运费和订单金额；
• 经典下单流程（详见第 4 步）；
• 网店管理员权限和 ILFF 客户后台的访问权限。

接入需要 15–20 分钟。

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

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

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

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

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

第 2 步：安装插件

1. 从 ILFF 网站的模块页面下载压缩包 ilff-woocommerce.zip，或向客户经理索取。无需解压。
2. 在 WordPress 后台打开 Plugins → Add New → Upload Plugin，选择压缩包并点击 Install Now。
3. 点击 Activate。

启用时插件会自动：

• 创建订单队列表；
• 在 WP-Cron 中添加每小时运行一次的 ILFF 任务：补发订单、跟踪号、状态、库存；
• 在 WooCommerce → Settings 中添加 ILFF 标签页，并添加配送方式«Курьер ILFF»（ILFF 快递上门）和«Пункт выдачи ILFF»（ILFF 自提点）。

第 3 步：插件设置

WooCommerce → Settings → ILFF。

Связь с ILFF（与 ILFF 的连接）

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

Заказы（订单）

1. Статус, при котором заказ уходит в ILFF（订单发送到 ILFF 的状态）：默认是 Processing。订单在转入该状态时发送。如果您要审核订单或等待付款，请选择审核后订单所转入的状态。
2. Статусы отмены（取消状态）：默认是 Cancelled。已发送的订单转入此类状态会取消 ILFF 中的申请。
3. Оплата при получении（货到付款）：买家向快递员或在自提点付款的支付方式。默认是 Cash on delivery（cod）。此类订单带货到付款金额发送到 ILFF，其他订单视为已预付。

Статусы заказа по статусам ILFF（按 ILFF 状态设置订单状态）。«Не менять»（不修改）表示保持订单状态不变：

WooCommerce 把 Refunded 状态处理为订单全额退款，因此退货的默认值是«Не менять»。如果网店中没有“已交付配送”状态，可以用自定义订单状态插件添加，并在这里选择。

Остатки, вес и габариты（库存、重量和尺寸）

1. Получать остатки из ILFF（从 ILFF 获取库存）：把可用库存写入商品（或变体）的库存，即 ILFF 仓库库存减去预留量和尚未到达 ILFF 的订单。处于仓库收货区的商品在上架前不计入库存。此类商品的库存管理会自动启用。
2. Получать вес и габариты товаров（获取商品重量和尺寸）：把在 ILFF 仓库测量的重量和尺寸按网店的计量单位写入商品，仅限我们已填写这些数据的商品。
3. Получать вес и габариты заказа（获取订单重量和尺寸）：已拣货订单的重量、尺寸和件数显示在订单页面的 ILFF 区块中。

点击 Save changes。插件会立即检查连接：顶部显示«Связь с ILFF есть, клиент: …»（已连接 ILFF，客户：…）。然后在 Состояние обмена（交换状态）区块中点击 Передать список товаров сейчас（立即发送商品列表）：商品会发送到 ILFF 用于关联（第 6 步），启用库存同步时会立即核对库存。

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

配送方式。 WooCommerce → Settings → Shipping → 打开俄罗斯的配送区域（或创建区域为“Russia”的配送区域）→ Add shipping method：

• Курьер ILFF：送货上门。买家看到每家物流公司的单独选项：«Курьер до двери: СДЭК»、«Курьер до двери: Курьер ILFF»，按该物流公司最便宜的费率显示，并带时效。如果 ILFF 服务为您的网店计算俄罗斯邮政费率（«Посылка»、«Посылка онлайн»、«Курьер онлайн»），它们会以各自的名称显示为单独的选项。
• Пункт выдачи ILFF：自提点、自提柜和俄罗斯邮政网点。

配送方式的名称可在其设置中修改（该方式一行中的铅笔图标）。如果配送由 ILFF 完成，请停用该区域中固定价格的配送方式。

下单流程必须是经典版。 在地图上选择自提点的按钮适用于经典购物车和经典结账页（短代码 [woocommerce_cart] 和 [woocommerce_checkout]）。新建的 WooCommerce 网店默认用区块构建购物车页和结账页：在这种页面上能看到«Пункт выдачи ILFF»方式，但无法选择自提点，订单也无法提交。请把页面切换为经典版：

1. Pages → Checkout → Edit。
2. 选中 Checkout 区块，在其面板中点击 Switch to classic checkout（或用内容为 [woocommerce_checkout] 的 Shortcode 区块替换该区块）。
3. 更新页面。对购物车页面执行同样的操作（[woocommerce_cart]）。

WooCommerce 可能在插件页面提示 ILFF 插件与区块结账不兼容：指的正是这一点。

第 5 步：买家看到的内容

1. 买家填写国家俄罗斯、地区和城市。快递上门和自提点的价格按城市计算，街道不参与计算：它随订单一起发送到 ILFF。
2. Курьер до двери（快递上门）：各物流公司的选项，带价格和时效。
3. Пункт выдачи ILFF — выберите пункт на карте: от N ₽（请在地图上选择自提点，N ₽ 起）：选择自提点之前显示该城市的最低价格。该方式下方有一个醒目的蓝色按钮 Выбрать пункт на карте（在地图上选择自提点）。选择该方式也会自动打开地图。
4. 在 ILFF 组件窗口中，买家在地图或列表中选择自提点、自提柜或邮政网点。选择后该方式变为«Пункт выдачи ILFF СДЭК: адрес пункта»（或«Почта России: адрес отделения»），并显示准确的价格和时效。下方的按钮变为 Изменить пункт выдачи（更换自提点）。
5. 在组件的«Курьер»标签页中，买家可以选择快递物流公司并输入地址：结账页会选中该物流公司的«Курьер до двери»选项，地址会填入街道栏。
6. 买家更换城市后，已选的自提点会被清除，该方式会再次提示在地图上选择自提点。
7. 未选择自提点时无法提交自提点订单：会出现«Выберите пункт выдачи»（请选择自提点）提示。

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

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

第 6 步：关联商品

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

• 条码：商品 Inventory 标签页中的 GTIN, UPC, EAN or ISBN 字段（WooCommerce 9.2 及更高版本）。在更早的版本中，如果您的条码插件填写了自定义字段 _ean、_barcode 或 _gtin，插件会从中读取条码；
• 货号：SKU 字段。

可变商品（尺码、颜色）按变体发送：每个变体有自己的货号和条码，库存和订单按变体处理。请为每个变体填写条码和货号。

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

网店中的订单

订单页面右侧有 ILFF 区块：ILFF 申请编号、交换状态（«передан»已发送、«ждёт привязки товаров»等待关联商品、«ждёт отправки»等待发送）、ILFF 状态、带跟踪链接的跟踪号、自提点和费率；勾选«Получать вес и габариты заказа»后还显示重量、尺寸和件数。订单备注中会出现«ILFF: создана заявка …»（已创建申请）、«ILFF: трек-номер …»（跟踪号）以及对取消请求的答复。

取消订单

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

WP-Cron 任务

ILFF 任务每小时运行一次：

• 补发未能立即发送的订单（连接故障后或等待关联结束后）：间隔为 1、5、15、60 和 180 分钟，但不会比任务运行频率更高；
• 获取跟踪号和订单状态：跟踪号写入订单备注和 ILFF 区块，状态按第 3 步的表格变更；
• 更新库存、重量和尺寸；
• 每天发送一次商品列表并核对全部库存。

订单在状态变化时立即发送到 ILFF，不依赖该任务。

WP-Cron 在访客访问网站时运行。访问量较小或已关闭 WP-Cron（wp-config.php 中的 DISABLE_WP_CRON）的网站，请在服务器上配置系统 cron，每 5–15 分钟调用一次 https://your-store/wp-cron.php 或命令 wp cron event run --due-now（WP-CLI）。最近几次运行和下次运行的时间显示在 ILFF 标签页的 Состояние обмена 区块中。

更新插件

下载新的压缩包，按安装时的方式上传：Plugins → Add New → Upload Plugin。WordPress 会提示 Replace current with uploaded：请确认。设置、订单队列和订单数据会保留。

删除插件

停用插件会停止 ILFF 任务，设置保留。删除插件（Plugins → Delete）会清除其设置、订单队列和配送区域中的 ILFF 配送方式；订单中的申请编号、跟踪号和自提点保留。

常见问题

插件把交换错误写入 WooCommerce 日志（WooCommerce → Status → Logs，来源为 ilff），其中不含 API 密钥和买家数据。其他问题请联系您的 ILFF 客户经理。