148 lines
9.2 KiB
Markdown
148 lines
9.2 KiB
Markdown
# 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) құжатымен танысыңыз.
|