# Бірінші счётты қалай жасау керек

> Екі жолы бар: кабинеттен қолмен екі өрісті толтырып немесе API арқылы бір сұраумен. Алдымен sandbox-та жасап, төлемді симуляциялап көру ұтымды.

## Қысқаша

Счёт жасаудың екі жолы бар. **Кабинеттен қолмен**: [Счёттар](https://qut.kz/app/invoices/) бөлімінде соманы жазып, **Счёт жасау** батырмасын басасыз — бірден QR мен төлем сілтемесі шығады. **API арқылы**: `POST https://api.qut.kz/api/v1/invoices` сұрауын жібересіз. Бірінші рет sandbox режимінде жасаңыз: нақты ақша жүрмейді, төлемді өзіңіз имитациялай аласыз.

## Алдымен sandbox

Кабинеттің жоғарғы жағында режим белгісі тұрады: **SANDBOX** немесе **LIVE**. Бірінші счётты SANDBOX режимінде жасаған дұрыс:

- Kaspi шақырылмайды, кассир қосудың қажеті жоқ
- Нақты ақша жүрмейді, ешкімге ештеңе жіберілмейді
- Счёт лимиттерге кірмейді және [сынақ мерзімін](/kb/trial-period) бастамайды
- Төлемді өзіңіз имитациялай аласыз

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

## Жол 1: кабинеттен қолмен

1. [Счёттар](https://qut.kz/app/invoices/) бөліміне кіресіз
2. Счёт түрін таңдайсыз: **QR / сілтеме** немесе **Телефонға счёт (Kaspi қосымшасы)**
3. Соманы теңгемен жазасыз
4. Қаласаңыз сипаттама («Сипаттама (60 таңба)») және тапсырыс нөмірін («Тапсырыс № (қосымша)») толтырасыз
5. **Телефонға счёт** таңдасаңыз, клиент нөмірін `7XXXXXXXXXX` пішімінде жазасыз
6. **Счёт жасау** батырмасын басасыз

Дайын. Тізімде жаңа жол пайда болады, **Төлем беті** сілтемесі арқылы клиент көретін бетті ашып көресіз. Сілтемені WhatsApp-қа, Telegram-ға, директке жіберуге болады.

Sandbox режимінде счёттың қасында **[Sandbox] төленді** батырмасы тұрады — оны бассаңыз, счёт төленген болып белгіленеді және webhook-тар нақтысындай кетеді.

Бұл жол кодсыз жұмыс істейді: [Әзірлеуші жоқ — қалай бастау керек](/kb/no-developer).

## Жол 2: API арқылы

Алдымен кабинеттің [Интеграциялар](https://qut.kz/app/integrations/) бөлімінде **API кілттері** блогынан кілт жасайсыз. Кілт **бір рет қана көрсетіледі** — сол жерде көшіріп алыңыз. Sandbox режимінде кілт `qp_test_…` деп басталады.

```bash
curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_test_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": 2500,
    "kind": "qr",
    "description": "Тапсырыс №1001",
    "externalOrderId": "1001",
    "customer": { "name": "Асан", "phone": "77010000000" }
  }'
```

Жауап 201 болады, ішінде:

| Өріс | Не үшін |
|---|---|
| `id` | Счёттың идентификаторы, күйін сұрағанда керек |
| `status` | Бастапқы күйі |
| `payUrl` | Клиентке жіберетін төлем беті |
| `qrUrl`, `qrImageUrl`, `deepLink` | QR және Kaspi қосымшасына апаратын сілтеме |
| `expiresAt` | Счёттың жарамдылық мерзімі |

Клиентке `payUrl` сілтемесін берсеңіз жеткілікті — ол бетте QR да, Kaspi-ге өтетін батырма да бар.

`Idempotency-Key` тақырыбын әр счётқа бірегей етіп қойған дұрыс (тапсырыс нөмірі жарайды). Сол кілтпен сұрау қайталанса, жаңа счёт жасалмайды, бұрынғысы қайтады.

Sandbox-та төлемді имитациялау: `POST /api/v1/invoices/{id}/simulate` денесінде `{ "status": "paid" }`.

Толық құжаттама: https://api.qut.kz/docs

## Счётты қайдан көру керек

- **Кабинет → Счёттар** — тізім, сүзгілер, іздеу, әр счёттың күйі
- **Кабинет → Шолу** — соңғы счёттар мен бүгінгі түсім
- `GET /api/v1/invoices/{id}` — счёт, оның оқиғалары мен қайтарулары
- Webhook — күй өзгерген сәтте өзіңіздің адресіңізге хабар келеді
- Telegram бот — `/last` және `/today` командалары

Кабинетте не қайда тұрғаны: [Кабинетте не қайда тұр](/kb/cabinet-tour).

## Бірінші счёт шықпаса

| Белгісі | Себебі |
|---|---|
| API 401 қайтарады | Кілт жоқ, қате жазылған немесе `X-API-Key` тақырыбы қойылмаған |
| API 403 қайтарады | Кілтте керекті құқық жоқ немесе тариф белсенді емес |
| Live режимде счёт жасалмайды | Kaspi кассирі қосылмаған немесе байланысы үзілген |
| Кілт жарамсыз дейді | Кілт пен режим сәйкес емес: sandbox кілтін live режимде қолданып тұрсыз |
| Сома қабылданбайды | QR счётта ең көбі 2 ондық, телефонға счётта бүтін теңге |

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

**Счёт жасау үшін кассир керек пе?** Sandbox-та керек емес. Live режимде — иә, Kaspi кассирі қосулы болуы керек.

**QR қанша тұрады?** Kaspi-дің сканерлеу терезесі шамамен үш минут, нақты уақытын жауаптағы `expiresAt` өрісінен қараңыз. Уақыт өтсе, жаңа счёт жасайсыз.

**Клиентте Kaspi қосымшасы жоқ болса?** Телефонға счёт жетпейді, оған QR немесе `payUrl` сілтемесін беріңіз.

**Sandbox-та жасаған счёттарым live-қа көше ме?** Жоқ. Режимдер бөлек, sandbox счёттары тек sandbox-та қалады.

**Бір сұраумен бірнеше счёт жасауға бола ма?** Иә, `POST /api/v1/invoices/bulk` бір сұрауда 1-ден 100-ге дейін счёт қабылдайды. Кабинетте бұл **Топтап (CSV)** деп аталады.