将 OpenCart 网店接入 ILFF

下载模块 ilff.ocmod.zip

ILFF 扩展把您的 OpenCart 网店与 ILFF 服务连接起来：

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

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

您需要 OpenCart 4.0.2 或更高版本、带 curl 扩展的 PHP 8、网店管理员权限、用于配置 cron 的服务器访问权限以及 ILFF 客户后台的访问权限。接入需要 15–20 分钟。

ILFF 客户后台为俄语界面，下文按屏幕上的原文给出其名称，并在括号中附上译文。扩展带有英语和俄语语言文件，下文的设置名称按英语版给出。

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

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

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

Интеграции 标签页顶部显示 Ключ API（API 密钥）。如果没有，点击 Сгенерировать（生成）。第 3 步需要用到该密钥。不要转发给任何人：ILFF 服务凭它识别您的网店。

第 2 步：安装扩展

1. 从 ILFF 网站的模块页面下载压缩包 ilff.ocmod.zip，或向客户经理索取。不要修改压缩包名称：OpenCart 根据名称确定扩展代码。
2. 在后台打开 Extensions → Installer，上传压缩包，然后在 ILFF 一行点击 Install。
3. 打开 Extensions → Extensions，选择类型 Shipping，找到 ILFF: delivery and order exchange，点击 Install（绿色按钮），然后点击 Edit（铅笔图标）。

安装时扩展会自动：

• 创建订单队列表；
• 接入事件处理程序：记录订单费率、按状态发送和取消订单、下单页面的自提点选择窗口；
• 在 OpenCart 内置 cron 中创建 ILFF 任务（订单、跟踪号、状态、库存）（Extensions → Cron Jobs），每小时一次。

第 3 步：扩展设置

1. ILFF service URL：已填写，无需修改。
2. ILFF client API key：第 1 步中的密钥。保存后该栏保持为空，已保存的密钥不会显示。如果只修改设置，请保持为空。
3. Order status that sends the order to ILFF：例如 Processing。订单在转入该状态时发送。如果您要审核订单或等待付款，请选择审核后订单所转入的状态。
4. Cancel statuses：勾选表示订单已取消的状态，通常是 Canceled。转入此类状态会取消 ILFF 中的申请。
5. ILFF 状态对应的 Store statuses。“Do not change”表示保持订单状态不变：

首次安装时扩展会自动设置状态：订单在 Processing 状态发送到 ILFF，按 ILFF 状态分别设为 Shipped（已交付配送）、Complete（已送达）、Canceled（已取消）和 Refunded（退货）。这些都可以修改。

1. Cash on delivery payment codes：用逗号分隔。默认是 cod（标准的 Cash On Delivery 方式）。只有这些方式的申请中带货到付款金额，其他订单视为已预付。
2. Receive stock from ILFF：把可用库存写入商品数量，即 ILFF 仓库库存减去预留量和尚未到达 ILFF 的订单。处于仓库收货区的商品在上架前不计入库存。
3. Receive product weight and dimensions：把 ILFF 中的商品重量（千克）和尺寸（厘米）写入商品，仅限我们已填写这些数据的商品。
4. Simplified Russian address（默认启用）：下单时隐藏国家（始终为俄罗斯）、地区、“Company”和“Address 2”。“City”栏位于街道之前并提供城市提示，地区和邮编按所选城市自动填写。购物车的运费估算中只保留邮编。
5. Delivery on the product page（默认关闭）：在“Add to Cart”按钮下方显示买家所在城市的快递上门和自提点“起”价。
6. Pickup point window：“ILFF widget”（默认：地图、物流公司和价格）或“Simple window”。使用组件时，请填写客户后台中的 ILFF client code for the widget，并在后台把网店域名加入组件域名列表。未填写代码时打开简易窗口。Delivery calculator settings variant 是 ILFF 客户后台中的方案代码，例如 site2，适用于该网站有单独配送设置的情况。留空则使用默认设置。免运费门槛在 ILFF 客户后台中设置，商品金额达到门槛时，模块把运费显示为免费。
7. City suggestions URL：可选。留空时使用 ILFF 服务地址旁的提示服务。
8. Geo Zone：如果不是所有地区都需要 ILFF 配送，请选择地理区域。Status：启用。Sort Order：该方式在其他方式中的排序位置。
9. 勾选 Send the product list now，点击 Save and check connection。顶部会显示与 ILFF 的连接正常及客户名称、已发送的商品数量，以及在启用库存同步时已更新的库存数量。

第 4 步：下单流程

1. 计算需要配送地址：城市以及街道和门牌号。启用俄罗斯简化地址时，国家和地区会自动填写。在购物车的运费估算中，城市按邮编确定；如果无法确定，则显示“下单时计算”而不是价格。
2. ILFF 送货上门显示最便宜费率的价格和时效。
3. ILFF 自提点：在配送方式选择按钮下方出现选择 ILFF 自提点的按钮。点击后打开该城市自提点的列表和地图。选择自提点后，配送方式会刷新，并显示“ILFF 自提点：地址”以及价格和时效。
4. 如果配送由 ILFF 完成，请停用网店中固定价格的配送方式。
5. 用 ILFF 配送下一个测试订单，把它转入发送状态，确认订单已进入 ILFF。

第 5 步：关联商品

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

尺码和颜色有两种管理方式：

• OpenCart 4 变体（推荐）。 每个尺码或颜色是一个独立的商品变体，有自己的 EAN 和 SKU。系统按条码自动匹配，库存和订单按变体处理。
• 商品选项。 一个商品带一组选项值（例如“尺码：S、M、L”）。选项值没有自己的条码，因此在«Товары магазина»中每个选项值单独显示为一行“商品 / 选项：值”，需要手动与您的商品关联一次。之后 ILFF 库存会写入该选项值的数量，带该选项值的订单进入 ILFF 时对应正确的商品。未关联的选项值不会用主商品代替：此类订单会等待关联。

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

如果买家所在城市没有自提点或邮政网点，自提点选择窗口（ILFF 组件）会在地址位置打开地图，显示邻近城市最近的自提点及其距离；价格按所选自提点计算。如果地址目录中没有该街道（村镇、新街道），快递价格按城市计算。

取消订单

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

第 6 步：Cron

ILFF 任务由 OpenCart 内置 cron 每小时运行一次：

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

OpenCart 内置 cron 由服务器的系统 cron 启动。请在服务器上添加一个任务，每 5–15 分钟调用一次 OpenCart cron（命令显示在 Extensions → Cron Jobs 页面）。没有它，跟踪号、状态和库存不会更新。订单在状态变化时立即发送到 ILFF，不依赖 cron。

在 OpenCart 4.1.0.4 中，从命令行运行 php cron.php 可能出现核心错误（“Class Twig\Loader\FilesystemLoader not found”）。此时请通过网店地址调用 cron，例如 curl -s https://your-store/index.php?route=cron/cron。

更新扩展

OpenCart 4 的安装程序不能在已安装的扩展上覆盖安装压缩包（“Extension already installed!”或“Path ilff/ already exists!”）。因此请按以下方式更新：

1. 从本页面下载新的压缩包 ilff.ocmod.zip，在电脑上解压。
2. 通过 FTP 或主机面板把压缩包内容复制到网店的 extension/ilff/ 目录，覆盖旧文件。扩展设置会保留。
3. 如果新版本增加了事件（例如用于商品页或购物车），请打开扩展设置并点击 Save and check connection：缺少的事件会自动添加。

另一种方式是在 Extensions → Shipping 和 Installer 中卸载扩展，再重新安装新的压缩包。此时需要重新填写设置。

常见问题

其他问题请联系您的 ILFF 客户经理。