Расширение “Ferma OFD.ru” для CMS “MODX” и модулей “miniShop2”, “miniShop3”

Введение

Расширение «Ferma OFD.ru» связывает интернет-магазин на MODX с облачной кассой Ferma. Оно формирует чеки по заказам miniShop, получает результаты их обработки и ведёт реестр чеков. После установки и настройки основная работа происходит автоматически; администратор контролирует статусы чеков в реестре и разбирает возникающие исключения.

Один установочный пакет подходит для двух сочетаний: MODX 2 с miniShop2 и MODX 3 с miniShop3. Расширение определяет магазин самостоятельно. В руководстве используются общие названия элементов интерфейса, внешний вид менеджера MODX 2 и MODX 3 может отличаться.

1. Назначение и основные принципы

1.1. Какие чеки создаёт расширение

Расширение поддерживает четыре операции по существующему заказу (см. таблицу 1).

Таблица 1. Операции, поддерживаемые расширением

Операция Когда используется
Предоплата 100% Покупатель оплатил заказ до передачи товара или оказания услуги.
Полный расчёт Товар передан или услуга оказана; ранее подтверждённая предоплата засчитывается.
Возврат предоплаты Деньги возвращаются до полного расчёта.
Возврат полного расчёта Деньги возвращаются после полного расчёта.

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

Чек формируется из данных заказа: позиции, количество, сумму и контакт покупателя расширение получает из miniShop. Администратор не вводит произвольный состав чека в реестре и не создаёт чек без заказа. Возврат использует сохранённый состав исходного чека.

1.2. Последовательность чеков и очередь

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

Несколько зависимых операций могут ожидать своих предшественников одновременно. Присвоение ReceiptId и статус «Ожидает» ещё не означают подтверждение чека: дождитесь итогового ответа Ferma. Если исходный чек окончательно отклонён или Ferma сообщила об ошибке ККТ, зависимая операция блокируется; причину нужно посмотреть в реестре.

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

2. Установка и первоначальная настройка

2.1. Что подготовить заранее

Понадобится:

  1. MODX 2 с miniShop2 или MODX 3 с miniShop3 и права администратора менеджера.
  2. Установочный архив Ferma OFD формата transport.zip, учётные данные Ferma и ИНН организации.
  3. Система налогообложения, ставки НДС товаров и доставки, выбранный контур Ferma.
  4. Решение о том, какие статусы заказа соответствуют получению предоплаты, передаче товара или оказанию услуги и возврату.
  5. Публичный адрес сайта, доступный Ferma для отправки результата обработки чека. Для штатной работы он должен открываться извне по HTTPS.

Начните с тестового контура Ferma. На рабочий контур переходите после проверки всех сценариев на тестовых заказах и согласования фискальных настроек с ответственным за учёт.

2.2. Установка пакета

  1. Откройте менеджер MODX и перейдите в менеджер пакетов: «Пакеты» → «Установщик».
    Рисунок 1. Менеджер пакетов MODX и пункт меню "Установщик"
  2. Нажмите стрелку у кнопки «Загрузить пакеты» и выберите «Загрузить пакет с компьютера».
    Рисунок 2. Пункт загрузки локального пакета
  3. В открывшемся окне выберите файл «fermaofd-1.1-pl.transport.zip» и нажмите «Открыть».
    Рисунок 3. Выбор файла пакета на компьютере
  4. После загрузки найдите Ferma OFD в списке пакетов и нажмите «Установить». Далее следуйте указаниям установщика. Дождитесь сообщения об успешной установке.
    Рисунок 4. Установка пакета Ferma OFD
  5. Откройте страницу Ferma OFD через пункт меню менеджера и перейдите на вкладку «Главная».
    Рисунок 5. Главная страница Ferma OFD: состояние и последние операции

До настройки на вкладке «Главная» может показываться предупреждение о выключенной фискализации — это нормально.

При обновлении установите новый ZIP-архив тем же способом поверх установленной версии. Настройки и реестр сохраняются; после обновления откройте вкладку «Состояние» и проверьте подключение. Не удаляйте действующий пакет только ради обновления.

2.3. Основные настройки и подключение к Ferma

В меню «Пакеты» выберите «Ferma OFD», на открывшейся странице перейдите в раздел «Настройки». Подробнее о параметрах можно узнать в таблице 2.

Рисунок 6. Вкладка "Настройки": блоки "Интеграция" и "Состав чека"

Таблица 2. Основные параметры интеграции

Параметр Что указать и на что влияет
«Фискализация включена» Включает автоматическую работу расширения. Пока проверяете настройки, можно оставить значение «Нет». Текущее состояние отображается на вкладке «Главная».
«Публичный HTTPS URL сайта» Внешний адрес сайта, доступный Ferma. Из него формируются адреса callback и cron.
«Контур Ferma» «Тестовый» для проверки, «Рабочий» для настоящих расчётов. Не путайте контуры: тестовый чек не заменяет рабочий.
«Тестовый API URL» По умолчанию указан тестовый адрес Ferma. Меняйте его только по указанию сервиса.
«Логин Ferma», «Пароль Ferma» Учётные данные Ferma. При повторном сохранении пустое поле пароля сохраняет уже записанный пароль.
«ИНН организации» ИНН лица, от имени которого формируются чеки: 10 или 12 цифр.

После заполнения нажмите «Сохранить настройки» и убедитесь, что появилось сообщение об успешном сохранении. Затем нажмите «Проверить соединение»: проверка использует уже сохранённые значения. Успешная авторизация подтверждает доступ к API, но не заменяет пробный чек.

2.4. Автоматические чеки по статусам заказа

Это основная настройка автоматической работы. Расширение не меняет статус заказа и не проверяет факт оплаты в платёжной системе: оно реагирует на переход заказа miniShop в назначенный статус. Поэтому для каждого события в блоке «Автоматические чеки» внизу раздела настроек выберите статус, который в вашем магазине действительно означает соответствующий момент расчёта (см. таблицу 3).

Рисунок 7. Блок "Автоматические чеки": статусы заказа и прямой полный расчёт

Таблица 3. Выбор статусов для автоматических чеков

Поле Какое событие должен означать выбранный статус
«Статус предоплаты» Деньги получены до передачи товара или оказания услуги. Создаётся чек «Предоплата 100%».
«Статус полного расчёта» Товар передан или услуга оказана. Создаётся чек «Полный расчёт»; подтверждённая предоплата засчитывается.
«Статус возврата» Покупателю действительно возвращены деньги. Если по заказу уже есть полный расчёт, создаётся его возврат, иначе — возврат предоплаты.

В каждом выпадающем списке выберите один статус. Один и тот же статус нельзя назначить двум операциям. Если событие не должно создавать чек автоматически, оставьте значение «Не создавать автоматически» и при необходимости создавайте чек вручную из реестра.

Названия статусов на скриншоте приведены только как пример, ориентируйтесь на правила своего магазина. Например, статус «Отменён» подходит для возврата лишь тогда, когда вместе с таким переходом покупателю уже возвращают деньги.

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

Последовательность и прямой полный расчёт

Если статус полного расчёта наступил, пока предоплата ещё ожидает подтверждения Ferma, полный расчёт остаётся в очереди. Аналогично возврат ждёт подтверждения исходного чека. Менять статус заказа повторно для запуска очереди не нужно: после callback или автоматической проверки расширение продолжит цепочку.

Переключатель «Разрешить прямой полный расчёт» обычно оставляют в положении «Нет». Включайте «Да» только если в магазине допустим сценарий, где первый чек по заказу сразу является полным расчётом. Пока переключатель выключен, полный расчёт без созданной предоплаты не отправляется и получает статус «Заблокирован». Включение прямого расчёта не отменяет ожидание уже созданной предоплаты.

Как проверить настройку

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

2.5. Состав чека, НДС и доставка

В блоке «Состав чека» задаются общие значения для товарных позиций (см. таблицу 4). Для отдельного товара НДС и признак предмета расчёта можно переопределить в его карточке (см. раздел 2.6).

Таблица 4. Параметры товарной позиции

Параметр Значение
«Система налогообложения» Система, передаваемая в чек. Она должна соответствовать системе, которую применяет продавец.
«НДС товара по умолчанию» Ставка для товара без индивидуального значения Ferma. Доступны «Без НДС», 0%, 5%, 7%, 10%, 22% и соответствующие расчётные ставки.
«Расчётный НДС для предоплаты» Если включён, только в чеке предоплаты обычная ставка переводится в расчётную, например 22% → 22/122. Уже расчётная ставка не меняется. В чеке полного расчёта обратного преобразования нет.
«Признак предмета расчёта товара по умолчанию» «Товар» или «Услуга» для позиций без индивидуального значения.
«Вид оплаты» Форма оплаты для чека. При полном расчёте после подтверждённой предоплаты расширение передаёт зачёт предоплаты.
«Единица измерения товара» Общая единица для товарных позиций.

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

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

В блоке «Кассир» при необходимости включите передачу сведений о кассире. Тогда ФИО обязательно; ИНН можно оставить пустым, а заполненный ИНН должен состоять из 10 или 12 цифр.

2.6. Индивидуальные параметры товара

Индивидуальные значения нужны, когда ставка НДС или признак предмета расчёта отдельного товара отличаются от общих настроек. Они влияют только на чеки Ferma и не меняют налоги и цены miniShop. Если индивидуальное значение не указано, применяется значение из настроек Ferma.

  1. Откройте карточку товара в меню «Пакеты» → «miniShop3» (или miniShop2 в зависимости от конфигурации) → «Товары».
    Рисунок 8. Пункт "Товары" в меню miniShop3
  2. Перейдите на вкладку «Дополнительные поля (TV)».
  3. Найдите поле «НДС Ferma» и выберите ставку. При необходимости выберите значение в поле «Признак предмета расчёта Ferma». Значение «Из общих настроек» оставляет общий параметр.
    Рисунок 9. Дополнительные поля Ferma на вкладке "Дополнительные поля (TV)"
  4. Нажмите «Сохранить» в карточке товара.

Для нового товара сначала сохраните сам товар: до первого сохранения у него ещё нет ID.

Поле TV связано с шаблоном ресурса, поэтому может отображаться и у ресурсов, не являющихся товарами, если им назначен тот же шаблон. На чек влияет только значение у товара заказа. Параметры доставки задавайте в блоке «Доставка» настроек Ferma, а не в TV товара.

2.7. Callback и резервная проверка статусов

Ferma возвращает результат обработки чека на callback-адрес расширения. Адрес формируется автоматически, посмотреть его можно на вкладке «Состояние». Если callback задерживается или не поступает, ожидающие чеки проверяются опросом.

  • Поле «Интервал проверки, минуты» задаёт время до первого автоматического запроса статуса после отправки чека и ограничивает частоту последующих проверок. Доступны 1, 2, 5, 10 и 20 минут. Callback обрабатывается сразу, не дожидаясь интервала.
  • Поле «Лимит cron за запуск» ограничивает число заданий, обрабатываемых за один запуск.

Проверка по посещениям витрины и менеджера MODX работает постоянно, пока включена фискализация: очередное посещение может запустить обработку готовых заданий и очереди. Это не гарантирует точное время проверки на сайте без посещений. При низкой посещаемости администратор сервера может дополнительно настроить HTTP cron по адресу, указанному на вкладке «Состояние». Установочный пакет серверное расписание автоматически не создаёт.

Рисунок 10. Вкладка "Состояние": магазин, секрет callback и последний запуск cron

Важно: Не публикуйте и не пересылайте целиком адреса callback и cron. Они содержат секретный параметр. Передавайте их только администратору сервера по защищённому каналу.

2.8. Проверка подключения и включение

  1. Сохраните настройки тестового контура и нажмите «Проверить соединение».
  2. На вкладке «Настройки» убедитесь, что указан публичный HTTPS URL.
  3. Откройте вкладку «Состояние» и убедитесь, что адреса callback и cron сформированы.
  4. Вернитесь в «Настройки», включите фискализацию и сохраните изменения.
  5. Создайте тестовый заказ и последовательно проверьте предоплату, полный расчёт и возврат. Дождитесь, пока в реестре чеки получат итоговые статусы.
  6. Перед настоящими расчётами переключитесь на рабочий контур, сохраните настройки и повторно проверьте соединение. Не используйте тестовые чеки как подтверждение реальных расчётов.

3. Использование расширения

3.1. Автоматическое создание чеков

Когда заказ переходит в один из настроенных статусов, расширение определяет операцию, собирает данные существующего заказа и отправляет чек в Ferma или ставит зависимый чек в очередь. Открытие заказа и повторное сохранение без смены статуса новый чек не запускают.

Пример обычного сценария:

  1. Заказ получает статус оплаты: создаётся чек «Предоплата 100%».
  2. Ferma подтверждает этот чек: статус в реестре становится «Подтверждён».
  3. Заказ получает статус передачи: создаётся «Полный расчёт», а сумма ранее полученной предоплаты засчитывается.
  4. Если нужен возврат, заказ получает настроенный статус возврата. Расширение выбирает возврат полного расчёта, если такой чек уже есть, иначе — возврат предоплаты.

Если этап 3 или 4 наступил раньше подтверждения предыдущего чека, следующая операция появится в реестре как ожидающая. Она отправится после подтверждения исходного чека, при очередной обработке callback или опроса. Повторно менять статус заказа только для ускорения очереди не требуется.

3.2. Реестр чеков и детали

Откройте «Ferma OFD» → «Реестр чеков». В реестре можно фильтровать записи по периоду, искать их по заказу, ID, статусу, InvoiceId или ReceiptId, выбирать количество строк на странице (25, 50 или 100) и листать результаты. Для каждого заказа в реестре показаны его операции и их статусы.

Рисунок 11. Поиск, период и действия в реестре чеков

  • Кнопка «Обновить список» перечитывает записи без принудительной проверки Ferma.
  • Кнопка «Проверить статусы» запускает проверку ожидающих операций и обработку очереди.
  • Кнопка «Подробнее» открывает панель «Детали операции» с данными конкретного чека.

В панели «Детали операции» отображаются состояние, дата создания и число попыток операции. Кнопка «Проверить статус» запрашивает у Ferma актуальный статус чека, кнопка «Открыть чек ОФД» открывает чек в ОФД. Данные каждой попытки отправки собраны в блоке «История отправки».

Рисунок 12. Панель "Детали операции"

Реквизиты в истории отправки (рядом с каждым есть кнопка «Скопировать»):

  • InvoiceId — идентификатор запроса, который формирует расширение;
  • ReceiptId — идентификатор чека, который присвоила Ferma;
  • «Следующая проверка» — время следующей автоматической проверки статуса чека;
  • ФН — номер фискального накопителя;
  • ФДН — номер фискального документа;
  • ФПД — фискальный признак документа.

Раскрывающиеся блоки «Сохранённый запрос», «Ответ регистрации» и «Последний ответ статуса» содержат технические данные, которые понадобятся при обращении в поддержку.

InvoiceId и ReceiptId отличаются от номера заказа. После определённой ошибки отправки повтор создаёт новый InvoiceId для той же операции.

Кнопка «Открыть чек ОФД» появляется, когда доступны сведения для формирования ссылки на чек. Отсутствие кнопки само по себе не означает ошибку отправки: ориентируйтесь на статус операции и ответ Ferma.

3.3. Ручное создание чека по заказу

Ручная отправка полезна, если для нужного события автоматический статус не назначен. Создать произвольный чек без заказа здесь нельзя.

  1. Откройте вкладку «Реестр чеков», пролистайте в самый низ вкладки и раскройте блок «Создать чек вручную».
  2. Укажите ID или номер заказа и выберите нужный заказ из списка подсказок.
  3. Выберите операцию в раскрывающемся списке.
  4. Нажмите «Отправить чек в Ferma».
    Рисунок 13. Выбор существующего заказа и допустимой операции для ручной отправки

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

3.4. Что означают основные статусы

Статусы чеков в реестре и рекомендуемые действия приведены в таблице 5.

Таблица 5. Статусы чеков и действия администратора

Статус в интерфейсе Что делать
«Не отправлен» Операция создана и ожидает отправки. Проверьте, что фискализация включена и обработка очереди работает.
«Ожидает предоплату» / «Ожидает исходный чек» Зависимая операция находится в очереди. Проверьте предшествующий чек; отправлять её отдельно не нужно.
«Отправляется» / «Ожидает» Запрос отправляется или Ferma его обрабатывает. Дождитесь callback или автоматической проверки.
«Исход неизвестен» Нельзя считать запрос неотправленным. Не создавайте новый чек наугад: сначала проверьте результат по прежнему InvoiceId.
«Подтверждён» Ferma подтвердила чек. Зависимая операция может продолжиться.
«Ошибка отправки» Определённая ошибка отправки, ReceiptId нет. Исправьте причину и, если кнопка показана, используйте «Повторить отправку».
«Проверка остановлена» Автоматическая проверка остановилась после неудачных попыток. Проверьте статус вручную и выясните состояние чека в Ferma.
«Отклонён» / «Ошибка ККТ» Ferma вернула отрицательный итог. Изучите детали операции и обратитесь к ответственному за кассу или в поддержку.
«Заблокирован» Предыдущая операция отсутствует или окончательно неуспешна. Сначала разберитесь с ней.

3.5. Повтор после ошибки

Кнопка «Повторить отправку» доступна только для операции со статусом «Ошибка отправки», у которой нет ReceiptId. Устраните причину ошибки, нажмите кнопку и подтвердите действие. Расширение использует ту же запись реестра, но создаёт новую попытку и новый InvoiceId.

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

Повтор не заменяет разбор отказа Ferma или ошибки ККТ. Не пытайтесь исправить такой случай сменой статуса заказа наугад.

3.6. Журнал и диагностика

На вкладке «Журнал» отображаются технические события без паролей и данных покупателя. Записи можно фильтровать по источнику, событию, ID заказа и ID чека; они разбиты на страницы. Журнал помогает понять, была ли создана операция, началась ли отправка, сработал ли опрос и какой ответ сохранён.

Рисунок 14. Журнал событий с фильтрами и постраничным выводом

Если чек не появился или не подтверждается:

  1. Проверьте на вкладке «Главная» и в «Настройках», что фискализация включена.
  2. Проверьте подключение и вкладку «Состояние».
  3. В «Реестре чеков» откройте конкретную операцию, прочитайте сообщение и при необходимости нажмите «Проверить статус».
  4. Откройте «Журнал» и отфильтруйте записи по ID заказа или ID чека.

Для обращения в поддержку подготовьте ID заказа, вид операции, время, статус, InvoiceId, ReceiptId (если он есть) и текст ошибки. Пароль Ferma, секретные URL и персональные данные покупателя передавать не нужно.

4. Важные ограничения

  • Расширение работает только с существующими заказами miniShop. Произвольный payload и чек без заказа в интерфейсе создать нельзя.
  • Для каждой из четырёх операций заказа ведётся одна запись реестра. Повтор после ошибки меняет попытку и InvoiceId, но не создаёт вторую самостоятельную операцию.
  • Частичные предоплаты и возвраты, чеки коррекции, маркировка и агентские схемы в данном интерфейсе не предусмотрены.
  • НДС товара для чеков Ferma берётся из индивидуального поля TV либо из общих настроек Ferma; стандартные налоговые поля miniShop ставку Ferma не задают. У доставки отдельный параметр НДС.
  • Если callback не поступает, а на сайте нет посещений и серверного cron, своевременная проверка статусов не гарантируется. Для магазина с низким трафиком настройте серверное расписание.

История изменений

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

Версия 1.1
Выпущена 28 октября 2026 г.
Обновлен плагин и переработана инструкция для модулей “miniShop2”, “miniShop3”