插件“ILFF delivery and fulfilment”把您的 CS-Cart 网店与 ILFF 服务连接起来：
- 下单流程中出现 ILFF 配送方式：快递上门、在地图上选择的自提点和俄罗斯邮政，带价格和时效；
- 使用 ILFF 配送方式的订单在进入您选定的状态时自动发送到 ILFF；
- ILFF 跟踪号成为订单的发货记录：买家会收到发货邮件，并在自己的账户中看到跟踪号；
- 订单状态按 ILFF 状态变更；
- 商品的库存、重量和尺寸从 ILFF 同步到网店；
- 在网店取消订单会取消 ILFF 中的发货申请。
数据交换始终由网店发起：插件使用 API 密钥主动访问 ILFF 服务，无需向我们开放网店。
您需要：
- CS-Cart 4.21（已在 CS-Cart 4.21.2 俄语版上测试）；
- PHP 8.1 或更高版本，带 curl 扩展；
- 网店主货币为俄罗斯卢布，货币列表中有 RUB：ILFF 以卢布计算运费和订单金额；
- ILFF 配送方式仅在俄罗斯境内有效；
- 网店管理员权限、服务器 cron 或主机计划任务的访问权限以及 ILFF 客户后台的访问权限。
接入需要 15–20 分钟。
插件带有英语版本，下文的名称按英语版给出。ILFF 客户后台为俄语界面，下文按屏幕上的原文给出其名称，并在括号中附上译文。
第 1 步：在 ILFF 客户后台中接入
客户后台 → Интеграции（集成）标签页 → 展开 Интернет-магазин（网店）区块。
- Платформа（平台）：选择 CS-Cart。
- Адрес магазина（网店地址）：网站地址，例如
shop.ru。 - 勾选项 Заказ с несвязанным товаром ждёт привязки（含未关联商品的订单等待关联）：启用后，如果订单中的商品尚未与您在 ILFF 中的商品关联，该订单在关联完成前不会被接收（见第 5 步）。建议保持勾选。
- 点击 Подключить（接入）。后台会创建接入记录。此时后台不会访问网店：连接由插件在第 3 步检查。
Интеграции 标签页顶部显示 Ключ API（API 密钥）。如果没有，点击 Сгенерировать（生成）。第 3 步需要用到该密钥。不要转发给任何人：ILFF 服务凭它识别您的网店。自提点组件所需的 код клиента（客户代码）也在同一位置；请把网店域名加入 домены виджета（组件域名）列表。
第 2 步：安装插件
- 从 ILFF 网站的模块页面下载压缩包
ilff-cscart.zip，或向客户经理索取。不要解压压缩包。 - 在 CS-Cart 管理后台打开 Add-ons → Manage add-ons，点击 +（上传并安装插件）并选择压缩包。
安装时插件会自动创建带实时费率的配送方式 ILFF courier、ILFF pickup point 和 Russian Post (ILFF)。它们的价格由 ILFF 计算。
第 3 步：插件设置
打开 Add-ons → Manage add-ons，找到插件 ILFF delivery and fulfilment 并打开其 Settings。
Connection with ILFF
- API key：第 1 步中的密钥。
- Service URL：已填写，无需修改。
- Client code (widget)：客户后台中的代码。没有该代码时不显示自提点地图。
- Calculator settings variant：ILFF 客户后台中的方案代码，例如
site2，适用于该网站有单独配送设置的情况。留空表示使用默认设置。免运费门槛在 ILFF 客户后台中设置。 - City suggestions URL：选填，通常留空。
Orders
- Send the order to ILFF in statuses：默认是“Processed”。订单在转入任一已勾选的状态时发送。处于“Open”状态的订单不会发送到 ILFF：审核后请把它转入“Processed”。
- Cancel the ILFF request in statuses：默认是“Canceled”。把已发送的订单转入此类状态会取消 ILFF 中的申请。
- Cash on delivery payment methods：勾选买家收货时付款所用的方式。此类订单以货到付款方式发送到 ILFF，其他订单视为已预付。
ILFF 状态对应的订单状态。 “- do not change -”表示保持订单状态不变：
| 设置 | ILFF 状态 | 默认值 |
|---|---|---|
| Order status for "Handed to the carrier" | Передан в КС（已交给物流公司） | Complete |
| Order status for "Delivered" | Доставлен клиенту, Выдан, Частичная выдача（已送达、已取件、部分取件） | Complete |
| Order status for "Cancelled" | Отменен, Аннулирован（已取消、已作废） | Canceled |
| Order status for "Returned" | Возврат принят, Полный отказ（退货已接收、全部拒收） | do not change |
CS-Cart 没有单独的“Shipped”状态，因此已交付配送的订单默认变为“Complete”。如果您创建了自己的状态，请在这里选择。
Stocks and weights
- Get stocks from ILFF：把可用库存写入商品数量，即 ILFF 仓库库存减去预留量和尚未到达 ILFF 的订单。处于仓库收货区的商品在上架前不计入库存。不跟踪库存的商品不会被修改。
- Get product weights and dimensions from ILFF：把在 ILFF 仓库测得的重量和尺寸写入商品和变体。
- Get weight and dimensions of the packed order：已拣货订单的重量、尺寸和包裹数显示在订单的 ILFF 区块中。
保存设置，然后在 Exchange state 区块中点击 Check connection：出现“Connection with ILFF is OK.”。如果没有连接，原因显示在同一位置（见“常见问题”）。
Exchange state 区块显示 ILFF 配送方式、订单队列、最近几次交换运行的时间、交换任务的 URL 和错误日志。点击 Send products to ILFF：商品会发送到 ILFF 用于关联（第 5 步）。
第 4 步：配送方式和买家看到的内容
Administration → Shipping & taxes → Shipping methods：可以重命名 ILFF 配送方式，修改其排序和描述；不要为它们设置价格，价格由 ILFF 计算。不需要的方式请关闭。如果配送由 ILFF 完成，请关闭您自己的固定价格配送方式。ILFF 配送方式也可以手动创建：选择实时费率计算，服务为“ILFF: courier”、“ILFF: pickup point”或“ILFF: Russian Post”。
买家在下单流程中看到：
- ILFF courier：价格和时效。价格按买家地址中的城市计算，街道随订单一起发送到 ILFF。
- ILFF pickup point：选择自提点之前，显示“Choose a pickup point on the map, from N ₽”和按钮 Choose a pickup point on the map。选择该方式时会自动打开地图。选择自提点后，方式下方显示自提点地址，方式显示准确的价格和时效，按钮变为 Choose another pickup point。
- Russian Post (ILFF)：俄罗斯邮政送到买家地址，前提是 ILFF 服务为您的网店计算俄罗斯邮政运费。
- 在组件的快递标签页，买家可以选择快递物流公司：系统会选中“ILFF courier”方式，并显示该物流公司的价格。
- 未选择自提点时无法提交使用“ILFF pickup point”方式的订单：会出现“Choose an ILFF pickup point on the map.”。
如果买家所在城市没有自提点，组件会显示邻近城市中最近的网点及距离；价格按所选网点计算。不向买家地址配送的 ILFF 方式不会出现在列表中。
请下一个使用 ILFF 配送方式的测试订单，把它转入发送状态，并确认订单已进入 ILFF。
第 5 步：关联商品
在 ILFF 客户后台“Интернет-магазин”区块中，Товары магазина（网店商品）按钮显示插件发送的网店商品及其与您在 ILFF 中商品的关联。关联按货号匹配，即 CS-Cart 的 product code（CS-Cart 没有条码字段）。
| 状态 | 处理方法 |
|---|---|
| Связан（已关联） | 无需操作，关联已保存 |
| Подобран（已匹配） | 检查并确认 |
| Несколько совпадений（多个匹配项） | 手动选择正确的商品 |
| Не найден（未找到） | 手动选择商品，或在网店中填写 product code |
带变体（Product variations 插件：尺码、颜色）的商品按变体发送：每个变体有自己的代码，库存和订单按变体处理。
如果有订单在等待关联，Интеграции 标签页顶部会出现带此类订单数量的提示条。关联完成后，插件会自动重新发送订单。
网店中的订单
CS-Cart 管理后台的订单页面右侧栏有 ILFF 区块：配送类型、ILFF 申请编号、交换状态（“sent”、“waiting for product binding”、“in queue”）、ILFF 状态、跟踪号；启用相应勾选项后，还显示重量、尺寸和包裹数；如有交换错误也会显示。
当 ILFF 中出现跟踪号时，插件会创建订单的发货记录：ILFF 物流公司、跟踪号以及备注中的跟踪链接。买家会收到发货邮件，并在自己的网店账户中看到跟踪号。
取消订单
把订单转入取消状态会取消 ILFF 中的申请，前提是申请尚未交给物流公司；已拣货的订单会重新入库存储。如果申请已交给支持取消的物流公司（Dalli、5Post），取消请求会转给该公司，订单退回仓库。对于其他物流公司，处理中的申请不会自动取消：订单的 ILFF 区块中会显示申请已在处理中的答复，请联系客户经理。
交换任务
交换任务需要每 15–60 分钟运行一次。插件设置的 Exchange state 区块显示带密钥令牌的交换任务 URL。请把它添加到服务器 cron 或主机的计划任务中，例如：
*/15 * * * * wget -q -O - "<交换任务 URL>" >/dev/null 2>&1
不要公开该 URL：没有正确的令牌任务不会运行。
该任务重新发送未能立即发出的订单（间隔 1、5、15、60 和 180 分钟），获取跟踪号和状态，更新库存和重量，并每天一次检查连接、发送商品列表并核对全部库存。订单在状态变更时立即发送到 ILFF，即使没有该任务。最近几次运行的时间显示在“Exchange state”区块中；Run exchange now 按钮也在这里。
更新和删除
更新：按安装时的方式上传新的插件压缩包（Add-ons → Manage add-ons → +）。设置和数据都会保留。
删除（Add-ons → Manage add-ons，ILFF 插件 → Uninstall）：ILFF 配送方式会被关闭（您的订单引用了它们），订单中的 ILFF 数据会保留。
常见问题
| 提示或现象 | 原因和处理方法 |
|---|---|
| “ILFF API key is not set.” | 请填写客户后台中的密钥并保存设置 |
| “No connection with ILFF: wrong API key” | 密钥输入有误或已更换。请从客户后台复制密钥并保存设置 |
| “No connection with ILFF: the store is not connected in the ILFF client account” | 未完成第 1 步：请选择“CS-Cart”平台并点击 «Подключить» |
| “No connection with ILFF: the ILFF service did not respond” | 网站服务器无法访问 ILFF：请检查到 8443 端口的 HTTPS 出站连接和 curl 扩展 |
| 下单流程中没有 ILFF 配送方式 | 地址不在俄罗斯、地址中没有城市、配送方式已关闭，或未为该方式选择 ILFF 服务 |
| 没有“ILFF pickup point”或不显示地图 | 未填写组件用客户代码（第 3 步） |
| 地图能打开，但自提点无法加载 | 网店域名未加入 ILFF 客户后台的组件域名列表 |
| 订单没有进入 ILFF | 检查订单状态和“Send the order to ILFF in statuses”设置、订单页面的 ILFF 区块（交换错误）以及后台的“等待关联”提示条 |
| 跟踪号和状态没有回传 | 未配置交换任务：请查看“Exchange state”区块中最近几次运行的时间 |
| 网店库存与后台库存不一致 | 网店收到的是可用库存：不含预留量、未发送的订单和收货区的商品 |
插件把交换错误写入网店文件夹中的日志 var/ilff/ilff.log，其中不含 API 密钥和买家数据；日志也可在“Exchange state”区块中查看。其他问题请联系您的 ILFF 客户经理。