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 қараңыз)
🔐 Қолтаңба: HMAC SHA-256
🔄 Retry: өсетін кідіріспен 3 әрекетке дейін

📖 Толығырақ — API құжаттамасында.

Талаптар

Node.js ≥ 20.6

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

# 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 бұл мәндерді тексереді және белгісіз параметрлері бар сұрауларды қабылдамауы мүмкін.

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

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.

Әзірлеу

# Линтинг
npm run lint

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

# Тесттер
npm test

Лицензия

Бұл жоба MIT лицензиясымен таратылады.

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

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

9.2 KiB Raw Blame History Unescape Escape