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

Қысқаша

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

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

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

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

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

Демеушілік немесе ерікті жарна жинасаңыз, соманы клиент өзі енгізетін сілтеме жасаңыз: Ашық сомалы төлем сілтемелері.

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

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

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

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

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

Есік алдындағы сканерлейтін 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-ді тіркелу нөмірінен құраңыз — сонда «Төлеу» батырмасы екі рет басылса да, екінші счёт жасалмайды.

Есік алдында

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

Телефонға счёт жібергенде клиенттің Kaspi қосымшасына push келеді, ол бірден растайды. Нөмірі 7XXXXXXXXXX пішімінде болсын. Салыстыру: QR счёт пен телефонға счёт.

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

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

Топтап счёт

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

Әр элемент бөлек тексеріледі: біреуі қате болса, қалғандары бәрібір жасалады. Жауапта қайсысы өтті, қайсысы құлады — бәрі көрінеді. Оны бүтін деп санамаңыз, әр элементтің нәтижесін оқып шығыңыз. Толығы: Топтап счёт жасау.

Топтап шығарғанда әрқайсысына өз 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 және тапсырыс нөмірі.

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

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

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.

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

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

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

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

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

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

Сатылған билетті қайтаруға мерзім бар ма? Иә, қайтарудың өз мерзімі бар. Ұзақ уақыт бұрын сатылған билетті қайтару өтпей қалуы мүмкін: Қайтару API.

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

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