# Продакшенге шығу чек-парағы

> Нақты режимге көшер алдында өтетін он екі тармақ: кассир, live кілт, webhook, қолтаңба, идемпоттылық, кеш төлем, қате өңдеу, журнал, тариф пен лимит, Telegram ескертуі, қайтару реті, бірінші нақты төлем.

## Қысқаша

Төмендегі он екі тармақты ретімен өтіңіз. Әрқайсысының қасында **не басу керек** және **қалай тексеру керек** жазылған. Бәрі жасыл болса, нақты режимге қауіпсіз көшесіз.

Ең жиі кездесетін екі қате: кілт `qp_test_…` күйінде қалып қою және webhook адресінің live үшін қосылмауы. Тізімнің 2 және 3-тармағы дәл соған арналған.

## 1. Кассир белсенді

**Не басу керек:** Кабинет → **Kaspi** бөлімі. Байланыстың күйі «белсенді» болуы керек.

**Қалай тексеру керек:** күйі сұр немесе «үзілген» болса, қайта байланыстырыңыз — SMS коды кассир нөміріне келеді, бүкіл процесс бір терезеде, шамамен он минут.

Есте сақтаңыз: Kaspi бір кассирге бір ғана белсенді құрылғыға рұқсат береді. Байланыстырған соң ол нөмірмен Kaspi Pay қосымшасына кірмеңіз — сессия үзіледі.

Мәселе болса: [Кассир байланысы үзілді](/kb/connection-lost), [Кассир қосылмай жатыр](/kb/cashier-not-connecting).

## 2. Кілт live

**Не басу керек:** Кабинет → **Интеграциялар** → API кілттер. `qp_live_…` кілтін жасаңыз және оны серверде `.env` файлында ауыстырыңыз.

**Қалай тексеру керек:** серверде `echo` немесе журнал арқылы кілттің **алғашқы жеті таңбасын** қараңыз: `qp_live_` болуы керек, `qp_test_` емес.

Бұл ең жиі ұмытылатын қадам. Кілт test күйінде қалса, счёттар жасалады, бірақ клиентке нақты төлем келмейді. Белгілері: [Тест режимі қосулы қалып қойған](/kb/test-mode-forgotten).

## 3. Webhook жария және https

**Не басу керек:** Кабинет → **Интеграциялар** → webhook адресі. Адрес тұрақты доменде және `https` болуы керек.

**Қалай тексеру керек:** сыртқы желіден (телефонның мобильді интернетінен, Wi-Fi-дан емес) адресіңізге `POST` жіберіп көріңіз. Жауап келуі керек. Егер:

- IP-мекенжай жазсаңыз — `webhook_url_requires_domain`
- `http://` жазсаңыз — `webhook_url_requires_https`
- Туннель адресі болса — `webhook_url_tunnel_forbidden`

Адрес **авторизациясыз ашық** болуы керек: Basic Auth, IP-сүзгі немесе Cloudflare-дің «бот қорғанысы» webhook-ты бөгейді. Қайта бағыттау да ұсталмайды (тек сол адрестің өзіне 307/308 болмаса).

Мәселе болса: [Webhook келмей жатыр](/kb/webhook-not-arriving).

## 4. Қолтаңба тексеріліп жатыр

**Не істеу керек:** кодыңызда `X-Webhook-Signature` тексерілетініне көз жеткізіңіз: `sha256=` + `HMAC-SHA256(secret, timestamp + "." + rawBody)`.

**Қалай тексеру керек:** әдейі бұзылған қолтаңбамен өз адресіңізге сұрау жіберіңіз. Сервер **401 қайтарып, тапсырысты өзгертпеуі керек**. Егер бұзылған қолтаңбамен де тапсырыс «төленді» болып кетсе — тексеру жоқ немесе жұмыс істемей тұр.

Қосымша: `X-Webhook-Timestamp` 5 минуттан ескі болса қабылдамау керек. Толығы: [Webhook қауіпсіздігі](/kb/webhook-security).

## 5. Идемпоттылық бар

**Не істеу керек:** екі жерде.

1. **Счёт жасағанда** — `Idempotency-Key` тақырыбын жіберіңіз. Желі үзіліп, сұрау қайталанса, жаңа счёт жасалмайды
2. **Webhook өңдегенде** — `(invoice.id, status)` жұбы бойынша. Сол жұп екінші рет келсе, тапсырысты қайта өңдемеңіз

**Қалай тексеру керек:** sandbox-та бір `Idempotency-Key` мәнімен екі рет счёт жасаңыз — екіншісінде HTTP 200 және `idempotentReplay: true` келуі керек. Webhook үшін: бір денені екі рет өз адресіңізге жіберіңіз, екіншісінде тауар екінші рет жөнелтілмеуі керек.

Толығы: [Идемпоттылық](/kb/idempotency).

## 6. Кеш төлемге дайын

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

**Қалай тексеру керек:** sandbox-та счётты `cancel` қылып, сосын `simulate {"status":"paid"}` жіберіңіз. `late: true` келеді. Жүйеңіз не істейді?

Екі жол бар, алдын ала таңдаңыз: қызметті беру немесе ақшаны қайтару. Үшінші жол — қолмен қарау үшін хабарлама жіберу. Толығы: [Кеш келген төлем](/kb/late-payment).

## 7. Қате өңдеу бар

**Не істеу керек:** интеграцияны `message` мәтініне емес, `error` кодына қарап жазыңыз. Кемінде мына кодтар өңделсін:

| Код | Не істеу керек |
|---|---|
| `kaspi_session_expired` | Қолдау қызметіне ескерту жіберу, счёт жасауды тоқтату |
| `tariff_limit_reached` | Ескерту жіберу, тарифті көтеру |
| `tariff_daily_burst` | Кодта цикл бар ма, тексеру |
| `rate_limited`, `429` | `Retry-After` тақырыбын қарап, күтіп қайталау |
| `502`, `503` | Өсіп отыратын кідіріспен қайталау (1, 2, 4, 8 секунд) |
| `refund_unknown` | **Қайталамау**, счёт күйін оқу |

**Қалай тексеру керек:** sandbox-та әдейі бұзылған сұраулар жіберіп көріңіз. Барлық кодтар: [Қателер каталогы](/kb/error-catalog).

## 8. Журнал жүргізіледі

**Не істеу керек:** әр счёт жасауды және әр келген webhook-ты жазыңыз: уақыты, `invoice.id`, `externalOrderId`, күйі, HTTP коды, `X-Webhook-Delivery`.

**Журналға жазбаңыз:** API кілттің өзін, webhook құпиясын.

**Қалай тексеру керек:** сынақ төлемін жасап, журналда қалғанын қараңыз. Журналсыз бірінші мәселені шеше алмайсыз.

## 9. Тариф белсенді және лимит жетеді

**Не басу керек:** Кабинет → **Тариф**. Тариф белсенді ме, айлық лимит айына жоспарланған счёт санына жете ме?

| Тариф | Айына счёт | Тәуліктік қорғаныс |
|---|---|---|
| Бастау | 800 | 200 |
| Бизнес | 4 000 | 1 500 |
| Про | 15 000 | 5 000 |

**Тәуліктік сан — бизнес лимиті емес**, циклге түскен интеграциядан қорғаныс. Егер тәулігіне 200-ден көп счёт жоспарласаңыз, тарифті сәйкесінше таңдаңыз.

Сынақ мерзімі 7 күн, тәулігіне 50 счёт және **бірінші нақты счёттан** басталады. Толығы: [Тарифтер және лимиттер](/kb/tariff-limits).

## 10. Telegram ескертуі қосулы

**Не басу керек:** Кабинет → **Баптау** → Telegram байланыстыру коды. Ботты байланыстырыңыз.

**Неге керек:** кассир байланысы үзілгенін журналдан емес, хабарламадан бірден білесіз. Түнде байланыс үзілсе, таңертең емес, сол сәтте көресіз.

Қосу реті: [Telegram ботын қосу](/kb/telegram-connect).

## 11. Қайтару реті ойластырылған

**Не істеу керек:** мына сұрақтарға жауабыңыз болсын.

- Қайтаруды кім жасайды: кабинеттен қолмен бе, әлде сіздің жүйеңіз API арқылы ма?
- Ішінара қайтару керек пе?
- `refund_unknown` немесе `refund_pending_unknown` келсе не істейсіз? (Жауабы: қайталамайсыз, счёт күйін оқисыз)

**Қалай тексеру керек:** sandbox-та толық және ішінара қайтаруды өткізіңіз. Толығы: [Қайтару API](/kb/refunds-api), [Екі рет қайтарып жіберуден сақтану](/kb/double-refund).

## 12. Бірінші нақты төлем — кіші сомамен

**Не істеу керек:** live режимге көшкен соң, өз телефоныңыздан **ең кіші сомаға** (мысалы 100 ₸) счёт жасап, нақты төлеңіз.

**Не тексеріледі:** бірден бәрі — кілт, кассир, QR, webhook, сіздің жүйеңіздегі күй өзгерісі, Kaspi шотына ақшаның түсуі.

Содан кейін сол счётты қайтарыңыз — қайтару жолы да тексерілді. Бұл бес минуттық әрекет бірінші нақты клиентте шығатын мәселелерді алдын ала табады.

Өтпесе: [Нақты режимге көштім, бірақ істемей жатыр](/kb/after-live-not-working).

## Қысқаша тізім

Бір көзбен шолу үшін:

1. Кассир белсенді
2. Кілт `qp_live_…`
3. Webhook жария, `https`, тұрақты домен
4. Қолтаңба тексеріледі, timestamp 5 минут
5. `Idempotency-Key` жіберіледі, webhook идемпотентті
6. `late: true` өңделеді
7. Қате кодтары өңделеді
8. Журнал бар, кілтсіз
9. Тариф белсенді, лимит жетеді
10. Telegram ескертуі қосулы
11. Қайтару реті белгілі
12. Бірінші нақты төлем кіші сомамен өтті

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

**Режимді ауыстырғанда sandbox счёттарым не болады?** Олар орнында қалады, бірақ live тізімде көрінбейді. Лимитке де кірмейді.

**Sandbox кілтім live режимде жұмыс істей ме?** Жоқ. Режим мен кілт сәйкес келуі керек, әйтпесе 401 аласыз.

**Қай кезде тарифті төлеу керек?** Сынақ мерзімі бірінші live счёттан басталып, 7 күн жүреді. Сол уақытта таңдап, төлей саласыз: [Тарифті қалай төлеу керек](/kb/tariff-payment).

**Тізімнің қай тармағын өткізіп жіберуге болады?** Ешқайсысын. Бірақ ретін өзгертуге болады — 12-тармақ соңында тұруы керек, өйткені ол қалғандарының бәрін бір уақытта тексереді.