Расширение “Ferma OFD.ru”
для CMS “WordPress”

Инструкция описывает работу плагина Ferma OFD для WordPress / WooCommerce: установку, первичную настройку, работу с товарами, заказами, произвольными чеками, реестром, журналом, состоянием и разделом помощи.

Важно: Перед запуском на рабочем магазине согласуйте фискальные значения, НДС, признаки предмета и способа расчёта, агентские реквизиты, маркировку и сценарии возвратов с бухгалтером или ответственным за фискализацию.

Плагин Ferma OFD связывает интернет-магазин на WordPress / WooCommerce с сервисом Ferma от OFD.ru и помогает формировать:

• чеки по заказам WooCommerce: предоплата 100%, полный расчёт, возвраты и коррекции;
• первичный полный расчёт без предоплаты для сценариев передачи товара, услуги в момент оплаты;
• произвольные чеки без заказа, включая ручные приходы, возвраты и коррекции;
• полные и частичные возвраты по фискальному остатку¹⁾ заказа;
• агентские реквизиты на уровне товарных позиций и ручных чеков;
• коды маркировки, типы КМ, ввод КМ по позициям заказа и возврат маркированных товаров;
• актуальные и устаревшие ставки НДС (включая устаревшие 20% и 20/120 для отдельных сценариев возвратов и коррекций);
• реестр чеков, правую панель деталей, журнал событий, состояние, диагностику callback и резервный polling.

Минимальная системные требования:

• WordPress 6.0;
• PHP 7.4;
• Плагин WooCommerce.

Плагин Ferma OFD поддерживает HPOS.

• ZIP-архив плагина Ferma OFD.
• Доступ администратора WordPress.
• Установленный и настроенный WooCommerce. Плагин зависит от WooCommerce, даже если часть ручных чеков используется без привязки к заказу.
• Данные Ferma: URL API, логин, пароль, ИНН.
• Согласованные фискальные значения: СНО, НДС, предмет расчёта, единица измерения, способ расчёта.

Если используются агентские товары, дополнительно подготовьте: тип агента; ИНН поставщика; наименование поставщика; номер телефона; дополнительные реквизиты, необходимые выбранному типу агента.

Если используются коды маркировки: признак маркированного товара, тип КМ, режим проверки КМ и тестовые/рабочие коды.

Если используются автоматические чеки: статусы WooCommerce, на которых создаются предоплата 100%, полный расчёт и полный возврат фискального остатка.

Важно: Перед установкой на рабочий сайт сделайте резервную копию файлов и базы данных.

1. Откройте админ-панель WordPress под пользователем с правами администратора.
2. Перейдите в раздел «Плагины» → «Добавить плагин».
3. Нажмите «Загрузить плагин».
   
4. Кликните «Выберите файл».
5. Выберите ZIP-архив плагина Ferma OFD и нажмите «Открыть».
   
6. Нажмите «Установить».
   
7. После установки нажмите «Активировать».
   
8. Проверьте, что в левом меню появился раздел «Ferma OFD».
   

В левом меню WordPress появился раздел «Ferma OFD». В нём открываются страницы «Реестр чеков», «Чеки по заказам WooCommerce», «Произвольные чеки без заказа», «Журнал», «Состояние», «Помощь», «Настройки».

На странице «Состояние» отображаются версия плагина, режим API, callback, polling, WooCommerce, HPOS и диагностическая информация.

Если WooCommerce не активен, плагин не сможет работать в режиме чеков по заказам.

Откройте раздел «Ferma OFD» → «Настройки». Настройки сгруппированы в раскрывающиеся разделы; рядом с каждым отображается состояние: настроено, требует внимания, диагностика или обязательный раздел. Разделы со статусом «обязательный» нужно заполнить до перехода на рабочий режим.

Таблица 1. Разделы для предварительной настройки

Сводный перечень параметров по разделам настроек.

Таблица 2. Перечень параметров по разделам настроек

В разделе «Ferma OFD» выберите «Настройки», раскройте вкладку «Подключение к Ferma» и заполните:

1. Выберите режим API: тестовый или рабочий.
2. Если нужен рабочий API, включите защитную настройку «Разрешить использование рабочего API». Без неё рабочий режим не сохранится.
3. Заполните тестовый и/или рабочий URL API.
4. Заполните логин, пароль и ИНН. (Логин и пароль можно получить в личном кабинете «Ferma» на вкладке «Сервис Ferma» в виджете «Ваши магазины (реквизиты доступа)»)
   
5. Выберите систему налогообложения.
6. Укажите НДС по умолчанию, признак предмета расчёта по умолчанию и единицу измерения по умолчанию.
7. При необходимости заполните email получателя чека по умолчанию и включите его использование как резервного получателя.
8. Заполните email для уведомлений об ошибках и, при необходимости, имя и email отправителя уведомлений.
9. Сохраните настройки.

Назначение трёх адресов электронной почты в этом разделе:

• Email получателя чека по умолчанию — адрес, на который отправляется электронный чек покупателю, если в самом заказе адрес покупателя не указан. Флажок «использовать как резервного получателя» включает подстановку этого адреса в таких случаях.
• Email для уведомлений об ошибках — адрес магазина или ответственного сотрудника; на него приходят сообщения о сбоях в работе плагина.
• Имя и email отправителя уведомлений — от чьего имени отправляются эти служебные письма²⁾.

Важно: Проверка соединения использует уже сохранённые данные. Если вы изменили логин, пароль или URL, сначала нажмите «Сохранить настройки», затем запускайте проверку.

НДС: Базовая ставка НДС с 1 января 2026 года — 22% (расчётная 22/122); для обычных новых чеков применяются именно они. Ставки 20% и 20/120 применяются только к операциям, налоговая база которых возникла до 2026 года (возвраты и коррекции по отгрузкам 2025 года). Плагин предупреждает о выборе устаревшей ставки, но не блокирует его.

В разделе «Ferma OFD» выберите «Настройки», раскройте вкладку «Подключение к Ferma» и заполните:

1. Включите или отключите передачу доставки отдельной позицией.
2. Задайте НДС доставки, предмет расчёта доставки и единицу измерения доставки.
3. Включите или отключите передачу положительных сборов WooCommerce отдельными позициями.
4. Задайте НДС сборов, предмет расчёта сборов и единицу измерения сборов.

Примечания:

• «Сбор» — это дополнительная плата по заказу, не являющаяся товаром (например, наценка за способ оплаты, упаковку или страховку). «Положительные» — те, что увеличивают сумму заказа; отрицательные сборы (скидки) отдельной позицией не передаются.
• Если отключить передачу доставки, сумма чека может отличаться от суммы заказа. Проверяйте состав чека перед отправкой.

В разделе «Ferma OFD» выберите «Настройки», раскройте вкладку «Агентские реквизиты» и заполните:

1. Включите «агентские рекзвитиы для новых операций», если магазин должен формировать агентские позиции.
2. Выберите тип агента по умолчанию.
3. Заполните поставщика по умолчанию: ИНН, наименование, телефон.
4. Если выбран банковский платёжный агент или банковский платёжный субагент, заполните блок оператора перевода.
5. Если выбран платёжный агент или платёжный субагент, заполните телефоны платёжного агента и оператора приёма платежей.
6. Сохраните настройки.

Примечание: Если поддержка агентских чеков выключена, агентские поля скрываются в товарах, произвольных чеках и новых ручных формах. Уже начатые агентские цепочки по заказам могут использовать ранее сохранённые реквизиты. Отключение блокируется, если есть незавершённые агентские предоплаты 100%.

Раздел используется, если магазин продаёт маркированные товары. Коды маркировки не передаются в чек предоплаты 100%, но требуются для полного расчёта, возврата прихода и коррекций по маркированным позициям. В разделе «Ferma OFD» выберите «Настройки», раскройте вкладку «Коды маркировки» и заполните:

1. Выберите тип кода маркировки по умолчанию. Для товара можно задать индивидуальный тип КМ.
2. Выберите режим проверки КМ. Строгий режим снижает риск некорректной фискализации, но может чаще блокировать чек при проблемах с кодом.
3. Включите автоматизацию маркированных заказов, если полный расчёт должен создаваться автоматически после заполнения всех необходимых КМ.
4. Быстрый закрывающий чек доступен, когда все обязательные КМ заполнены.

Таблица 2. Формат кода маркировки

В разделе «Ferma OFD» выберите «Настройки», раскройте вкладку «Кассир» и заполните:

1. Включите передачу сведений о кассире, если это требуется.
2. Заполните ФИО кассира. Это поле обязательно, если включена передача кассира.
3. При необходимости заполните ИНН кассира. Это необязательное поле.

Раздел необязательный. Его можно не настраивать, если все чеки будут формироваться вручную. Чтобы настроить, перейдите в раздел «Ferma OFD», выберите «Настройки», раскройте вкладку «Коды маркировки» и заполните:

1. Для первого чека предоплаты 100% включите «Формировать автоматически» и выберите статус заказа.
2. Для закрывающего чека полного расчёта включите «Формировать автоматически» и выберите статус заказа.
3. Для возвратного чека включите «Формировать автоматически» и выберите статус заказа.
4. Если товары, услуги или доступ передаются покупателю в момент оплаты, можно включить «Разрешить автоматический полный расчёт без предоплаты». Используйте эту настройку только для таких сценариев.
5. Сохраните настройки.

Пример: Сопоставление статусов можно задать так: предоплата 100% — на статусе «В обработке», полный расчёт — на статусе «Выполнен», возврат — на статусе «Возвращён». Допустимы любые статусы WooCommerce, в том числе пользовательские.

Примечания:

• Закрывающий чек полного расчёта формируется после успешного подтверждения предоплаты 100%. Если заказ попадёт в статус закрывающего чека раньше, чем подтвердится предоплата, плагин дождётся подтверждения и только потом сформирует полный расчёт. Если разрешён полный расчёт без предоплаты, плагин может сформировать первичный чек полного расчёта без предыдущей предоплаты.
• Автоматический возврат всегда формирует полный возврат доступного фискального остатка. Частичный возврат выполняется вручную через расширенный чек по заказу.

Раздел виден и доступен только пользователям с правами администратора.

Этот раздел нужен в двух случаях: если сайт закрыт защитой (Cloudflare, WAF, firewall, Basic Auth) или если статусы чеков обновляются с задержкой. В обычной ситуации настраивать его не требуется.

Что это: Callback — автоматическое уведомление от Ferma о смене статуса чека. Polling — резервная проверка статусов по расписанию (WP-Cron) на случай, если callback не дошёл.

1. Если используется Cloudflare, WAF, firewall или Basic Auth, разрешите IP-диапазоны Ferma, указанные в настройках.
2. Откройте диагностику callback, чтобы проверить, что маршрут WordPress зарегистрирован.
3. При необходимости настройте интервал проверки по расписанию.
4. При необходимости настройте лимит проверки: сколько чеков без финального статуса проверять за один проход.

Важно: Диагностика проверяет регистрацию маршрута WordPress, но не гарантирует, что реальные уведомления от Ferma пройдут через защиту сайта.

В разделе «Ferma OFD» выберите «Настройки», раскройте вкладку «Проверки и тесты» и выполните:

1. Отправьте тестовое уведомление на выбранный email, чтобы проверить почтовую отправку WordPress.
2. Проверьте соединение с Ferma после сохранения API-настроек.
3. Результаты тестов и возможные ошибки проверяйте на странице настроек и в журнале.

Раздел описывает, как задать фискальные параметры товара. Действия одинаковы при создании нового товара и при редактировании существующего — блок «Ferma OFD» доступен в карточке товара в обоих случаях, процесс не отличается.

1. Откройте раздел «Товары» в панели слева.
2. Создайте новый или выберите существующий товар для редактирования.
   
3. Обязательно заполните название товара и укажите цену. При необходимости задайте индивидуальные фискальные параметры товара в блоке Ferma OFD: НДС, предмет расчёта и единицу измерения.
4. Нажмите «Опубликовать», если создаете новый товар или обновить, если редактируете существующий.
   

Примечание: Если у товара нет индивидуальных фискальных параметров, используются значения по умолчанию из настроек плагина.

Примечание: Если выбрана устаревшая ставка НДС 20%, плагин покажет предупреждение. Отправка не блокируется.

1. Убедитесь, что поддержка агентских чеков включена в настройках. Подробнее в разделе 4.3.
2. В разделе «Товары» откройте карточку товара.
   
3. Включите признак агентского товара.
4. Выберите источник агентских реквизитов: по умолчанию или индивидуальные. Если выбраны индивидуальные реквизиты, заполните обязательные поля.
   
5. Нажмите «Обновить», если создаете редактируете товар или «Опубликовать», если создаете новый.

Примечание: Если агентские реквизиты выключены в настройках, блок агентских полей в товаре скрывается. Ранее сохранённые данные товара не удаляются и снова станут доступны после включения настройки.

1. Откройте карточку товара.
   
2. В блоке «Ferma OFD» включите настройку «Коды маркировки вводятся в заказе».
3. Выберите тип кода маркировки: из настроек по умолчанию или индивидуально для товара.
   
4. Нажмите «Обновить», если создаете редактируете товар или «Опубликовать», если создаете новый.

Тип КМ сам по себе не включает маркировку. Коды маркировки требуются только для товаров, у которых включён признак маркировки.

Раздел описывает, как выполнять основные действия с плагином. В консоли WordPress дополнительно доступен виджет Ferma OFD — он даёт быстрый обзор: ошибки, статусы, незавершённые операции и элементы, требующие внимания.

Реестр чеков — основной экран для контроля отправленных чеков.

Чтобы найти нужный чек:

1. Перейдите в раздел «Ferma OFD/Реестр чеков».
2. Задайте фильтр периода: сегодня, вчера, последняя неделя или все чеки.
3. При необходимости введите строку поиска по заказу, ID, статусу, InvoiceId или ReceiptId.
4. Выберите количество строк на странице (25, 50, 100 или 200) и нажмите «Показать». Кнопка «Сбросить» возвращает стандартный вид, «Обновить» — перезагружает реестр с текущими фильтрами.
   

Чтобы посмотреть изображение чека, нажмите на идентификатор чека в строке — откроется страница с чеком в том виде, в каком он печатается (обычно в новой вкладке).

Чтобы открыть детали чека, нажмите «Подробнее» в строке — справа откроется панель, где доступны:

• статус и тип операции;
• кнопка открытия чека ОФД, если ссылка есть;
• обновление статуса конкретного чека;
• технические данные: InvoiceId, ReceiptId, ФН, РНМ, ФД, ФПД, и кнопка «Скопировать тех. данные»;
• Raw request, Raw response и Callback payload в раскрывающихся блоках;
• для заказов с частичным возвратом — вся цепочка: предоплата 100%, частичный возврат, полный расчёт и последующие возвраты.

Чтобы выгрузить чеки, нажмите «Экспорт CSV» — выгрузится текущая выборка.

Примечание: Правая панель закрывается крестиком, клавишей Esc или кликом за пределами панели.

В карточке заказа WooCommerce есть блок Ferma OFD. В нём видны фискальная история заказа, предупреждения и рекомендуемое действие.

1. Перейдите в раздел «WooCommerce/Заказы».
2. Откройте карточку товара.
   
3. Найдите в карточке заказа блок Ferma OFD.
4. Проверьте историю чеков по заказу, предупреждения и рекомендуемое действие.
   

• Если заказ содержит позиции с устаревшей ставкой НДС, предупреждение показывается вверху блока.
• Кнопка «Оформить возврат Ferma» не отправляет чек сразу — она открывает расширенный чек по заказу (см. раздел 6.4).
• Если заказ содержит маркированные товары, блок может показать необходимость заполнить КМ перед полным расчётом.

Чтобы создать чек по существующему заказу WooCommerce:

1. Откройте «Ferma OFD/Чеки по заказам WooCommerce».
2. Введите ID заказа вручную или выберите заказ из списка последних заказов.
3. Нажмите «Открыть заказ чека».
   
4. Выберите тип чека Ferma по заказу. Для коррекционного чека заполните тип коррекции, описание, дату исходного чека и основание, если оно требуется.
5. При необходимости измените НДС по позициям в форме «расширенный чек». Устаревшие ставки доступны, но сопровождаются предупреждением.
6. Проверьте состав чека или состав коррекции.
7. Если форма требует подтверждение состава, полного возврата или агентской цепочки, отметьте соответствующий чек-бокс. Подтверждение запрашивается для необратимых или цепочечных операций: полного возврата остатка, продолжения агентской цепочки или когда состав чека отличается от исходного заказа. Без отметки чек сформирован не будет.
8. Кликните «Сформировать чек».
   

Примечание: Если агентские реквизиты выключены, но по заказу уже есть агентская история, связанный последующий чек в заказе будет использовать сохранённые агентские реквизиты. Для ручной операции потребуется отдельное подтверждение.

Ручной возврат выполняется через расширенный чек по заказу. Можно вернуть весь фискальный остаток или только выбранные позиции. Фискальный остаток — это сумма и позиции заказа, ещё не закрытые предыдущими возвратами; именно от него считаются последующие возвраты.

1. Откройте «Ferma OFD/Чеки по заказам WooCommerce».
2. Введите ID заказа вручную или выберите заказ из списка последних заказов.
3. Нажмите «Открыть заказ чека».
   
4. Выберите возвратный тип чека.
5. В блоке «Режим возврата» выберите «Полный возврат» или «Частичный возврат».
6. Для полного возврата подтвердите, что будет возвращён весь доступный фискальный остаток. Для частичного возврата отметьте позиции, которые нужно вернуть, и укажите количество. Товары указываются только в целых единицах.
7. При возврате маркированного товара выберите конкретный КМ.
8. Проверьте сумму возврата, НДС и доступный остаток. Если данные указаны верно, кликните «Подтверждаю полный возврат по всему доступному фискальному остатку заказа.».
9. Нажмите «Сформировать ручной чек Ferma» и проверьте запись в реестре.
   

Важно: Частичный возврат в Ferma OFD не изменяет сам заказ WooCommerce, не создаёт WooCommerce refund и не меняет складские остатки. Если нужно изменить заказ, склад или сделать управленческий возврат денег, это выполняется отдельно по правилам магазина.

Важно: Если вы вручную отметили позиции для частичного возврата, но затем перевели заказ в статус «Возвращён», плагин сформирует полный возврат всего доступного остатка, а ваш ручной выбор позиций будет проигнорирован. Ручной выбор не сохраняется как черновик для автоматизации.

Примечание: Обратите внимание на разницу между операциями. Частичный возврат — это только фискальная операция, заказ WooCommerce он не меняет. Коррекция, наоборот, может изменить заказ — но лишь если включена настройка применения состава коррекции к заказу, и только после успешного подтверждения чека.

Произвольный чек создаётся вручную, без привязки к заказу WooCommerce.

1. Откройте «Ferma OFD/Произвольные чеки без заказа».
2. Выберите тип чека.
3. При необходимости заполните данные покупателя.
4. Выберите тип оплаты по чеку. В текущей версии поддерживается один тип оплаты на весь произвольный чек.
   
5. Добавьте позиции чека: название, количество, цена, НДС, предмет расчёта, единицу измерения и способ расчёта. Если позиция агентская или маркированная³⁾, заполните соответствующие реквизиты. Чтобы позиции учитывались в итоговой сумме, их необходимо активировать.
   
6. Проверьте итоговую сумму.
7. Кликните «Отправить чек без заказа в Ferma».
   

Примечания:

• Сумма оплаты считается автоматически по позициям. Цена указывается с точностью не более 2 знаков после запятой; некорректные значения не округляются автоматически, а блокируются до исправления;
• Если агентские реквизиты выключены в настройках, в произвольных чеках нельзя добавить агентский признак.

Рисунок 12. Форма произвольного чека без заказа (изображение — см. docx)

Чтобы оформить коррекцию ранее пробитого чека:

1. Откройте «Ferma OFD/Чеки по заказам WooCommerce».
2. Введите ID заказа вручную или выберите заказ из списка последних заказов.
3. Нажмите «Открыть заказ чека».
   
4. Выберите коррекционный тип чека.
5. Выберите тип коррекции: самостоятельная или по предписанию.
6. Заполните описание причины коррекции.
7. Проверьте дату исходного чека.
8. Укажите номер основания, если он требуется.
   
9. Отредактируйте только те позиции, суммы и реквизиты, которые должны попасть в коррекцию.
10. Кликните «Подтверждаю, что указанные позиции, суммы, НДС, признаки и единицы измерения являются составом коррекции и должны быть переданы в Ferma.».
11. Если требуется внести изменения в заказ WooCommerce, также заполните блок «После успешного подтверждения чека коррекции применить состав коррекции к заказу WooCommerce».
12. Нажмите «Сформировать ручной чек Ferma».
    

Чтобы оформить произвольную коррекцию ранее пробитого чека:

1. Откройте «Ferma OFD/Произвольные чеки без заказа».
2. Выберите коррекционный тип чека.
3. При необходимости заполните данные покупателя.
4. Выберите тип оплаты по чеку. В текущей версии поддерживается один тип оплаты на весь произвольный чек.
   
5. Укажите чек-основание для коррекции (необязательно).
6. Заполните тип коррекции: самостоятельная или по предписанию.
7. Заполните описание причины коррекции.
8. Проверьте дату исходного чека и номер основания, если он требуется.
   
9. Укажите только те позиции, суммы и реквизиты, которые должны попасть в коррекцию.
   
10. Кликните «Отправить чек без заказа в Ferma».
    

Примечания:

• В произвольной коррекции чек-основание необязателен. Если чек-основание выбран, это должен быть подтверждённый произвольный чек без привязки к WooCommerce-заказу. ФПД выбранного чека передаётся в дополнительный реквизит чека. Коррекции по заказам WooCommerce выполняются через раздел чеков по заказам.
• Коррекционный чек формируется как новый фискальный документ. Если включено применение состава коррекции к заказу, изменение заказа выполняется только после успешного подтверждения чека.

Статусы обычно обновляются автоматически через callback или резервный polling. Если нужно проверить статус немедленно:

1. Откройте «Ferma OFD/Реестр чеков» и найдите нужный чек.
2. Нажмите «Подробнее», чтобы открыть правую панель деталей.
   
3. Нажмите «Обновить статус» — плагин запросит у Ferma актуальный статус чека.
   

Журнал хранит диагностику: ошибки, callback, проверки по расписанию, отправку чеков, тесты соединения и email-уведомления. При обращении в поддержку выгрузите записи кнопкой «Экспорт журнала CSV».

Важно: Очистка журнала удаляет диагностические записи. Перед очисткой выгрузите CSV, если журнал нужен для поддержки.

Раздел «Состояние» показывает общую готовность плагина и помогает собрать данные для поддержки.

• сводная таблица: версия плагина, режим API, подключение Ferma, callback, polling, WordPress, PHP, WooCommerce, HPOS, агентские чеки, email-уведомления;
• блок «Готовность к запуску» с проверками и рекомендациями;
• диагностический JSON-блок, который можно скопировать для поддержки.

Раздел «Ferma OFD/Помощь» содержит справочную информацию по настройкам, агентским реквизитам, маркировке, callback, типовым сценариям, возвратам, коррекциям и ограничениям.

Плагин хранит статус каждого чека по ответам от сервиса Ferma — то есть отражает, обработан ли чек на стороне Ferma и ОФД. Текущий статус виден в реестре чеков и в правой панели деталей.

Таблица 4. Статусы чеков

В таблице — частые ситуации и порядок действий. Если краткого решения недостаточно, откройте правую панель чека и журнал: там виден текст ошибки и технические данные для обращения в поддержку.

Таблица 5. Решение возможных проблем

• Произвольный чек поддерживает один тип оплаты на весь чек. Смешанная оплата несколькими способами в текущей версии не поддерживается.
• Сумма оплаты в произвольном чеке считается автоматически как итог по позициям; вручную она не задаётся.
• Частичный возврат является фискальной операцией Ferma OFD и не изменяет заказ WooCommerce автоматически.
• Частичный возврат не создаёт WooCommerce refund и не меняет складские остатки.
• Для товаров в частичном возврате поддерживается только целое количество; дробные возвраты товаров не поддерживаются.
• Автоматический возврат по статусу заказа формирует полный возврат доступного фискального остатка. Частичный возврат выполняется вручную.
• Произвольные чеки не взаимодействуют с заказами WooCommerce. Чек-основание в произвольной коррекции выбирается только из произвольных чеков без заказа.
• Документ не заменяет бухгалтерскую методологию организации.
• Перед запуском на рабочем магазине необходимо протестировать реальные сценарии магазина.
• Нестандартные сценарии продаж, возвратов или интеграций могут требовать отдельной проверки или доработки.

Версия 1.0
Выпущена 12 октября 2018 г.
Первая отслеживаемая версия документа.

Версия 2.0
Выпущена 24 июня 2026 г.
Переработан плагин и инструкция целиком.