Расширение «Ferma OFD.ru» связывает интернет-магазин на MODX с облачной кассой Ferma. Оно формирует чеки по заказам miniShop, получает результаты их обработки и ведёт реестр чеков. После установки и настройки основная работа происходит автоматически; администратор контролирует статусы чеков в реестре и разбирает возникающие исключения.
Один установочный пакет подходит для двух сочетаний: MODX 2 с miniShop2 и MODX 3 с miniShop3. Расширение определяет магазин самостоятельно. В руководстве используются общие названия элементов интерфейса, внешний вид менеджера MODX 2 и MODX 3 может отличаться.
Расширение поддерживает четыре операции по существующему заказу (см. таблицу 1).
Таблица 1. Операции, поддерживаемые расширением
| Операция | Когда используется |
|---|---|
| Предоплата 100% | Покупатель оплатил заказ до передачи товара или оказания услуги. |
| Полный расчёт | Товар передан или услуга оказана; ранее подтверждённая предоплата засчитывается. |
| Возврат предоплаты | Деньги возвращаются до полного расчёта. |
| Возврат полного расчёта | Деньги возвращаются после полного расчёта. |
Статусы заказа, запускающие предоплату, полный расчёт и возврат, администратор выбирает в настройках. Для возврата расширение определяет вид чека по уже созданным операциям заказа. Назначайте разные статусы для трёх сценариев: один статус не должен одновременно означать оплату, передачу и возврат.
Чек формируется из данных заказа: позиции, количество, сумму и контакт покупателя расширение получает из miniShop. Администратор не вводит произвольный состав чека в реестре и не создаёт чек без заказа. Возврат использует сохранённый состав исходного чека.
Обычная последовательность: предоплата → подтверждение Ferma → полный расчёт → при необходимости возврат. Если статус полного расчёта или возврата установлен до подтверждения предшествующего чека, расширение сохраняет операцию в очереди и отправляет её после подтверждения исходного чека, при очередной обработке очереди.
Несколько зависимых операций могут ожидать своих предшественников одновременно. Присвоение ReceiptId и статус «Ожидает» ещё не означают подтверждение чека: дождитесь итогового ответа Ferma. Если исходный чек окончательно отклонён или Ferma сообщила об ошибке ККТ, зависимая операция блокируется; причину нужно посмотреть в реестре.
Важно: Прямой полный расчёт без предоплаты разрешается только при включённой настройке «Разрешить прямой полный расчёт». Включайте её лишь для сценария, где первый и единственный чек по заказу действительно должен быть полным расчётом.
Понадобится:
Начните с тестового контура Ferma. На рабочий контур переходите после проверки всех сценариев на тестовых заказах и согласования фискальных настроек с ответственным за учёт.
До настройки на вкладке «Главная» может показываться предупреждение о выключенной фискализации — это нормально.
При обновлении установите новый ZIP-архив тем же способом поверх установленной версии. Настройки и реестр сохраняются; после обновления откройте вкладку «Состояние» и проверьте подключение. Не удаляйте действующий пакет только ради обновления.
В меню «Пакеты» выберите «Ferma OFD», на открывшейся странице перейдите в раздел «Настройки». Подробнее о параметрах можно узнать в таблице 2.
Таблица 2. Основные параметры интеграции
| Параметр | Что указать и на что влияет |
|---|---|
| «Фискализация включена» | Включает автоматическую работу расширения. Пока проверяете настройки, можно оставить значение «Нет». Текущее состояние отображается на вкладке «Главная». |
| «Публичный HTTPS URL сайта» | Внешний адрес сайта, доступный Ferma. Из него формируются адреса callback и cron. |
| «Контур Ferma» | «Тестовый» для проверки, «Рабочий» для настоящих расчётов. Не путайте контуры: тестовый чек не заменяет рабочий. |
| «Тестовый API URL» | По умолчанию указан тестовый адрес Ferma. Меняйте его только по указанию сервиса. |
| «Логин Ferma», «Пароль Ferma» | Учётные данные Ferma. При повторном сохранении пустое поле пароля сохраняет уже записанный пароль. |
| «ИНН организации» | ИНН лица, от имени которого формируются чеки: 10 или 12 цифр. |
После заполнения нажмите «Сохранить настройки» и убедитесь, что появилось сообщение об успешном сохранении. Затем нажмите «Проверить соединение»: проверка использует уже сохранённые значения. Успешная авторизация подтверждает доступ к API, но не заменяет пробный чек.
Это основная настройка автоматической работы. Расширение не меняет статус заказа и не проверяет факт оплаты в платёжной системе: оно реагирует на переход заказа miniShop в назначенный статус. Поэтому для каждого события в блоке «Автоматические чеки» внизу раздела настроек выберите статус, который в вашем магазине действительно означает соответствующий момент расчёта (см. таблицу 3).
Таблица 3. Выбор статусов для автоматических чеков
| Поле | Какое событие должен означать выбранный статус |
|---|---|
| «Статус предоплаты» | Деньги получены до передачи товара или оказания услуги. Создаётся чек «Предоплата 100%». |
| «Статус полного расчёта» | Товар передан или услуга оказана. Создаётся чек «Полный расчёт»; подтверждённая предоплата засчитывается. |
| «Статус возврата» | Покупателю действительно возвращены деньги. Если по заказу уже есть полный расчёт, создаётся его возврат, иначе — возврат предоплаты. |
В каждом выпадающем списке выберите один статус. Один и тот же статус нельзя назначить двум операциям. Если событие не должно создавать чек автоматически, оставьте значение «Не создавать автоматически» и при необходимости создавайте чек вручную из реестра.
Названия статусов на скриншоте приведены только как пример, ориентируйтесь на правила своего магазина. Например, статус «Отменён» подходит для возврата лишь тогда, когда вместе с таким переходом покупателю уже возвращают деньги.
После перехода заказа в назначенный статус операция появляется в реестре. Повторное сохранение заказа без нового перехода дубль не создаёт. Изменение настройки не создаёт чеки задним числом по уже завершённым переходам: пропущенную операцию проверьте и создайте через реестр.
Если статус полного расчёта наступил, пока предоплата ещё ожидает подтверждения Ferma, полный расчёт остаётся в очереди. Аналогично возврат ждёт подтверждения исходного чека. Менять статус заказа повторно для запуска очереди не нужно: после callback или автоматической проверки расширение продолжит цепочку.
Переключатель «Разрешить прямой полный расчёт» обычно оставляют в положении «Нет». Включайте «Да» только если в магазине допустим сценарий, где первый чек по заказу сразу является полным расчётом. Пока переключатель выключен, полный расчёт без созданной предоплаты не отправляется и получает статус «Заблокирован». Включение прямого расчёта не отменяет ожидание уже созданной предоплаты.
В блоке «Состав чека» задаются общие значения для товарных позиций (см. таблицу 4). Для отдельного товара НДС и признак предмета расчёта можно переопределить в его карточке (см. раздел 2.6).
Таблица 4. Параметры товарной позиции
| Параметр | Значение |
|---|---|
| «Система налогообложения» | Система, передаваемая в чек. Она должна соответствовать системе, которую применяет продавец. |
| «НДС товара по умолчанию» | Ставка для товара без индивидуального значения Ferma. Доступны «Без НДС», 0%, 5%, 7%, 10%, 22% и соответствующие расчётные ставки. |
| «Расчётный НДС для предоплаты» | Если включён, только в чеке предоплаты обычная ставка переводится в расчётную, например 22% → 22/122. Уже расчётная ставка не меняется. В чеке полного расчёта обратного преобразования нет. |
| «Признак предмета расчёта товара по умолчанию» | «Товар» или «Услуга» для позиций без индивидуального значения. |
| «Вид оплаты» | Форма оплаты для чека. При полном расчёте после подтверждённой предоплаты расширение передаёт зачёт предоплаты. |
| «Единица измерения товара» | Общая единица для товарных позиций. |
В блоке «Доставка» включите передачу доставки отдельной позицией, если платная доставка входит в расчёт с покупателем. Для неё отдельно задаются название, НДС, признак предмета расчёта и единица измерения. Преобразование обычной ставки в расчётную при предоплате действует и для доставки; уже расчётная ставка сохраняется.
Важно: Не исключайте платную доставку из чека, если её сумму нужно фискализировать: итоговая сумма чека должна соответствовать расчёту с покупателем.
В блоке «Кассир» при необходимости включите передачу сведений о кассире. Тогда ФИО обязательно; ИНН можно оставить пустым, а заполненный ИНН должен состоять из 10 или 12 цифр.
Индивидуальные значения нужны, когда ставка НДС или признак предмета расчёта отдельного товара отличаются от общих настроек. Они влияют только на чеки Ferma и не меняют налоги и цены miniShop. Если индивидуальное значение не указано, применяется значение из настроек Ferma.
Для нового товара сначала сохраните сам товар: до первого сохранения у него ещё нет ID.
Поле TV связано с шаблоном ресурса, поэтому может отображаться и у ресурсов, не являющихся товарами, если им назначен тот же шаблон. На чек влияет только значение у товара заказа. Параметры доставки задавайте в блоке «Доставка» настроек Ferma, а не в TV товара.
Ferma возвращает результат обработки чека на callback-адрес расширения. Адрес формируется автоматически, посмотреть его можно на вкладке «Состояние». Если callback задерживается или не поступает, ожидающие чеки проверяются опросом.
Проверка по посещениям витрины и менеджера MODX работает постоянно, пока включена фискализация: очередное посещение может запустить обработку готовых заданий и очереди. Это не гарантирует точное время проверки на сайте без посещений. При низкой посещаемости администратор сервера может дополнительно настроить HTTP cron по адресу, указанному на вкладке «Состояние». Установочный пакет серверное расписание автоматически не создаёт.
Важно: Не публикуйте и не пересылайте целиком адреса callback и cron. Они содержат секретный параметр. Передавайте их только администратору сервера по защищённому каналу.
Когда заказ переходит в один из настроенных статусов, расширение определяет операцию, собирает данные существующего заказа и отправляет чек в Ferma или ставит зависимый чек в очередь. Открытие заказа и повторное сохранение без смены статуса новый чек не запускают.
Пример обычного сценария:
Если этап 3 или 4 наступил раньше подтверждения предыдущего чека, следующая операция появится в реестре как ожидающая. Она отправится после подтверждения исходного чека, при очередной обработке callback или опроса. Повторно менять статус заказа только для ускорения очереди не требуется.
Откройте «Ferma OFD» → «Реестр чеков». В реестре можно фильтровать записи по периоду, искать их по заказу, ID, статусу, InvoiceId или ReceiptId, выбирать количество строк на странице (25, 50 или 100) и листать результаты. Для каждого заказа в реестре показаны его операции и их статусы.
В панели «Детали операции» отображаются состояние, дата создания и число попыток операции. Кнопка «Проверить статус» запрашивает у Ferma актуальный статус чека, кнопка «Открыть чек ОФД» открывает чек в ОФД. Данные каждой попытки отправки собраны в блоке «История отправки».
Реквизиты в истории отправки (рядом с каждым есть кнопка «Скопировать»):
Раскрывающиеся блоки «Сохранённый запрос», «Ответ регистрации» и «Последний ответ статуса» содержат технические данные, которые понадобятся при обращении в поддержку.
InvoiceId и ReceiptId отличаются от номера заказа. После определённой ошибки отправки повтор создаёт новый InvoiceId для той же операции.
Кнопка «Открыть чек ОФД» появляется, когда доступны сведения для формирования ссылки на чек. Отсутствие кнопки само по себе не означает ошибку отправки: ориентируйтесь на статус операции и ответ Ferma.
Ручная отправка полезна, если для нужного события автоматический статус не назначен. Создать произвольный чек без заказа здесь нельзя.
Сумма, позиции, НДС и контакт покупателя берутся из заказа и настроек Ferma. Перед отправкой проверьте заказ, параметры доставки и индивидуальные поля товаров. Если нужной операции нет в списке, она могла быть создана ранее или ограничена последовательностью предыдущих чеков.
Статусы чеков в реестре и рекомендуемые действия приведены в таблице 5.
Таблица 5. Статусы чеков и действия администратора
| Статус в интерфейсе | Что делать |
|---|---|
| «Не отправлен» | Операция создана и ожидает отправки. Проверьте, что фискализация включена и обработка очереди работает. |
| «Ожидает предоплату» / «Ожидает исходный чек» | Зависимая операция находится в очереди. Проверьте предшествующий чек; отправлять её отдельно не нужно. |
| «Отправляется» / «Ожидает» | Запрос отправляется или Ferma его обрабатывает. Дождитесь callback или автоматической проверки. |
| «Исход неизвестен» | Нельзя считать запрос неотправленным. Не создавайте новый чек наугад: сначала проверьте результат по прежнему InvoiceId. |
| «Подтверждён» | Ferma подтвердила чек. Зависимая операция может продолжиться. |
| «Ошибка отправки» | Определённая ошибка отправки, ReceiptId нет. Исправьте причину и, если кнопка показана, используйте «Повторить отправку». |
| «Проверка остановлена» | Автоматическая проверка остановилась после неудачных попыток. Проверьте статус вручную и выясните состояние чека в Ferma. |
| «Отклонён» / «Ошибка ККТ» | Ferma вернула отрицательный итог. Изучите детали операции и обратитесь к ответственному за кассу или в поддержку. |
| «Заблокирован» | Предыдущая операция отсутствует или окончательно неуспешна. Сначала разберитесь с ней. |
Кнопка «Повторить отправку» доступна только для операции со статусом «Ошибка отправки», у которой нет ReceiptId. Устраните причину ошибки, нажмите кнопку и подтвердите действие. Расширение использует ту же запись реестра, но создаёт новую попытку и новый InvoiceId.
Важно: Не повторяйте отправку для статусов «Ожидает», «Отправляется» и «Исход неизвестен»: Ferma могла принять первый запрос, и повтор создаст риск второго чека. Сначала выясните результат по сохранённому идентификатору.
Повтор не заменяет разбор отказа Ferma или ошибки ККТ. Не пытайтесь исправить такой случай сменой статуса заказа наугад.
На вкладке «Журнал» отображаются технические события без паролей и данных покупателя. Записи можно фильтровать по источнику, событию, ID заказа и ID чека; они разбиты на страницы. Журнал помогает понять, была ли создана операция, началась ли отправка, сработал ли опрос и какой ответ сохранён.
Если чек не появился или не подтверждается:
Для обращения в поддержку подготовьте ID заказа, вид операции, время, статус, InvoiceId, ReceiptId (если он есть) и текст ошибки. Пароль Ferma, секретные URL и персональные данные покупателя передавать не нужно.
Версия 1.0
Выпущена 07 марта 2019 г.
Первая отслеживаемая версия документа.
Версия 1.1
Выпущена 28 октября 2026 г.
Обновлен плагин и переработана инструкция для модулей “miniShop2”, “miniShop3”