将 PrestaShop 网店接入 ILFF

下载模块 ilff-prestashop.zip

模块 «ILFF: доставка и фулфилмент»（ILFF：配送与仓配一体化）把您的 PrestaShop 网店与 ILFF 服务连接起来：

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

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

您需要：

• PrestaShop 8 或 9（已在 8.2.9 上测试）；
• 带 curl 扩展的 PHP；
• 网店货币为俄罗斯卢布，重量单位为 kg，尺寸单位为 cm：ILFF 以卢布计算运费和订单金额；
• PrestaShop 的标准下单流程（classic 主题或基于其结构的主题）；
• 网店管理员权限、服务器 cron 或主机计划任务的访问权限以及 ILFF 客户后台的访问权限。

接入需要 15–20 分钟。

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

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

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

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

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

第 2 步：安装模块

1. 从 ILFF 网站的模块页面下载模块压缩包，或向客户经理索取。不要解压压缩包。
2. 在 PrestaShop 管理后台打开 Modules → Module Manager，点击 Upload a module 并选择压缩包。
3. 安装完成后点击 Configure。

安装时模块会自动：

• 创建订单队列表和已选自提点表；
• 为所有区域和客户组创建配送方式 Курьер ILFF（ILFF 快递上门）、Пункт выдачи ILFF（ILFF 自提点）、Почта России (ILFF)（俄罗斯邮政）；
• 添加 ILFF 设置页面（Modules → Module Manager → ILFF → Configure）。

第 3 步：模块设置

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

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

Заказы（订单）

1. Статусы отправки заказа в ILFF（把订单发送到 ILFF 的状态）：默认是“Payment accepted”和“Processing in progress”。订单在转入其中任一状态时发送。货到付款的订单初始状态为“Awaiting Cash On Delivery validation”：审核后请把它转入“Processing in progress”。
2. Статусы отмены（取消状态）：默认是“Canceled”。把已发送的订单转入此类状态会取消 ILFF 中的申请。
3. Оплата при получении（货到付款）：买家收货时付款所用的支付模块（默认是 ps_cashondelivery）。此类订单以货到付款方式发送到 ILFF，其他订单视为已预付。

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

状态变更时发给买家的邮件由 PrestaShop 按状态的设置发送。

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

1. Получать остатки из ILFF（从 ILFF 接收库存）：把可用库存写入商品（或组合）的数量，即 ILFF 仓库库存减去预留量和尚未到达 ILFF 的订单。处于仓库收货区的商品在上架前不计入库存。
2. Получать вес и габариты товаров（接收商品的重量和尺寸）：把在 ILFF 仓库测得的重量和尺寸（kg、cm）写入商品，仅限我们已填写这些数据的商品。组合不会被修改：在 PrestaShop 中，组合的重量是在商品重量基础上的增量。
3. Получать вес и габариты заказа（接收订单的重量和尺寸）：已拣货订单的重量、尺寸和包裹数显示在订单的 ILFF 区块中。

点击 Сохранить и проверить связь（保存并检查连接）：出现 «Связь с ILFF есть»（已连接 ILFF）。然后在 Состояние обмена（交换状态）区块中点击 Передать товары в ILFF（把商品发送到 ILFF）：商品会发送到 ILFF 用于关联（第 5 步）。

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

Shipping → Carriers：可以重命名 ILFF 配送方式，修改其排序、图标和时效说明；不要为它们设置价格，价格由 ILFF 计算。不需要的配送方式请关闭。如果配送由 ILFF 完成，请关闭网店中固定价格的配送方式。

买家在“Shipping method”步骤（填写地址之后）看到：

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

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

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

第 5 步：关联商品

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

• 条码：商品或组合的 EAN-13 字段（或 UPC、ISBN）；
• 货号：商品或组合的 Reference 字段。

带组合（尺码、颜色）的商品按组合发送：每个组合有自己的货号和条码，库存和订单按组合处理。

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

网店中的订单

订单页面右侧有 ILFF 区块：ILFF 申请编号、交换状态（«передан» 已发送、«ждёт привязки товаров» 等待关联商品、«ждёт отправки» 等待发送）、ILFF 状态、带跟踪链接的跟踪号、自提点和费率；启用相应勾选项后，还显示重量、尺寸和包裹数。跟踪号也会写入订单配送方式的跟踪号字段。订单的内部消息（仅员工可见）中会写入 «ILFF: создана заявка …»（已创建申请）、«ILFF: трек-номер …»（跟踪号）、«ILFF: пункт выдачи …»（自提点）以及对取消操作的答复。

取消订单

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

交换任务

请添加每 15–60 分钟运行一次的任务：在服务器 cron 中以命令形式添加，或在主机的计划任务中以地址形式添加。两种写法都显示在设置页面的 Состояние обмена 区块中，例如：

*/15 * * * * php /var/www/shop/modules/ilff/cron.php

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

更新和删除

更新：按安装时的方式上传新压缩包（Upload a module）。PrestaShop 会更新文件，设置和数据都会保留。

删除（Module Manager → ILFF → Uninstall）：ILFF 配送方式会被删除，设置和队列会被清除，订单中的 ILFF 数据会保留。

常见问题

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