# Терминдер сөздігі

> Қолдауға келетін сұрақтардың бір бөлігі — терминді түсінбегеннен. Мұнда 25 термин қарапайым тілмен, әрқайсысына бір-екі сөйлем және мысал.

## Қысқаша

Бұл бет — анықтама. Құжаттамада немесе кабинетте таныс емес сөз кездессе, осы жерден іздеңіз. Терминдер топталған: алдымен негізгі ұғымдар, сосын счёт түрлері, техникалық терминдер, ақша мен есеп, соңында тариф терминдері.

## Негізгі ұғымдар

**Кассир** — Kaspi Pay-дегі шектеулі құқығы бар рөл: счёт шығару, күйін көру, өз счёттары бойынша қайтару жасау. Біз сол рөл арқылы жұмыс істейміз. Мысалы: Kaspi Pay қосымшасында Настройки → Сотрудники → Добавить сотрудника, рөлі «Кассир».

**Байланыс (подключение)** — кассир нөмірінің біздің сервиспен байланыстырылған күйі. Кабинеттің **Kaspi** бөлімінде әр байланыс жеке карточка болып тұрады. Байланыс үзілсе, счёт жасау тоқтайды.

**API кілт** — сіздің бағдарламаңыз бізге «мен пәленше ұйымның атынан келдім» деп айтатын құпия жол. `X-API-Key` тақырыбымен жіберіледі. Мысалы: `qp_live_…` немесе `qp_test_…`. Кілт **тек серверде** тұруы керек, браузерге де, мобильді қосымшаға да салуға болмайды.

**Scope (құқық)** — кілттің нені істей алатыны. Алтауы бар: `invoices:read`, `invoices:write`, `refunds:write`, `subscriptions:manage`, `webhooks:manage`, `partner:manage`. Мысалы: есеп жинайтын кілтке тек `invoices:read` беріңіз, сонда ол счёт жасай да, қайтара да алмайды.

**Sandbox (тест режимі)** — бәрі нақтысындай, бірақ Kaspi шақырылмайды және ақша жүрмейді. Кілті `qp_test_…`. Мысалы: интеграцияны sandbox-та жинап, төлемді өзіңіз имитациялап тексересіз.

**Live (нақты режим)** — нақты Kaspi QR, нақты ақша. Кілті `qp_live_…`. Кабинеттің жоғарғы жағында қай режимде екеніңіз жазулы тұрады.

## Счёт және оның түрлері

**Счёт (invoice)** — клиенттен белгілі бір соманы сұрайтын жазба. Оның идентификаторы, сомасы, күйі, төлем беті болады. Күйлері: `new` → `pending` → `paid` / `cancelled` / `expired`.

**QR счёт** — клиент QR-ды сканерлеп немесе сілтемені ашып төлейтін счёт. Әдепкі түрі. Сипаттамасы 100 таңбаға дейін. Мысалы: кассадағы экранда QR көрсетесіз.

**Телефонға счёт** — клиенттің Kaspi қосымшасына тікелей келетін счёт, оған клиент нөмірі керек (`7XXXXXXXXXX`). Сипаттамасы 60 таңбаға дейін, сомасы бүтін теңге. Мысалы: телефон арқылы тапсырыс қабылдап, счётты бірден жібересіз.

**Төлем сілтемесі** — қайта-қайта қолдануға болатын тұрақты сілтеме, `qut.kz/p/<slug>` түрінде. Клиент ашқан сайын жаңа счёт жасалады. Мысалы: Instagram профиліне қоясыз немесе QR-ын басып шығарып кассаға жапсырасыз.

**Ашық сома** — сілтемеде сома бекітілмеген, клиент өзі енгізеді. Мин және макс шектеу қоюға болады. Мысалы: «Шығармашылық қолдау» немесе алдын ала сомасы белгісіз қызмет.

## Техникалық терминдер

**Webhook** — төлем күйі өзгергенде біз сіздің серверіңізге жіберетін хабар. Сіз адресті кабинеттің **Интеграциялар** бөлімінде қоясыз. Мысалы: `invoice.paid` келді — тапсырысты «төленді» деп белгілейсіз.

**Webhook құпиясы (secret)** — хабардың шынымен бізден келгенін тексеретін кілт. Бір рет қана көрсетіледі. Қолтаңба `HMAC-SHA256(secret, timestamp + "." + rawBody)` түрінде есептеледі; денені **өзгертілмеген байт күйінде**, JSON-ға айналдырғанға дейін тексеру керек.

**Идемпоттылық** — бір әрекеттің екі рет орындалып кетпеуі. Счёт жасағанда `Idempotency-Key` тақырыбын қойсаңыз, сол кілтпен қайталанған сұрау жаңа счёт жасамайды, бұрынғысын қайтарады. Мысалы: интернет байланыс үзіліп, сұрау қайталанды — клиентке екі счёт кетпейді.

**externalOrderId** — сіздің өз тапсырыс нөміріңіз. Счётқа жазып қойсаңыз, webhook-та қайта келеді және кабинеттен іздеуге жарайды. Мысалы: `"externalOrderId": "1001"`.

**metadata** — счётқа тіркейтін кез келген қосымша JSON. Бізге мағынасыз, сізге керек. Мысалы: `{"table": "12", "waiter": "Асан"}`.

**Poller** — счёттардың төленген-төленбегенін Kaspi-ден сұрап тұратын біздің механизм. Әр 3 секунд сайын жүреді, жас счёттар жиі тексеріледі. Іс жүзінде клиент төлегеннен кейін webhook әдетте 5 секунд ішінде келеді.

## Ақша, қайтару, чек

**Қайтару (refund)** — төленген счёт бойынша ақшаны клиентке қайтару. `POST /api/v1/invoices/{id}/refund`, кабинетте **Қайтару** батырмасы.

**Ішінара қайтару** — соманың бір бөлігін ғана қайтару. Счёт `partially_refunded` күйіне өтеді. Мысалы: 10 000 ₸ тапсырыстың бір позициясы жоқ болып шықты, 2 500 ₸ қайтарасыз.

**Чек** — біздің төлем бетіміздегі чек, клиент оны сілтемеден көреді. Есеп жүргізуге ыңғайлы, бірақ фискалды құжат емес.

**Фискалды чек** — салық талабына сай құжат. Kaspi Касса қосулы болса, қашықтан төлемге чекті Kaspi өзі шығарып, клиентке жібереді. Чек беру міндеті сатушыда: біз ақшаны ұстамаймыз, сондықтан сіздің атыңыздан чек бере алмаймыз.

**Кеш төлем** — жабылған (`cancelled` немесе `expired`) счётқа ақшаның кешігіп келуі. Бұл жағдайда `invoice.paid` оқиғасы `late: true` белгісімен кейін де келуі мүмкін. Қызметті беру керек немесе ақшаны қайтару керек.

## Жазылым және тариф

**Жазылым (subscription)** — счётты кестеге сай өздігінен шығару: күн, апта немесе ай аралығымен. Ақша клиенттің шотынан өздігінен алынбайды — жазылым тек счёт шығарады, төлемді клиент әр жолы өзі растайды. Мысалы: спортзал абонементі, ай сайын счёт.

**Тариф** — біздің қызметіміздің айлық ақысы: Бастау 4 990 ₸, Бизнес 14 900 ₸, Про 39 900 ₸. Транзакциядан пайыз алмаймыз.

**Айлық лимит** — тарифке кіретін счёт саны (мысалы, Бизнесте айына 4 000). Күнтізбелік ай бойынша, Алматы уақытымен есептеледі. Тірелсеңіз API `tariff_limit_reached` қатесін береді.

**Тәуліктік қорғаныс** — бір тәулікте жасалатын счёттың шегі (Бастауда 200, Бизнесте 1 500, Про тарифінде 5 000). Бұл бизнес лимиті емес, циклге түскен интеграциядан қорғаныс. Қатесі — `tariff_daily_burst`, айлық лимиттің қатесімен шатастырмаңыз.

## Жиі қойылатын сұрақтар

**Sandbox пен тест режимі — бір нәрсе ме?** Иә, бір нәрсенің екі атауы.

**Кассир мен қызметкер бір ме?** Жоқ. Кассир — Kaspi Pay-дегі рөл. Қызметкер — біздің кабинетке шақырылған адам, ол өз нөмірімен кіреді.

**Идемпоттылық қайда керек?** Счёт жасауда (қосарланған счёт болмауы үшін) және webhook өңдеуде (бір оқиға екі рет келсе, тапсырысты екі рет жөнелтіп жібермеу үшін).

**Термин мұнда жоқ болса?** Қолдауға жазыңыз: WhatsApp +7 778 881 3333, Telegram @qutpaybot. Жиі сұралатынын осы бетке қосамыз.