# Мейрамхана мен кафеге

> Үстелдегі QR, кассадағы экран, есеп-шот сомасы бойынша счёт, бөліп төлеу, даяшы бойынша есеп және жеткізу тапсырысы — залда Qut Pay қалай жұмыс істейтінінің толық сценарийі.

## Қысқаша

Мейрамханада екі бөлек нәрсе бар: **тұрақты сілтеме** (үстелге басып қоятын QR, сомасы ашық) және **динамикалық счёт** (есеп-шоттың нақты сомасына кассада шығарылады). Күнделікті жұмыс екіншісіне құрылады: даяшы есеп-шотты жауып, кассадағы экранда немесе планшетте QR көрсетеді, клиент Kaspi қосымшасымен сканерлейді, төлем 5 секунд шамасында сіздің жүйеңізге webhook арқылы келеді де, есеп-шот жабылады. Ақша тіке сіздің Kaspi шотыңызға түседі.

## Күнделікті сценарий: үстелде төлеу

1. Даяшы POS-та есеп-шотты жабады, сома шығады: 14 300 ₸.
2. Сіздің жүйеңіз `POST /api/v1/invoices` жібереді: `amount: 14300`, `description: "Есеп-шот №418, 6-үстел"`, `externalOrderId: "418"`.
3. Жауапта `qrImageUrl` мен `expiresAt` келеді. QR-ды кассаның экранына, планшетке немесе чек принтеріне шығарасыз.
4. Клиент Kaspi қосымшасымен сканерлейді және төлейді.
5. Сізге `invoice.paid` webhook келеді. POS есеп-шотты «төленді» деп жабады, үстел босайды.

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

## Үстелдегі басылған QR мен кассадағы экран

Бұл екеуін шатастырмау керек — олар бөлек нәрсе.

| | Үстелге басып қоятын QR | Кассадағы/планшеттегі QR |
|---|---|---|
| Не бұл | [Төлем сілтемесі](/kb/payment-links) `qut.kz/p/<slug>` QR түрінде | Нақты счёттың Kaspi QR-ы |
| Сома | Ашық, клиент өзі енгізеді | Есеп-шоттың дәл сомасы |
| Мерзімі | Тұрақты, айлап тұра береді | Шамамен үш минут |
| Қашан ыңғайлы | Шайханалар, фудкорт, тез қызмет, бахшиш | Толық сервисі бар зал |
| Тәуекелі | Клиент соманы қате енгізуі мүмкін | Терезе өтіп кетсе қайта шығару керек |

Көп мейрамхана екеуін қатар ұстайды: залда — кассадағы динамикалық QR, ал үстелдерде тұрақты сілтеме «қосымша сый» немесе тез төлеу үшін.

## Есеп-шот сомасы бойынша счёт

```json
POST /api/v1/invoices
{
  "amount": 14300,
  "kind": "qr",
  "description": "Есеп-шот №418, 6-үстел",
  "externalOrderId": "418",
  "metadata": { "table": "6", "waiter": "aigerim", "shift": "evening" }
}
```

`description` клиентке көрінеді, QR счёт үшін ең көбі 100 таңба. Онда қонақ түсінетін нәрсе тұрсын: есеп-шот нөмірі мен үстел жеткілікті. Тағам тізімін тықпалаудың қажеті жоқ.

`Idempotency-Key` тақырыбын жіберіңіз. Даяшы «QR көрсету» батырмасын екі рет басса немесе Wi-Fi үзіліп қайта жіберілсе, сол кілтпен жаңа счёт жасалмайды, бұрынғысы қайтады.

## Бөліп төлеу

Бір счётты бірнеше адам бөліп төлей алмайды — Kaspi счёты бөлінбейді. Сондықтан **бірнеше бөлек счёт** шығарасыз.

- Есеп-шотты POS-та бөлесіз: 14 300 ₸ → 7 150 + 7 150 немесе позициялар бойынша.
- Әр бөлікке жеке счёт жасайсыз, `externalOrderId` бөлек болсын: `418-1`, `418-2`.
- `metadata` ішіне ортақ есеп-шот нөмірін жазасыз: `{ "bill": "418" }`. Кейін есепте оларды бір топқа жинау үшін керек.
- Бөліктер бөлек-бөлек төленеді, әрқайсысына жеке `invoice.paid` келеді. Есеп-шотты бәрі төленгенде ғана жабыңыз.

Біреуі төленіп, екіншісі төленбей қалса, төленбегенін `POST /api/v1/invoices/{id}/cancel` арқылы жабасыз да, қалған соманы қайта шығарасыз.

## Даяшы бойынша есеп

Екі жолы бар, екеуі де жұмыс істейді.

**Жеңілі — metadata.** Әр счётқа `metadata.waiter` жазасыз. Кейін [CSV экспортта](/kb/csv-export) немесе `GET /api/v1/invoices` арқылы сол өріс бойынша топтайсыз. Қосымша баптау керек емес, бір адамның ауысымы бір минутта есептеледі.

**Қатаңы — бөлек API кілт.** Әр кассаға (немесе нүктеге) бөлек кілт жасап, [оны кассирге байлауға](/kb/api-key-connection) болады. Байланған кілттің live счёттары тек сол кассир арқылы жүреді, басқа кассирдің счёттарын көрмейді. Бұл бірнеше залы немесе бірнеше нүктесі бар желіге ыңғайлы: [Нүктелер бойынша бөлек есеп](/kb/multi-point-reporting).

Әдетте бір мейрамханаға metadata жеткілікті, бөлек кілт — филиалдар үшін.

## Жеткізу тапсырысы

Жеткізуде төлем сәті бөлек: тапсырыс қабылданғанда немесе есік алдында.

- **Алдын ала төлем.** Оператор тапсырысты қабылдап, `kind: "phone"` счётын жібереді — клиенттің Kaspi-іне push келеді. `customer.phone` `7XXXXXXXXXX` пішімінде болсын. `description` мұнда 60 таңба.
- **Жеткізу сәтінде.** Курьер қолындағы телефоннан счёт шығарады немесе диспетчер шығарып, QR-ды курьерге жібереді. Курьер Kaspi-ге кірмейді, тек QR көрсетеді.
- Тапсырысты аспаздыққа **`invoice.paid` келгеннен кейін** ғана жіберіңіз, счёт жасалған сәтте емес.

Толығырақ: [Жеткізу қызметіне](/kb/for-delivery).

## Kaspi қосымшасы жоқ клиентке не істеу керек

Мұндай қонақ сирек, бірақ кездеседі. Есте сақтайтыны: **телефонға счёт (`kind: "phone"`) оған жетпейді** — push Kaspi қосымшасына келеді, қосымша жоқ болса ешнәрсе келмейді.

Не істейсіз:

1. QR-ды басқа адамға көрсетесіз — қасындағы серігі төлеп, олар өзара есептеседі.
2. `payUrl` сілтемесін WhatsApp-пен жібересіз: браузерде ашылады.
3. Қалғаны — сіздің кассаңыздың қалыпты тәртібі: қолма-қол ақша немесе карта. Qut Pay мұнда араласпайды.

Толығы: [Клиентте Kaspi қосымшасы жоқ](/kb/customer-no-kaspi).

## Кодсыз нұсқасы

Әзірлеушіңіз болмаса да бастай аласыз:

- **Кабинеттен қолмен.** [Счёттар](https://qut.kz/app) бөлімінде сома мен сипаттаманы жазып, QR аласыз. Кассадағы компьютер немесе планшет жеткілікті.
- **Telegram бот.** Даяшының телефонынан `/invoice 14300 Есеп-шот 418` деп жазып, QR алады. `/today` — ауысым қорытындысы, `/last` — соңғы счёттар.
- **Тұрақты сілтемелер.** Үстелге де, тұтқаға да басып қоюға болады, сомасы ашық.
- **n8n.** POS-ыңыз webhook шығарса, n8n-ге жалғап, счётты автоматты шығаруға болады, код жазбай.

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

- **Кассир нөмірімен Kaspi Pay қосымшасына кірмеңіз.** Kaspi бір кассирге бір ғана белсенді құрылғы береді, кірген сәтте біздің байланыс үзіледі де, кешкі толы залда счёт шығару тоқтайды. Бұл ең жиі кездесетін апат: [Кассир байланысы үзілді](/kb/connection-lost).
- **Кеш келген төлем болады.** Счёт `expired` болып қалғаннан кейін де ақша келіп, `invoice.paid` оқиғасы `late: true` белгісімен келуі мүмкін. Қонақ кетіп қалған болса, ақшаны қайтарасыз: [Кеш келген төлем](/kb/late-payment).
- **Кассир нөмірі қонаққа көрінеді.** Счёт туралы хабарламада ол нөмір тұрады, бұл Kaspi-дің қалыпты жұмысы.
- **Фискалды чек бөлек мәселе.** Оны Qut Pay шешпейді: [Фискалды чек](/kb/fiscal-receipt).
- **Тарифті ауысым саны бойынша таңдаңыз.** Күніне 30 есеп-шот — айына 900 шамасында, бұл Бизнес тарифі. Есептеу: [Қай тарифті таңдау керек](/kb/tariff-choose).

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

**Әр үстелге бөлек QR басып қойсақ бола ма?** Болады, бірақ ол ашық сомалы төлем сілтемесі болады — клиент соманы өзі енгізеді. Есеп-шоттың дәл сомасы керек болса, кассадан динамикалық счёт шығарыңыз.

**Бахшишті бөлек алуға бола ма?** Иә, екінші счёт жасаңыз немесе ашық сомалы сілтеме беріңіз. Бір счёттың сомасын клиент өзгерте алмайды.

**Счётты қате сомамен шығарып қойдым, не істеймін?** Төленбеген болса — `cancel` жасап, дұрысын шығарасыз. Төленіп кетсе — [қайтару](/kb/refunds-api) арқылы толық немесе ішінара қайтарасыз.

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

**Бірнеше филиал бар, есеп араласып кетпей ме?** Әр филиалға бөлек кілт беріп, әрқайсысын өз кассиріне байлайсыз. Сонда есеп те, счёттар да бөлек көрінеді: [Нүктелер бойынша бөлек есеп](/kb/multi-point-reporting).