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 — скільки бонусів буде нараховано за це замовлення.
