1. Цель и общее описание
Необходимо разработать модуль (расширение) для OpenCart, который интегрирует программу лояльности myBot.in.ua непосредственно на странице оформления заказа (Checkout). Модуль должен позволять клиентам просматривать свой бонусный баланс и применять бонусы как скидку при оформлении заказа.
1.1. Сценарий работы
Сценарий A — клиент зарегистрирован в программе лояльности:
- Клиент заходит на страницу оформления заказа.
- Вводит номер телефона в стандартное поле формы.
- Система выполняет запрос к API myBot — получает данные о клиенте и его бонусном балансе.
- Отображается блок с балансом бонусов и полем для ввода суммы к списанию.
- Клиент вводит желаемую сумму скидки (или оставляет максимально доступную) и нажимает «Перерасчитать».
- Система перерасчитывает итог заказа с учетом скидки.
- При подтверждении заказа — система списывает бонусы через API.
Сценарий B — клиент НЕ зарегистрирован в программе лояльности:
- Клиент вводит номер телефона.
- API возвращает ответ, что клиент не найден.
- Система отображает блок с приглашением присоединиться к программе лояльности через Telegram-бот.
2. Технические требования к API
2.1. Подключение к API
Параметр | Значение |
Production URL | https://mybot.in.ua/pos-api/v1 |
Development URL | https://dev.mybot.in.ua/pos-api/v1 |
Документация | https://mybot.in.ua/pos-api/v1/doc |
Авторизация | Bearer Token в заголовке Authorization |
Формат времени | UTC (GMT+0) |
2.2. Авторизация (получение токена)
- Метод: POST /auth
- Срок действия токена: 12 часов
- Реализовать единую функцию-обертку для всех API-запросов (кроме /auth) с блоком try/catch для автоматического обновления токена при истечении срока действия.
- Токен хранить в защищенном месте (например, в конфигурации модуля или кэше OpenCart). Не хранить в cookies или локальном хранилище браузера.
2.3. Получение баланса клиента
- Метод: GET /account
- Параметр: номер телефона клиента в формате 380 (без +, пробелов, скобок)
- Если клиент не найден — API вернет соответствующую ошибку. Необходимо обработать этот случай (Сценарий B).
2.4. Расчет чека
- Метод: POST /receipt
- Возвращает предварительный расчет БЕЗ записи данных
Параметры запроса:
Параметр | Тип | Описание |
phone | string | Телефон в формате 380 |
bonuses_amount | — | НЕ передавать в первом запросе |
discount_amount | — | НЕ передавать в первом запросе |
body | array | Массив товаров заказа (JSON) |
Структура объекта товара в массиве body:
{ "name": "Наименование товара",
"barcode": "Артикул товара",
"amount": 2, // количество
"cost": 500 // стоимость за единицу }
Важные поля в ответе:
- data.totals.total_discount — максимально доступная скидка по программе лояльности. Отображать в поле ввода «Расчет бонусами» как значение по умолчанию.
- data.totals.discounted_cost — финальная стоимость заказа со скидкой.
- data.totals.bonuses_accrued — сколько бонусов будет начислено за этот заказ.