# Kaspi POS Automation

Kaspi Pay API арқылы POS-жүйелер үшін төлемдерді автоматтандыру. Жоба шот-фактуралар жасау, QR-кодтар генерациялау, транзакциялар тарихын қарау және қайтаруларды рәсімдеу үшін серверлік қосымша мен веб-интерфейс ұсынады.

## Сәулет

```
┌──────────────┐       ┌──────────────────┐       ┌──────────────────┐
│  Web UI      │◄─────►│  Express Server   │◄─────►│  Kaspi Pay API   │
│  (public/)   │       │  (server.js)      │       │  (entrance/      │
│              │       │                   │       │   mtoken/qrpay)  │
└──────────────┘       └──────────────────┘       └──────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   src/            │
                    │  ├─ config.js     │  Кілт жұбы, құрылғы, тұрақтылар
                    │  ├─ crypto.js     │  ECDH, ECDSA, TOTP, AES
                    │  ├─ helpers.js    │  Fetch орауышы, тақырыптар
                    │  ├─ session.js    │  Stateless сессия фабрикасы
                    │  ├─ logger.js     │  Файл және консоль логтары
                    │  ├─ polling.js    │  Төлем статусын сұрау
                    │  ├─ webhookStore  │  Вебхук басқару
                    │  └─ routes/       │  API маршрут өңдеушілері
                    │     ├─ auth.js    │  SMS авторизация (3 қадам)
                    │     ├─ invoice.js │  Шот-фактура жасау
                    │     ├─ qr.js      │  QR-код генерациялау
                    │     ├─ history.js │  Транзакциялар тарихы
                    │     ├─ refund.js  │  Қайтару өңдеу
                    │     └─ session.js │  Сессия басқару
                    └───────────────────┘
```

Сервер **авторизациядан кейін stateless** — сессия деректері (шифрланған `vtokenSecret`, `tokenSN`, `profileId`) клиент жағында сақталады және тақырыптар арқылы жіберіледі.

### Webhooks

Сервер жасалған QR және invoice төлемдерінің статустарын автоматты түрде бақылайды (әр 3 секунд сайын polling) және статус өзгерген кезде көрсетілген URL-дарға HTTP POST хабарламаларын жібереді.

- 📡 **Оқиғалар:** `payment.success` · `payment.failed` · `payment.expired`
- ⚙️ **Баптау:** `webhooks.json` файлы ([`webhooks.example.json`](./webhooks.example.json) қараңыз)
- 🔐 **Қолтаңба:** HMAC SHA-256
- 🔄 **Retry:** өсетін кідіріспен 3 әрекетке дейін

> 📖 Толығырақ — [API құжаттамасында](./docs/API.kk.md#webhooks--хабарламалар).

## Талаптар

- Node.js ≥ 20.6

## Жылдам бастау

```bash
# 1. Репозиторийді клондау
git clone https://github.com/tapter-dev/kaspi-pos-automation.git
cd kaspi-pos-automation

# 2. Тәуелділіктерді орнату
npm install

# 3. Шифрлау кілтімен .env жасау
echo "TOKEN_SECRET_KEY=$(openssl rand -hex 32)" > .env

# 4. (Қосымша) Вебхуктарды баптау
cp webhooks.example.json webhooks.json
# webhooks.json файлын өз қажеттіліктеріңізге сай өңдеңіз

# 5. Серверді іске қосу
npm start
```

Бірінші іске қосу кезінде `keypair.json` және `device.json` автоматты түрде генерацияланады.

## Орта айнымалылары

| Айнымалы            | Сипаттама                                | Әдепкі мән                 | Міндетті |
| ------------------- | ---------------------------------------- | -------------------------- | -------- |
| `TOKEN_SECRET_KEY`  | AES-256-GCM үшін 64 символды hex-жол    | —                          | Иә       |
| `PORT`              | Сервер порты                             | `3000`                     | Жоқ      |
| `APP_VERSION`       | Kaspi Pay қосымша нұсқасы                | `4.110.1`                  | Жоқ      |
| `APP_BUILD`         | Құрастыру нөмірі                         | `1099`                     | Жоқ      |
| `APP_PLATFORM`      | Құрылғы платформасы                      | `iOS`                      | Жоқ      |
| `APP_PLATFORM_VER`  | ОЖ нұсқасы                               | `18.5`                     | Жоқ      |
| `APP_LOCALE`        | Тіл                                      | `ru-RU`                    | Жоқ      |
| `APP_MODEL`         | Құрылғы моделі                           | `iPhone17,3`               | Жоқ      |
| `APP_BRAND`         | Құрылғы бренді                           | `Apple`                    | Жоқ      |
| `APP_DEVICE_NAME`   | Құрылғы атауы                            | `iPhone`                   | Жоқ      |
| `APP_SCREEN_W`      | Экран ені                                | `393.0`                    | Жоқ      |
| `APP_SCREEN_H`      | Экран биіктігі                           | `852.0`                    | Жоқ      |
| `APP_CFNETWORK`     | CFNetwork нұсқасы                        | `CFNetwork/3826.500.131`   | Жоқ      |
| `APP_DARWIN`        | Darwin нұсқасы                           | `Darwin/24.5.0`            | Жоқ      |

> ⚠️ `APP_*` параметрлері нақты Kaspi Pay клиентіне сәйкес келеді. Kaspi API бұл мәндерді тексереді және белгісіз параметрлері бар сұрауларды қабылдамауы мүмкін.

## Кілттерді ротациялау

```bash
npm run regen:keypair   # ECDSA-кілттерді қайта генерациялау
npm run regen:device    # Құрылғы идентификаторын қайта генерациялау
```

Ескі файлдар `.bak` ретінде сақталады. Ротациядан кейін бар сессиялар жарамсыз болады.

## Демо-интерфейс (`public/`)

`public/` қалтасында серверімен бірге автоматты түрде іске қосылатын және `http://localhost:3000` мекенжайы бойынша қолжетімді кірістірілген веб-интерфейс (SPA) орналасқан.

**Интерфейс мүмкіндіктері:**

- 🔐 **Авторизация** — Kaspi Pay кассирінің телефон нөмірі арқылы 3 қадамды SMS-flow арқылы кіру (нөмірді енгізу → OTP-код → аяқтау)
- 🧾 **Шот жасау** — клиенттің телефон нөмірі бойынша сома мен түсініктемені көрсете отырып шот жасау
- 📱 **QR-төлем** — нақты уақытта статусты бақылаумен төлем үшін QR-код генерациялау
- 📋 **Операциялар тарихы** — транзакциялар тізімін толық мәліметтерімен қарау
- 💰 **Сатылымдар мен қайтарулар** — сатылым статистикасы және қайтаруларды рәсімдеу

**Файлдар:**

| Файл | Сипаттама |
| --- | --- |
| `public/index.html` | HTML-белгілеу және интерфейс стильдері |
| `public/app.js` | Клиенттік логика (API-шақырулар, күй басқару) |

> Интерфейс API-ді көрсету және тестілеу үшін арналған. Продакшн үшін өз фронтендіңізді пайдалану ұсынылады.

## API құжаттамасы

Барлық API эндпоинттері бойынша толық құжаттама: [`docs/API.kk.md`](./docs/API.kk.md).

## Әзірлеу

```bash
# Линтинг
npm run lint

# Форматтау
npm run format

# Тесттер
npm test
```

## Лицензия

Бұл жоба [MIT](./LICENSE) лицензиясымен таратылады.

## Жобаға қатысу

Біз қоғамдастықтың үлесін қуана қабылдаймыз! Pull request жасамас бұрын [CONTRIBUTING.md](./CONTRIBUTING.md) құжатымен танысыңыз.