Расширение “Ferma OFD.ru” для CMS “Joomla” и модуля “VirtueMart”

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

Один установочный пакет содержит компонент Ferma OFD и адаптеры для VirtueMart и JoomShopping. В настройках не нужно выбирать адаптер, расширение делает это самостоятельно.

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

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

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

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

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

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

Чек не становится подтверждённым сразу после отправки запроса. Ferma обрабатывает его асинхронно; результат поступает через callback или обнаруживается при проверке статуса.

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

1. Joomla 4.4, 5.x или 6.x и совместимая версия PHP: не ниже 8.1 для Joomla 4.4/5.x; для Joomla 6.x — не ниже 8.3.
2. Установленный компонент интернет-магазина VirtueMart и права администратора Joomla.
3. Логин и пароль ЛКК Ferma, ИНН организации и выбранная система налогообложения.
4. Решение о том, какие статусы заказа соответствуют получению предоплаты, передаче товара/оказанию услуги и возврату.
5. Публичный адрес сайта, доступный Ferma для отправки результата обработки чека. Для штатной работы он должен открываться извне по HTTPS.

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

1. Откройте панель администратора Joomla.
2. Перейдите в раздел «Система».
3. В блоке «Установка» нажмите «Расширения».
   

   

4. В окне «Загрузить и установить» перетащите файл в поле загрузки или нажмите «Или выберите файл» и загрузите архив pkg_fermaofd.zip.
   

   

Дождитесь сообщения Joomla об успешной установке или обновлении. Чтобы перейти на страницу расширения: откройте «Компоненты» → «Ferma OFD».

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

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

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

Откройте Компоненты → Ferma OFD → Настройки и настройте расширение, подробнее о настройках можно узнать в таблице 2.

Таблица 2. Основные настройки и параметры подключения к Ferma

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

Настройка самого чека находится в компоненте, а не в параметрах плагина магазина.

В блоке «Параметры чека» задайте значения, которые будут применяться к позициям заказа, если для товара не настроено индивидуальное значение Ferma (см. таблицу 3).

Таблица 3. Параметры чека

В блоке «Доставка в чеке» включите передачу доставки отдельной позицией, если платная доставка входит в расчёт с покупателем. Укажите её наименование, отдельную ставку НДС доставки, предмет расчёта («Услуга» или «Товар») и единицу измерения. При включённом расчётном НДС для предоплаты ставка доставки преобразуется на тех же условиях, что и ставка товара: например, заданные 22% станут 22/122 только в предоплате. «Без НДС» останется «Без НДС». Не отключайте передачу платной доставки, если её сумму нужно фискализировать: состав и сумма чека могут перестать соответствовать заказу.

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

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

1. Откройте «Заказы VirtueMart» → «Товары».
2. Нажмите на название товара, чтобы открыть карточку товара.
   

   

3. Перейдите на вкладку «Настраиваемые поля».
4. В списке «Тип поля» выберите поле «Ferma OFD — НДС».
   

   

5. В появившемся списке «НДС Ferma» выберите ставку и сохраните товар. Пустое значение «НДС Ferma по умолчанию» оставляет общую ставку из настроек компонента.
   

   

Поле применяется к товарной позиции. Ставку доставки задавайте в блоке «Доставка в чеке», не в карточке товара.

Для каждого события выберите статус именно того момента, когда должен создаваться чек: получение денег, передача товара/оказание услуги, возврат денег. Названия и набор статусов зависят от настроек магазина. Если автоматизация какого-то сценария не нужна, оставьте «Не создавать автоматически» и используйте ручное создание в реестре.

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

1. Откройте Компоненты → Ferma OFD → Настройки.
   

   

2. Найдите блок «VirtueMart: автоматические чеки».
3. Выберите соответствующие статусы заказа для признаков способа расчета. В списке видны код и название статуса.
4. Нажмите «Сохранить настройки». После этого реальная смена статуса заказа на выбранный запускает соответствующую операцию.
   

   

Ferma возвращает результат обработки чека на адрес callback, который расширение формирует автоматически. Посмотреть адрес можно на странице «Состояние». Публичный URL сайта должен указывать на доступный извне адрес Joomla. При блокировке запросов Ferma callback не поступит.

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

  

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

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

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

   

2. Нажмите «Сохранить настройки».
   

   

3. Откройте Ferma OFD → Состояние и нажмите «Проверить подключение к Ferma». Убедитесь, что учётные данные приняты. Эта проверка подтверждает доступ к API, но не заменяет пробный чек.
4. Проверьте публичный URL и наличие адресов callback и cron на этой же странице. Настройте хотя бы один надёжный способ резервной проверки.
   

   

5. Вернитесь в «Настройки», включите «Включить фискализацию» и сохраните изменения.
   

   

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

   

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

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

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

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

Откройте «Ferma OFD» → «Реестр чеков». Здесь показаны подробные детали по заказу.

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

• ReceiptId — идентификатор чека, который присвоила Ferma после регистрации.
• InvoiceId — идентификатор запроса, который формирует расширение. Можно найти на странице чека, открыв по кнопке «Подробнее» в JSON структуре блока «Payload, отправленный в Ferma».

Номер заказа и InvoiceId — разные значения. Ссылка «Открыть чек» появляется, когда доступны сведения для её формирования. Отсутствие ссылки само по себе не означает ошибку отправки.

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

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

   

Чек появится в реестре. Если исходный чек уже отправлен и ожидает подтверждения, новая операция будет ожидать отправки в очереди.

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

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

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

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

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

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

1. Проверьте на странице «Главная», что фискализация включена, выбран правильный магазин и верный контур Ferma.
2. В «Настройках» проверьте ИНН, НДС и адрес сайта.
3. На странице «Состояние» нажмите «Проверить подключение к Ferma» и проверьте время последнего вызова cron. Если callback не доходит, проверьте его доступность и резервную проверку.
4. В «Реестре чеков» откройте конкретную операцию, прочитайте сообщение и при необходимости нажмите «Обновить статус».
5. Откройте «Журнал»: там видны время, событие и сообщение ошибки. Для обращения в поддержку подготовьте внутренний ID заказа, операцию, время, статус, InvoiceId, ReceiptId (если есть) и текст ошибки. Пароли, секретные URL и персональные данные покупателя передавать не нужно.

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

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

Версия 2.0
Выпущена 28 сентября 2026 г.
Документ обновлен под новую версию расширения.