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

Қысқаша

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

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

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

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

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

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

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

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

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

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 экспортта немесе GET /api/v1/invoices арқылы сол өріс бойынша топтайсыз. Қосымша баптау керек емес, бір адамның ауысымы бір минутта есептеледі.

Қатаңы — бөлек API кілт. Әр кассаға (немесе нүктеге) бөлек кілт жасап, оны кассирге байлауға болады. Байланған кілттің live счёттары тек сол кассир арқылы жүреді, басқа кассирдің счёттарын көрмейді. Бұл бірнеше залы немесе бірнеше нүктесі бар желіге ыңғайлы: Нүктелер бойынша бөлек есеп.

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

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

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

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

Толығырақ: Жеткізу қызметіне.

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

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

Не істейсіз:

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

Толығы: Клиентте Kaspi қосымшасы жоқ.

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

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

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

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

Кассир нөмірімен Kaspi Pay қосымшасына кірмеңіз. Kaspi бір кассирге бір ғана белсенді құрылғы береді, кірген сәтте біздің байланыс үзіледі де, кешкі толы залда счёт шығару тоқтайды. Бұл ең жиі кездесетін апат: Кассир байланысы үзілді.
Кеш келген төлем болады. Счёт expired болып қалғаннан кейін де ақша келіп, invoice.paid оқиғасы late: true белгісімен келуі мүмкін. Қонақ кетіп қалған болса, ақшаны қайтарасыз: Кеш келген төлем.
Кассир нөмірі қонаққа көрінеді. Счёт туралы хабарламада ол нөмір тұрады, бұл Kaspi-дің қалыпты жұмысы.
Фискалды чек бөлек мәселе. Оны Qut Pay шешпейді: Фискалды чек.
Тарифті ауысым саны бойынша таңдаңыз. Күніне 30 есеп-шот — айына 900 шамасында, бұл Бизнес тарифі. Есептеу: Қай тарифті таңдау керек.

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

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

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

Счётты қате сомамен шығарып қойдым, не істеймін? Төленбеген болса — cancel жасап, дұрысын шығарасыз. Төленіп кетсе — қайтару арқылы толық немесе ішінара қайтарасыз.

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

Бірнеше филиал бар, есеп араласып кетпей ме? Әр филиалға бөлек кілт беріп, әрқайсысын өз кассиріне байлайсыз. Сонда есеп те, счёттар да бөлек көрінеді: Нүктелер бойынша бөлек есеп.

Qut Pay — тәуелсіз сервис, «Kaspi Bank» АҚ-мен аффилирленбеген. Kaspi және Kaspi Pay — құқық иесінің тауар белгілері.