1. Goal and General Description
A module (extension) for OpenCart needs to be developed that integrates the loyalty program myBot.in.ua directly on the checkout page. The module should allow customers to view their bonus balance and apply bonuses as a discount during checkout.
1.1. Operation Scenario
Scenario A — the customer is registered in the loyalty program:
- The customer goes to the checkout page.
- Enters their phone number in the standard form field.
- The system makes a request to the myBot API — retrieves data about the customer and their bonus balance.
- A block with the bonus balance and a field for entering the amount to be deducted is displayed.
- The customer enters the desired discount amount (or leaves the maximum available) and clicks "Recalculate".
- The system recalculates the order total considering the discount.
- Upon order confirmation — the system deducts bonuses via the API.
Scenario B — the customer is NOT registered in the loyalty program:
- The customer enters their phone number.
- The API returns a response that the customer is not found.
- The system displays a block inviting them to join the loyalty program via the Telegram bot.
2. Technical Requirements for the API
2.1. API Connection
Parameter | Value |
Production URL | https://mybot.in.ua/pos-api/v1 |
Development URL | https://dev.mybot.in.ua/pos-api/v1 |
Documentation | https://mybot.in.ua/pos-api/v1/doc |
Authorization | Bearer Token in the Authorization header |
Time Format | UTC (GMT+0) |
2.2. Authorization (token retrieval)
- Method: POST /auth
- Token validity: 12 hours
- Implement a single wrapper function for all API requests (except /auth) with a try/catch block for automatic token renewal upon expiration.
- Store the token securely (e.g., in the module configuration or OpenCart cache). Do not store in cookies or local browser storage.
2.3. Retrieving Customer Balance
- Method: GET /account
- Parameter: customer phone number in format 380 (without +, spaces, parentheses)
- If the customer is not found — the API will return the corresponding error. This case must be handled (Scenario B).
2.4. Receipt Calculation
- Method: POST /receipt
- Returns a preliminary calculation WITHOUT recording data
Request Parameters:
Parameter | Type | Description |
phone | string | Phone in format 380 |
bonuses_amount | — | DO NOT send in the first request |
discount_amount | — | DO NOT send in the first request |
body | array | Array of order items (JSON) |
Structure of the product object in the body array:
{ "name": "Product Name",
"barcode": "Product Code",
"amount": 2, // quantity
"cost": 500 // price per unit }
Important fields in the response:
- data.totals.total_discount — the maximum available discount from the loyalty program. Display in the "Calculate with Bonuses" input field as the default value.
- data.totals.discounted_cost — the final cost of the order with the discount.
- data.totals.bonuses_accrued — how many bonuses will be accrued for this order.