Курс валют

1. Что делает модуль

Модуль предназначен для автоматической и ручной синхронизации курсов валют в интернет-магазинах на ocStore 3.0.x / OpenCart 3.0.x. Он заменяет стандартный неработающий механизм Европейского центробанка (ЕЦБ) на прямую интеграцию с тремя независимыми украинскими финансовыми источниками.

Ключевые возможности:

• 3 независимых источника курсов:

  • Национальный банк Украины (НБУ): официальный курс всех мировых валют.

  • Монобанк (Monobank API): актуальные котировки коммерческого банка с автоматической конвертацией кодов ISO 4217 и защитой от лимитов запросов.

  • ПриватБанк (PrivatBank API): возможность выбора между наличным курсом отделений (coursid=5) и карточным/безналичным курсом (coursid=11).

• Гибкий выбор типа котировки: для Монобанка и ПриватБанка можно выбрать, по какому курсу пересчитывать цены:

  • Курс продажи (Sale) — стандарт для розничной торговли;

  • Курс покупки (Buy);

  • Средний курс (Buy + Sale) / 2.

• Математическая точность: модуль автоматически определяет базовую валюту магазина (UAH, USD или EUR) и пересчитывает коэффициенты Value для витрины:

  $$\text{Value} = \frac{\text{Rate}(\text{Base})}{\text{Rate}(\text{Currency})}$$

• Процентная коррекция: позволяет добавить буфер к курсу (например, +1.5% для страховки от курсовых колебаний или -1%).

• Выборочное обновление: возможность выбрать чекбоксами только те валюты, которые нужно изменять.

• Автоматизация (CRON): фоновое обновление по расписанию через планировщик хостинга с защитой секретным токеном.

• Журнал событий: фиксация всех запросов, обновленных значений и ошибок в файл лога прямо в интерфейсе модуля.

2. Как установить модуль

1. Скачайте установочный архив

    

2. Загрузите модуль в систему:

   • Откройте панель управления магазином: Модули / Расширения → Установка расширений (Installer).

   • Нажмите кнопку «Загрузить» и выберите скачанный .ocmod.zip архив. Дождитесь зеленого уведомления об успешной загрузке.

3. Обновите кэш модификаторов:

   • Перейдите в Модули / Расширения → Модификаторы (Modifications).

   • Нажмите синюю кнопку «Обновить» (со стрелками) в правом верхнем углу.

4. Проверьте права доступа:

   • Перейдите в Система → Пользователи → Группы пользователей.

   • Откройте на редактирование группу «Администраторы» (или вашу текущую).

   • В списках «Разрешить просмотр» и «Разрешить редактирование» убедитесь, что отмечены пункты:

     • extension/currency/bank_ua

     • extension/extension/currency

   • Нажмите «Сохранить».

5. Активация:

   • Перейдите в Модули / Расширения → Модули / Расширения.

   • В выпадающем списке «Тип расширения» выберите «Курсы валют».

   • Напротив модуля «Курсы валют Украины» нажмите зеленую кнопку «Установить», затем синюю «Редактировать».

3. Как управлять модулем

После установки модуль доступен тремя удобными способами:

1. Через боковое меню: Система → Локализация → Автообновление валют.

2. Из списка валют: Система → Локализация → Валюты (иконка шестеренки в верхнем тулбаре).

3. Из каталога расширений: Модули / Расширения → Курсы валют.

Вкладка 1: «Налаштування» (Основные параметры)

• Статус: переведите в положение «Включено».

• Джерело курсів валют: выберите нужный банк (НБУ, Монобанк или ПриватБанк). Интерфейс динамически покажет необходимые для выбранного банка параметры.

• Тип курсу: (для Монобанка и ПриватБанка) укажите «Курс продажу», «Курс купівлі» или «Середній».

• Курс ПриватБанку: (для ПриватБанка) выберите «Відділення (готівковий)» или «Картки / безготівковий».

• Корекція курсу (%): при необходимости укажите процент изменения (например, 1.5 прибавит 1.5% к полученному курсу, 0 — курс банка без изменений).

• Оновлювати валюти: отметьте галочками валюты, курсы которых должны перезаписываться в базе данных магазина.

• Логування (Debug): включите для детального протоколирования всех операций.

• После изменения настроек нажмите синюю кнопку «Сохранить» вверху справа.

Ручное обновление курсов в один клик

В правом верхнем углу панели модуля нажмите желтую кнопку «Оновити курси зараз»:

• Модуль выполнит безопасный AJAX-запрос к выбранному банку.

• Выведется уведомление со списком обновленных курсов.

• Значения в таблице валют на экране обновятся мгновенно без перезагрузки страницы.

• Примечание: на штатной странице Система → Локализация → Валюты стандартная кнопка «Обновить» также автоматически синхронизирует курсы через этот модуль.

Вкладка 2: «CRON планувальник» (Автоматизация)

Чтобы курсы обновлялись в фоновом режиме без участия человека:

1. Во вкладке отображается персональный защитный URL и готовая команда для сервера.

2. При необходимости смените ключ безопасности кнопкой «Сгенерировать новый» и сохраните настройки.

3. В панели управления хостингом (cPanel, ISPmanager, FastPanel и т.д.) перейдите в раздел Планировщик задач (CRON) и добавьте выполнение команды:

   Bash

    

   0 6 * * * wget -q -O - "https://ваш-домен.com/index.php?route=extension/currency/bank_ua/cron&key=ВАШ_КЛЮЧ" > /dev/null 2>&1
   

   (Данное расписание запускает обновление каждый день в 06:00 утра).

Вкладка 3: «Журнал (Лог)»

• Отображает историю каждого запуска: точное время, выбранный банк, полученные котировки и статус очистки системного кэша валют.

• Кнопка «Очистить лог» очищает историю записей при необходимости.