1. Cel i ogólny opis
Konieczne jest opracowanie modułu (rozszerzenia) dla OpenCart, który integruje program lojalnościowy myBot.in.ua bezpośrednio na stronie realizacji zamówienia (Checkout). Moduł powinien umożliwiać klientom przeglądanie swojego salda bonusowego oraz stosowanie bonusów jako zniżki przy realizacji zamówienia.
1.1. Scenariusz działania
Scenariusz A — klient zarejestrowany w programie lojalnościowym:
- Klient wchodzi na stronę realizacji zamówienia.
- Wprowadza numer telefonu w standardowym polu formularza.
- System wykonuje zapytanie do API myBot — otrzymuje dane o kliencie i jego saldzie bonusowym.
- Wyświetlany jest blok z saldem bonusów oraz pole do wprowadzenia kwoty do odliczenia.
- Klient wprowadza pożądaną kwotę zniżki (lub pozostawia maksymalnie dostępną) i naciska „Przelicz”.
- System przelicza sumę zamówienia z uwzględnieniem zniżki.
- Przy potwierdzeniu zamówienia — system odlicza bonusy przez API.
Scenariusz B — klient NIE zarejestrowany w programie lojalnościowym:
- Klient wprowadza numer telefonu.
- API zwraca odpowiedź, że klient nie został znaleziony.
- System wyświetla blok z zaproszeniem do dołączenia do programu lojalnościowego przez bota Telegram.
2. Wymagania techniczne dotyczące API
2.1. Połączenie z API
Parametr | Wartość |
Produkcja URL | https://mybot.in.ua/pos-api/v1 |
Rozwój URL | https://dev.mybot.in.ua/pos-api/v1 |
Dokumentacja | https://mybot.in.ua/pos-api/v1/doc |
Autoryzacja | Bearer Token w nagłówku Authorization |
Format czasu | UTC (GMT+0) |
2.2. Autoryzacja (uzyskanie tokena)
- Metoda: POST /auth
- Okres ważności tokena: 12 godzin
- Wdrożyć jedną funkcję-opakowanie dla wszystkich zapytań API (z wyjątkiem /auth) z blokiem try/catch do automatycznego odnawiania tokena po upływie terminu ważności.
- Token przechowywać w bezpiecznym miejscu (np. w konfiguracji modułu lub pamięci podręcznej OpenCart). Nie przechowywać w cookies ani lokalnej pamięci przeglądarki.
2.3. Uzyskanie salda klienta
- Metoda: GET /account
- Parametr: numer telefonu klienta w formacie 380 (bez +, spacji, nawiasów)
- Jeśli klient nie zostanie znaleziony — API zwróci odpowiedni błąd. Należy obsłużyć ten przypadek (Scenariusz B).
2.4. Obliczenie paragonu
- Metoda: POST /receipt
- Zwraca wstępne obliczenie BEZ zapisu danych
Parametry zapytania:
Parametr | Typ | Opis |
phone | string | Telefon w formacie 380 |
bonuses_amount | — | NIE przekazywać w pierwszym zapytaniu |
discount_amount | — | NIE przekazywać w pierwszym zapytaniu |
body | array | Tablica produktów zamówienia (JSON) |
Struktura obiektu produktu w tablicy body:
{ "name": "Nazwa produktu",
"barcode": "Kod produktu",
"amount": 2, // ilość
"cost": 500 // cena za sztukę }
Ważne pola w odpowiedzi:
- data.totals.total_discount — maksymalnie dostępna zniżka w programie lojalnościowym. Wyświetlać w polu wprowadzenia „Obliczenie bonusami” jako wartość domyślną.
- data.totals.discounted_cost — ostateczna cena zamówienia ze zniżką.
- data.totals.bonuses_accrued — ile bonusów zostanie naliczonych za to zamówienie.