POS System Integration Guide

Overview

This guide explains the full flow and API structure for integrating AOS cashback functionality with third-party POS systems at store branches. It outlines authentication, QR scanning, transaction posting, and bonus calculation.

🔁 Integration Flow

Below is the step-by-step process of POS integration with AOS:

1. Store Registration

Each store is added to the AOS system, and a unique token is issued for every branch.

2. Token Usage

Tokens are included in all relevant API requests to authenticate each transaction.

3. Customer Login Requirement

Customers must have the AOS mobile app installed and be logged in.

4. QR Code Scanning at Checkout

The cashier scans the customer's QR code using the POS terminal.

5. Customer Data Fetching

QR code data is sent via API, and the customer profile is returned and displayed at the POS.

6. Receipt Entry

The cashier enters product and payment data into the system.

7. Bonus Usage (Optional)

If the customer wants to use bonus (cashback), a modal input should allow setting the amount to deduct.

8. Transaction Submission

Once finalized, all transaction data is sent to the AOS server.

9. Response Handling

If a success response is returned, the receipt is closed and printed.

10. Customer Update

Bonus is credited or debited from the customer account, and the app updates accordingly.

🖲️ POS System Requirements

The POS software must support the following components for successful integration:

QR Scan Button + Modal

A dedicated button to scan the AOS QR code and a modal window (or input field) to enter/scan the code.

Customer Info Display

Once the QR code is scanned, show customer name and current cashback balance on the screen.

Bonus Usage Interface

Provide a separate button and modal window where the cashier can enter how much cashback the customer wants to use.

Updated Receipt Logic

If cashback is used, subtract it from the total and clearly show the discounted amount on printed receipts.

📡 API Endpoints

1. Get Customer Profile by QR Code

http GET https://dev-api.aos-shop.uz/store/customers/profile

Query parameters:

This endpoint fetches the customer data based on the scanned QR code and validates it against the given store token.

2. Submit Transaction Data

http POST https://dev-api.aos-shop.uz/transactions

Body structure:

{
  "rTime": "string",
  "rDate": "string",
  "filial": "string",
  "client": "string",
  "cEmployee": "string",
  "rNumber": "string",
  "rTotal": 0,
  "bonus": 0,
  "items": [
    {
      "discount": 0,
      "price": 0,
      "barcode": "string",
      "amount": 0,
      "vatPercent": 0,
      "vat": 0,
      "name": "string",
      "classCode": "string",
      "other": 0,
      "commissionTIN": "string"
    }
  ],
  "payments": [
    {
      "item": "Наличные",
      "total": 150000.2
    }
  ],
  "cardType": "static",
  "percent": 0
}

Notes:

• bonus: The amount of cashback used by the customer (if any).
• rTotal: Total receipt amount before applying cashback.
• payments: Can include cash, card, or other methods.

✅ Final Notes

• Ensure accurate VAT and commission fields for fiscal compliance.
• API response must be handled gracefully with validation on the POS side.
• Customer-facing feedback (e.g., bonus earned) must be shown in real-time for transparency.

For technical support or questions, please contact the AOS development team.