# Іс-шара мен билет сатуға

> Алдын ала сату төлем сілтемесі немесе сайттағы форма арқылы, есік алдында QR немесе телефонға счёт, топтап счёт, орын нөмірін metadata-ға жазу және жаппай қайтару.

## Қысқаша

Іс-шара төлемінің екі бөлек сәті бар және оларды екі бөлек құралмен жасайсыз. **Алдын ала сатуда** — төлем сілтемесі (кодсыз) немесе сайттағы форма (форма-хук арқылы). **Есік алдында** — экранда QR көрсету немесе клиенттің телефонына тікелей счёт жіберу, себебі ол жерде секунд саналады. Орын нөмірі, сектор, билет түрі — бәрі `metadata` өрісіне жазылады және webhook-та қайта келеді. Іс-шара болмай қалса, барлық счёт бойынша қайтару жасайсыз.

## Алдын ала сату

### Кодсыз: төлем сілтемесі

Ең қарапайымы. Билет түрі бойынша бір-бір сілтеме жасайсыз:

| Билет | Сома | Сілтеме |
|---|---|---|
| Стандарт | 8 000 ₸ | `qut.kz/p/standart` |
| VIP | 20 000 ₸ | `qut.kz/p/vip` |
| Студент | 4 000 ₸ | `qut.kz/p/student` |

Сілтемелерді Instagram-ға, афишаға, Telegram арнасына қоясыз. Кім төлегенін кабинеттен көресіз. Толығы: [Төлем сілтемелері](/kb/payment-links).

Демеушілік немесе ерікті жарна жинасаңыз, соманы клиент өзі енгізетін сілтеме жасаңыз: [Ашық сомалы төлем сілтемелері](/kb/open-amount-links).

### Сайттағы форма

Тіркелу формасы болса (аты, телефоны, билет түрі), форманы төлемге қосасыз. Tilda және кез келген форма форма-хук арқылы жалғанады, код жазудың қажеті жоқ: [Tilda және кез келген форма](/kb/tilda-forms).

Өз сайтыңыз болса, бір ғана API әдісі керек.

## Жұмыс схемасы қадамдап

Сайттан билет сату:

| Қадам | Кім | Не болады |
|---|---|---|
| 1 | Қатысушы | Формаға деректерін жазады, билет түрін таңдайды |
| 2 | Сіздің сервер | `POST /api/v1/invoices` — счёт жасайды, `metadata`-ға орын мен билет түрін салады |
| 3 | Қатысушы | Сілтемені ашып, Kaspi-де растайды |
| 4 | Qut Pay | `invoice.paid` оқиғасын сіздің адреске жібереді |
| 5 | Сіздің сервер | Билетті шығарады, QR-ын қатысушыға жібереді |
| 6 | Есік алдында | Билеттің QR-ын сканерлеп, кіргізесіз |

Есік алдындағы сканерлейтін QR — **сіздің билетіңіздің** QR-ы, төлемдікі емес. Екеуін шатастырмаңыз.

## Қандай API әдісі қолданылады

```
POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Idempotency-Key: reg-2026-0417-A14

{
  "amount": 8000,
  "kind": "qr",
  "description": "Concert 17.04, стандарт",
  "externalOrderId": "reg-2026-0417-A14",
  "customer": { "name": "Дархан", "phone": "77011234567" },
  "metadata": {
    "event": "concert-2026-04-17",
    "ticketType": "standard",
    "sector": "A",
    "seat": 14
  }
}
```

`description` клиентке көрінеді: QR счётта 100 таңба, телефонға счётта 60 таңба шектеуі бар. Іс-шараның атауы мен күнін сол жерге сыйдырыңыз.

`Idempotency-Key`-ді тіркелу нөмірінен құраңыз — сонда «Төлеу» батырмасы екі рет басылса да, екінші счёт жасалмайды.

## Есік алдында

Кассада немесе кіреберісте кезек тұрады, сондықтан жылдамдық маңызды. Екі жол:

| Жол | Қалай | Қашан жақсы |
|---|---|---|
| Экранда QR | Планшетте счёттың QR-ын ашасыз, келуші сканерлейді | Жарық жақсы, кезек қалыпты |
| Телефонға счёт | Нөмірін сұрап, `kind: "phone"` счёт жібересіз | Қараңғы, сыртта, экран көрінбейді |

Телефонға счёт жібергенде клиенттің Kaspi қосымшасына push келеді, ол бірден растайды. Нөмірі `7XXXXXXXXXX` пішімінде болсын. Салыстыру: [QR счёт пен телефонға счёт](/kb/qr-vs-phone).

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

Кодсыз нұсқасы: кабинеттен немесе Telegram боттың `/invoice` командасымен счёт шығарасыз. Есік алдында телефоннан жұмыс істеу үшін бот ыңғайлы.

## Топтап счёт

Ұйымдарға, топтарға, мектеп сыныптарына билет сатсаңыз, счёттарды бір сұрауда жасауға болады: `POST /api/v1/invoices/bulk`, бір сұрауда 1-100 счёт.

Әр элемент **бөлек тексеріледі**: біреуі қате болса, қалғандары бәрібір жасалады. Жауапта қайсысы өтті, қайсысы құлады — бәрі көрінеді. Оны бүтін деп санамаңыз, әр элементтің нәтижесін оқып шығыңыз. Толығы: [Топтап счёт жасау](/kb/bulk-invoices).

Топтап шығарғанда әрқайсысына өз `externalOrderId` және өз `metadata`-сын беріңіз, сонда кім төлегенін ажыратасыз.

## Metadata: орын нөмірі

Іс-шарада `metadata` — ең пайдалы өріс. Оған не жазуға болады:

```
"metadata": {
  "event": "concert-2026-04-17",
  "ticketType": "vip",
  "sector": "B",
  "row": 3,
  "seat": 12,
  "promoter": "insta",
  "guestName": "Дархан"
}
```

Не береді:

- `invoice.paid` webhook-ында бәрі қайта келеді — билетті сол жерде шығарасыз
- CSV экспортта сүзе аласыз: қай сектор қанша сатылды
- Промоутер бойынша есеп: қай арна қанша билет әкелді

`externalOrderId` бөлек — ол сіздің тіркелу нөміріңіз. Екеуін қатар қолданыңыз: [Metadata және тапсырыс нөмірі](/kb/metadata-and-orders).

## Болмай қалған іс-шара: жаппай қайтару

Іс-шара болмай қалса, әр счёт бойынша қайтару жасайсыз:

```
POST https://api.qut.kz/api/v1/invoices/{id}/refund
{ "reason": "іс-шара болмай қалды" }
```

Реті:

1. **Тізімді алыңыз.** `GET /api/v1/invoices` арқылы немесе кабинеттен CSV экспортпен. `paid` күйіндегілерді бөліңіз.
2. **Алдымен хабарлаңыз.** Қайтару басталғанға дейін қатысушыларға жазыңыз, әйтпесе қолдау қызметіңіз хабарламаға көміледі.
3. **Бірінен соң бірін жасаңыз.** Жаппай қайтару әдісі жоқ, әр счётқа бөлек сұрау. Аралық қойыңыз, жиілік шектеуіне тірелмеу үшін.
4. **Нәтижесін жазып отырыңыз.** Қайсысы өтті, қайсысы құлады — тізімді сақтаңыз.
5. **`refund_unknown` келсе, қайталамаңыз.** Алдымен счёттың күйін оқыңыз, әйтпесе екі рет қайтарып жіберуіңіз мүмкін. Толығы: [Қайтару API](/kb/refunds-api).

Іс-шара кейінге шегерілсе, қайтарудың орнына билетті жаңа күнге жарамды деп жариялау — жиі кездесетін әрі оңайырақ шешім.

## Ерекше ескертулер

- **Кеш келген төлем.** Счёт `expired` болғаннан кейін ақша келсе, оқиға `late: true` белгісімен келеді. Есік алдында бұл нақты адам — кіргізіңіз немесе ақшаны бірден қайтарыңыз.
- **Тәуліктік қорғанысты ескеріңіз.** Билет сатылымы басталған күні счёт саны бір күнде шарықтайды. Тәуліктік сан — бизнес лимиті емес, циклден қорғаныс, бірақ оған тірелсеңіз `tariff_daily_burst` қатесін аласыз. Іс-шараға дейін тарифті тексеріңіз: [Қай тарифті таңдау керек](/kb/tariff-choose).
- **Есік алдында интернет болсын.** Счёт жасау интернетсіз жұмыс істемейді. Нүктеде Wi-Fi нашар болса, мобильді интернеті бар екінші телефон дайын тұрсын.
- **Алдын ала сынаңыз.** Іс-шараға бір күн қалғанда емес, бір апта бұрын sandbox-та толық циклді жүргізіп көріңіз: [Интеграцияны қалай сынау керек](/kb/testing-integration).
- **Ақша тіке сіздің Kaspi шотыңызға түседі**, бізде ұсталмайды.

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

**Билеттің өзін кім шығарады?** Сіз. Біз төлемді ғана өңдейміз. Билетті, оның QR-ын және кіреберістегі тексеруді өзіңіз жасайсыз немесе билет жүйесін қолданасыз.

**Бір адам екі билет алса ше?** Бір счёт шығарыңыз, `amount`-қа жалпы соманы, `metadata`-ға орындар тізімін жазыңыз. Немесе әр орынға бөлек счёт — қайтару керек болса, бөлек счёт ыңғайлырақ.

**Сатылған билетті қайтаруға мерзім бар ма?** Иә, қайтарудың өз мерзімі бар. Ұзақ уақыт бұрын сатылған билетті қайтару өтпей қалуы мүмкін: [Қайтару API](/kb/refunds-api).

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

**Тіркелу тегін, бірақ келмегендер көп. Не істеймін?** Шағын сома алыңыз (1 000-2 000 ₸) немесе депозит схемасын қолданыңыз — келгенде қайтарасыз. Ұқсас схема: [Сұлулық салоны мен барберге](/kb/for-beauty-salon).