# Сома дұрыс емес немесе тиын жоғалып жатыр

> Телефонға шығарылған счёт бүтін теңге қабылдайды, QR счёт ең көбі екі ондық. amount_must_be_whole_tenge қатесінің себебі, дөңгелектеуді өз жағыңызда қалай дұрыс істеу керек.

## Қысқаша

Екі ереже бәрін түсіндіреді. **Телефонға шығарылған счёт (`kind: "phone"`) бүтін теңге қабылдайды** — тиын жіберсеңіз, `amount_must_be_whole_tenge` қатесі келеді. **QR счёт ең көбі екі ондық белгіні қабылдайды.** Валюта әрқашан — KZT, басқасы жоқ.

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

## Симптом бойынша себеп

| Симптом | Себебі | Шешімі |
|---|---|---|
| `amount_must_be_whole_tenge` | Телефонға счётқа тиын жіберілген | Дөңгелектеп, бүтін теңге жіберіңіз |
| `invalid_amount` | Сома жоқ, нөл, теріс немесе сан емес | Оң сан жіберіңіз |
| `amount_too_small` | Ең төменгі шектен аз | Сомасын көбейтіңіз |
| `amount_too_large` | Ең жоғарғы шектен көп | Азайтыңыз немесе бірнеше счётқа бөліңіз |
| Клиент басқа соманы көріп тұр | Сома жолмен жіберілген, бөлгіш дұрыс емес | Сан түрінде жіберіңіз |
| Тиын жоғалды | QR екі ондыққа дейін қабылдайды, артығы қысқарған | Өз жағыңызда дөңгелектеңіз |

## Сома қалай жіберіледі

`amount` өрісі — **сан**, теңгемен. Тиынмен емес: 1 000 ₸ жіберу үшін `1000` жазасыз, `100000` емес.

```bash
curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_live_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"kind":"qr","description":"Тапсырыс №1042"}'
```

Телефонға счёт:

```bash
curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_live_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"kind":"phone","customer":{"phone":"77771234567"},"description":"Тапсырыс №1042"}'
```

Мұнда `1000.50` жіберсеңіз, `amount_must_be_whole_tenge` қайтады.

## Дөңгелектеуді өз жағыңызда істеңіз

Ең жиі кездесетін көрініс: себетте `3 333.33 ₸` тұр, ал клиент `3 333 ₸` төлейді. Айырма кішкентай, бірақ айдың соңында есеп айырысқанда бәрі көрініп қалады.

Сондықтан ретті былай құрыңыз:

```js
// 1. Соманы өз жағыңызда бүтіндеңіз
const total = Math.round(cart.total);   // 3333.33 → 3333

// 2. Сол соманы өз базаңызға жазыңыз
await orders.update(orderId, { chargedAmount: total });

// 3. Дәл сол соманы жіберіңіз
await createInvoice({ amount: total, kind: 'phone', ... });
```

Үш ұстаным:

- **Бір ғана дөңгелектеу нүктесі болсын.** Есептің әр жерінде дөңгелектесеңіз, қателік жиналады.
- **Дөңгелектелген соманы базаға жазыңыз.** Кейін салыстырғанда қай сома нағыз екені белгілі болады.
- **Клиентке сол соманы көрсетіңіз.** Себетте бір сома, счётта екінші сома тұрса, сұрақ туады.

`Math.round` жоғары қарай дөңгелектейді (`0.5` → жоғары). Егер сіз әрқашан төмен қарай дөңгелектегіңіз келсе, `Math.floor` қолданыңыз — бірақ таңдағаныңызды бүкіл жүйеде бірдей ұстаңыз.

## Жүздік бөлікпен жұмыс

Егер жүйеңізде бағалар тиынмен сақталса (мысалы `333333` = 3 333.33 ₸), айналдыруды бір жерде істеңіз:

```js
const tenge = Math.round(priceInTiyn / 100);
```

Қалқымалы санмен есептеуден сақ болыңыз: `0.1 + 0.2` көп тілде `0.30000000000000004` береді. Бағаларды бүтін санмен (тиынмен) сақтап, тек соңғы қадамда теңгеге айналдырған сенімді.

## Екі счёттың айырмашылығы

| Не | QR счёт (`qr`) | Телефонға счёт (`phone`) |
|---|---|---|
| Сома | Ең көбі 2 ондық | Тек бүтін теңге |
| Сипаттама | 100 таңбаға дейін | 60 таңбаға дейін |
| Клиент нөмірі | Керек емес | Міндетті, `7XXXXXXXXXX` |
| Қалай көрінеді | QR, сілтеме, deep link | Клиенттің Kaspi-іне хабарлама |

Практикада екеуіне де бүтін теңге жіберген ыңғайлы: сонда счёт түрін ауыстырғанда логиканы қайта жазудың қажеті болмайды.

## Сома шектеулері

Ең төменгі және ең жоғарғы сома бар, және оларды біз емес, Kaspi жағы да шектейді. Шектен шықсаңыз `amount_too_small` немесе `amount_too_large` келеді.

Ірі сомамен жұмыс істейтін болсаңыз (мысалы көтерме сауда), екі нәрсені ескеріңіз:

- Соманы бірнеше счётқа бөлу — жұмыс істейтін тәсіл, бірақ әр счётты бөлек бақылау керек
- Клиенттің өз жағында да лимиттер болуы мүмкін, ол Kaspi-дің баптауы

Сондай-ақ `amount_too_large` қатесі кодтағы қатеден де келеді: айнымалы тиынмен берілгенде сома жүз есе үлкейіп кетеді. Мұндайда шектен асқан сан әдетте көзге бірден түседі.

## Валюта

Валюта тек **KZT**. Басқа валютаны жіберудің жолы жоқ, `currency` өрісін іздеудің қажеті жоқ.

Сайтыңыз бірнеше валютада баға көрсетсе, айырбастауды өз жағыңызда, счёт жасаудан бұрын істеңіз. Клиент Kaspi-де әрқашан теңгемен төлейді.

## Тексеру реті

1. Қате мәтінін оқыңыз: `amount_must_be_whole_tenge` па, `invalid_amount` па
2. Жіберіп жатқан мәннің типін тексеріңіз: сан ба, жол ба
3. Телефонға счёт болса, тиын бар-жоғын қараңыз
4. Өз базаңыздағы сома мен жіберілген сома бірдей ме
5. Дөңгелектеу кодта бір ғана жерде тұр ма

Егер сома дұрыс, бірақ ақша көрінбей жатса, мәселе басқада: [Счёт төленді, ақша түспеді](/kb/money-not-received).

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

**QR счётқа тиын жіберуге бола ма?** Екі ондыққа дейін қабылданады. Бірақ практикада бүтін теңге жіберген қарапайым әрі қауіпсіз.

**Клиент соманы өзі өзгерте ала ма?** Әдеттегі счётта — жоқ, сома бекітілген. Ашық сомалы төлем сілтемесінде клиент өзі енгізеді.

**Сома жолмен жіберілсе не болады?** Кейбір жағдайда қабылданады, кейбірінде `invalid_amount` келеді. Әрқашан сан түрінде жіберіңіз.

**Дөңгелектегенде айырманы кім төлейді?** Бұл сіздің шешіміңіз. Көбі төмен қарай дөңгелектеп, бірнеше тиынды өзі көтереді — клиентке түсіндіру қиынырақ болады.

**Счёт жасалып қойған, соманы өзгертуге бола ма?** Жоқ. Счётты болдырып, жаңасын жасау керек.