README

Модуль обеспечивает взаимодействие интернет-магазина на базе CMS Joomla с корзиной JoomShopping с платёжным сервисом ХуткiГрош: выставление счетов в ЕРИП (АИС "Расчет"), оплата картой (WebPay), QR-код, автоматическое обновление статусов заказов после оплаты.

Поддерживаемые версии

Поддерживаются одновременно две версии модуля:

	HutkiGrosh API v3 (рекомендуется)	HutkiGrosh (предыдущее поколение)
Текущая версия	3.2.2	3.1.0
API	актуальное поколение (REST API v3)	предыдущее поколение API
Подключение	API-токен, выбор услуги из списка	логин/пароль, ЕРИП ID вручную
Тестовая система	api-sandbox.hgrosh.by	trial.hgrosh.by
Кому подходит	новым магазинам и тем, кто переходит на API v3	действующим магазинам, работает как раньше

Сервис ХуткiГрош сейчас поддерживает все поколения API параллельно.

Следите за анонсами о сроках отключения старого API и переходите на API v3 заранее (порядок перехода описан в разделе "Одновременная работа и переход на API v3").

Скачать

Для каждой версии CMS используется свой файл сборки (.zip):

CMS	Сборка API v3 (рекомендуется)	Сборка предыдущего поколения
Joomla 4.x + JoomShopping 5.x	plg_jshopping_hutkigrosh_apiv3.zip	нет
Joomla 3.x + JoomShopping 4.x	plg_jshopping_hutkigrosh_apiv3.zip	plg_jshopping_hutkigrosh.zip

Отдельная сборка API v3 обусловлена сменой поколения API сервиса, а не изменениями Joomla: внутри одной версии CMS обе сборки отличаются только поколением API.

Требования

PHP 5.6 и выше (для сборки API v3 — PHP 7.0 и выше; для Joomla 4 требуется PHP 7.2.5 и выше, как требует сама CMS), расширения PHP cURL и openssl

Установка (одинакова для обеих версий модуля)

Joomla 4.x:

Создайте резервную копию магазина и базы данных.
Скачайте архив нужной сборки (раздел "Скачать").
В админке: Система > Установить > Расширения, загрузите скачанный архив.
Перейдите: Компоненты > JoomShopping > Опции > Способы оплаты, выберите способ оплаты Через систему «Расчет» (ЕРИП) (создаётся инсталлятором автоматически; для сборки предыдущего поколения — имя, заданное при её установке) и откройте вкладку "Конфигурация".

Joomla 3.x:

Создайте резервную копию магазина и базы данных.
Скачайте архив нужной сборки (раздел "Скачать").
В административной части Joomla выберите Расширения > Менеджер расширений > Установка > Загрузить Файл пакета, выберите архив и нажмите Загрузить.
Перейдите: Компоненты > JoomShopping > Опции > Способы оплаты, выберите способ оплаты Через систему «Расчет» (ЕРИП) (для сборки предыдущего поколения - Hutkigrosh, имя, заданное при её установке) и откройте вкладку "Конфигурация".

Настройка HutkiGrosh API v3

Шаг 1. Получите API-токен

В бизнес-аккаунте ХуткiГрош откройте Настройки > Интеграция ПУ (раздел доступен ролям "Владелец ПУ" и "Администратор ПУ"). Используйте токен с доступом к информации о ПУ и созданию/редактированию счетов.

Шаг 2. Подключите магазин

В настройках модуля вставьте токен в поле API Токен.
Нажмите кнопку "Актуализировать" (рядом с полем API Токен), модуль загрузит из ХуткiГрош справочники для полей Розничная торговая точка, Услуга, Кассовое место (если токен уже сохранён, списки заполняются автоматически при открытии формы настроек).
Выберите значения в списках и сохраните изменения.

Шаг 3. Остальные параметры

Основное:

Статус: включен/выключен способ оплаты (стандартное поле расширения).
Порядок сортировки: позиция способа оплаты в списке при оформлении заказа (стандартное поле расширения).
Путь в дереве ЕРИП: путь, по которому клиент будет искать выставленный счёт (например, АИС "Расчет" (ЕРИП) > Интернет-магазины/сервисы >).
Срок действия счета (дней): как долго счёт будет доступен в ЕРИП для оплаты (от 1 до 10).
Использовать номер заказа: отправлять на шлюз номер заказа (orderNumber), а не идентификатор (orderId).
Debug mode: запись и отображение дополнительных сообщений при работе модуля (используется при диагностике).

Экран успешного заказа:

Секция "Инструкция": пошаговая инструкция по оплате счёта в ЕРИП.
Секция QR-код: оплата счёта по QR-коду через мобильное приложение банка (QR-код запрашивается у сервиса).
Секция Webpay: кнопка оплаты счёта картой (переход на Webpay).
Текст успешного выставления счета: может содержать HTML, допустимы переменные @order_id, @order_number, @order_total, @order_currency, @order_fullname, @order_phone, @order_address.
CSS файл для итогового экрана: путь к собственному CSS-файлу оформления.

Статусы заказов (выбор из существующих статусов магазина, список статусов — Магазин > Настройки > Статусы):

Статус при выставлении счета: какой статус установить заказу после выставления счёта в ЕРИП. Рекомендуется "Ожидание" (Pending), заказ ожидает оплаты.
Статус при успешной оплате счета. Рекомендуется статус оплаты, заказ ожидает комплектации и отправки.
Статус при отмене оплаты счета. Рекомендуется статус отмены заказа.
Статус при ошибке оплаты счета. Рекомендуется статус ошибочного/неоплаченного заказа.

Уведомления (отправляются шлюзом ХуткiГрош):

Email оповещение: письмо клиенту при успешном выставлении счёта.
Sms оповещение: SMS клиенту при успешном выставлении счёта.

Способ оплаты для клиента:

Название и описание способа оплаты задаются стандартными полями JoomShopping при редактировании способа оплаты (по умолчанию "Через систему «Расчет» (ЕРИП)").

Обязательно: адрес обработчика уведомлений

Для автоматического обновления статуса заказа (после оплаты клиентом счёта в ЕРИП) сообщите в службу технической поддержки ХуткiГрош адрес обработчика, указав Ваш домен (для Joomla 3.x и 4.x адрес одинаков):

https://ваш-домен/index.php?option=com_jshopping&controller=hutkigrosh&task=notify

Модуль принимает уведомление запросом с идентификатором счёта (purchaseid) в URL.

Тестовый режим (Sandbox)

Получите API-токен тестовой системы (выдаётся при регистрации в ХуткiГрош).
Включите в настройках модуля режим Sandbox и настройте согласно инструкции выше.
Счета будут выставляться в тестовую систему api-sandbox.hgrosh.by.
Для эмуляции оплаты счёта используйте личный кабинет (сверху-справа "Профиль пользователя" > "Тестовый режим").

Документация API v3: https://api-dev.hgrosh.by/eripservice/docs/ru/index.html

Настройка Hutkigrosh (предыдущее поколение)

Перейдите к настройке модуля (см. "Установка").

Параметры подключения:

Логин: Ваш логин для доступа к ХуткiГрош (необходимо обратиться к менеджерам для получения рабочего или тестового логина).
Пароль: Ваш пароль для доступа к ХуткiГрош (необходимо обратиться к менеджерам для получения рабочего или тестового пароля).
ЕРИП ID: уникальный идентификатор услуги в ЕРИП.
Код услуги: код услуги в дереве ЕРИП, используется при генерации QR-кода.
Sandbox: тестовый режим, счета выставляются в тестовую систему trial.hgrosh.by.

Основное:

Статус: включен/выключен способ оплаты (стандартное поле расширения).
Порядок сортировки: позиция способа оплаты в списке при оформлении заказа (стандартное поле расширения).
Путь в дереве ЕРИП: путь, по которому клиент будет искать выставленный счёт (например, АИС "Расчет" (ЕРИП) > Интернет-магазины/сервисы >).
Срок действия счета (дней): как долго счёт будет доступен в ЕРИП для оплаты.
Использовать номер заказа: отправлять на шлюз номер заказа (orderNumber), а не идентификатор (orderId).
Debug mode: запись и отображение дополнительных сообщений при работе модуля (используется при диагностике).

Экран успешного заказа:

Секция "Инструкция": пошаговая инструкция по оплате счёта в ЕРИП.
Секция QR-код: оплата счёта по QR-коду через мобильное приложение банка (QR-код генерируется модулем).
Секция Webpay: кнопка оплаты счёта картой (переход на Webpay).
Секция Alfaclick: не работает, сервис ХуткiГрош прекратил поддержку выставления счетов в Alfaclick. Секция еще присутствует в настройках этой сборки, но включать ее не нужно (в сборке API v3 секция отсутствует).
Текст успешного выставления счета: может содержать HTML, допустимы переменные @order_id, @order_number, @order_total, @order_currency, @order_fullname, @order_phone, @order_address.
CSS файл для итогового экрана: путь к собственному CSS-файлу оформления.

Статус при выставлении счета: какой статус установить заказу после выставления счёта в ЕРИП. Рекомендуется "Ожидание" (Pending), заказ ожидает оплаты.
Статус при успешной оплате счета. Рекомендуется статус оплаты, заказ ожидает комплектации и отправки.
Статус при отмене оплаты счета. Рекомендуется статус отмены заказа.
Статус при ошибке оплаты счета. Рекомендуется статус ошибочного/неоплаченного заказа.

Уведомления (отправляются шлюзом ХуткiГрош):

Email оповещение: письмо клиенту при успешном выставлении счёта.
Sms оповещение: SMS клиенту при успешном выставлении счёта.

Способ оплаты для клиента:

Название и описание способа оплаты задаются стандартными полями JoomShopping при редактировании способа оплаты (по умолчанию "Через систему «Расчет» (ЕРИП)").

Сохраните изменения.

Обязательно: адрес обработчика уведомлений

См. раздел "Адрес обработчика уведомлений" выше: адреса совпадают для обоих поколений API.

Тестовый режим

Используйте данные для подключения к тестовой системе, полученные при регистрации в ХуткiГрош.
Включите в настройках модуля режим "Песочницы" (Sandbox) и настройте согласно инструкции выше.
Для эмуляции оплаты клиентом выставленного счёта воспользуйтесь личным кабинетом тестовой системы (меню "Тест оплаты ЕРИП").

Одновременная работа и переход на API v3

Обе сборки являются одним и тем же расширением (плагин hutkigrosh группы jshopping, общий способ оплаты и общие настройки): сборка API v3 устанавливается поверх предыдущей версии и замещает её файлы; заказы и данные магазина не затрагиваются. Обратный переход выполняется установкой предыдущей сборки поверх.
Адрес обработчика уведомлений не меняется: сообщать в поддержку ХуткiГрош новый адрес не нужно.
Способ оплаты в магазине остается один: двойная обработка уведомлений исключена.
Настройки статусов, текстов и секций сохраняются при переходе; поля подключения меняются: вместо "Логин/Пароль/ЕРИП ID/Код услуги" заполняется "API Токен" и справочники "Услуга", "Розничная торговая точка", "Кассовое место" (ранее сохраненные значения остаются в базе данных).

Рекомендуемый порядок перехода:

Создайте резервную копию магазина и базы данных.
Получите API-токен тестовой системы (см. "Настройка Hutkigrosh API v3", шаг 1).
Установите сборку API v3 поверх предыдущей версии (порядок установки см. в разделе "Установка").
В настройках модуля вставьте токен в поле "API Токен", нажмите "Актуализировать" и выберите значения в списках "Услуга", "Розничная торговая точка", "Кассовое место".
Включите режим Sandbox и проверьте выставление и оплату счёта (эмуляция оплаты в личном кабинете тестовой системы, см. "Тестовый режим").
Выключите Sandbox и вставьте токен выданный для рабочей системы в поле "API Токен", нажмите "Актуализировать" и выберите значения в списках "Услуга", "Розничная торговая точка", "Кассовое место": счета будут выставляться в рабочую систему.
Проверьте обработчик уведомлений: статус заказа в магазине должен измениться после оплаты счёта.

Логи

Модуль ведет лог файл по пути (название файла cmsgate.log для обоих поколений API одинаково):

сборка API v3: <корень_сайта>/plugins/jshopping/hutkigrosh/vendor/apiv3/cmsgate-core/logs/cmsgate.log
сборка предыдущего поколения: <корень_сайта>/plugins/jshopping/hutkigrosh/vendor/esas/cmsgate-core/logs/cmsgate.log

Также скачать лог можно кнопкой Скачать логи в настройках модуля.

Для обеспечения безопасности необходимо убедиться, что в настройках http-сервера включена директива AllowOverride All для корневой папки.

Поддержка

По вопросам подключения и работы сервиса обращайтесь в службу технической поддержки ХуткiГрош.

esas / cmsgate-joomshopping-hutkigrosh

Package info

Security

Statistics

README

Поддерживаемые версии

Скачать

Требования

Установка (одинакова для обеих версий модуля)

Настройка HutkiGrosh API v3

Шаг 1. Получите API-токен

Шаг 2. Подключите магазин

Шаг 3. Остальные параметры

Обязательно: адрес обработчика уведомлений

Тестовый режим (Sandbox)

Настройка Hutkigrosh (предыдущее поколение)

Обязательно: адрес обработчика уведомлений

Тестовый режим

Одновременная работа и переход на API v3

Логи

Поддержка