Медициналық орталыққа

Қысқаша

Медициналық орталықта Qut Pay үш жерде жұмыс істейді: қабылдауға жазылғанда (алдын ала төлем немесе брондау), тіркеу орнында (қабылдау ақысы) және нәтиже дайын болғанда (талдау үшін төлем). Барлығы бір ғана әдіске келіп тіреледі: счёт жасайсыз, клиент Kaspi арқылы төлейді, сізге webhook келеді. Бір ерекше ережесі бар және ол қатаң: счёт сипаттамасына пациенттің диагнозын, дәрігердің атын немесе науқас туралы кез келген деректі жазбаңыз. Сипаттамада тек қызмет атауы тұрады, ішкі деректер metadata ішінде қалады.

Құпиялық: сипаттамада не жазуға болмайды

description өрісін клиент көреді: Kaspi қосымшасындағы хабарламада, төлем бетінде, кейін Kaspi тарихында. Ол мәтін экранда ашық тұрады, телефонды басқа адам ұстап тұруы да мүмкін.

Дұрыс құрылым:

POST /api/v1/invoices
{
  "amount": 12000,
  "kind": "qr",
  "description": "Маман қабылдауы",
  "externalOrderId": "V-2026-09-4471",
  "metadata": {
    "patient_id": "4471",
    "service_code": "A01.20",
    "doctor_id": "d-17",
    "branch": "center"
  }
}

metadata клиентке көрсетілмейді, ол сіздің жүйеңізге webhook-пен қайта оралады. Пациентті сол арқылы табасыз. Толығырақ: Metadata және тапсырыс нөмірі және Деректер және құпиялық.

Тағы екі нәрсе:

• customer.name өрісіне толық аты-жөнін жазудың қажеті жоқ. Ол міндетті емес өріс.
• Есепті кабинеттен қарайтын әкімшілер счёттардың сипаттамасын көреді. Сипаттама бейтарап болса, кабинетке кіру құқығы бар кез келген қызметкер пациенттің не үшін келгенін көрмейді.

Қабылдау ақысы тіркеу орнында

1. Тіркеуші МИС-те қабылдауды белгілейді, қызмет пен бағасы шығады.
2. Жүйе счёт жасайды, сипаттамасы бейтарап.
3. Тіркеу орнындағы экранда QR шығады, пациент сканерлеп төлейді.
4. invoice.paid келеді — қабылдау «төленді» болып белгіленеді, талон басылады.

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

Пациент кезекте тұрғысы келмесе — телефонына счёт жіберіңіз: kind: "phone", customer.phone 7XXXXXXXXXX пішімінде. Оның Kaspi-іне push келеді, ол отырған жерінде төлейді. Мұнда description 60 таңбадан аспайды.

Алдын ала төлем және брондау

Қашықтан жазылғанда (сайт, кол-орталық, WhatsApp) төлемді алдын ала алуға болады. Бұл келмей қалатындарды азайтады.

• Толық төлем. Қызметтің толық құны. Пациент келмесе, жазылу ережеңіз бойынша қайтарасыз немесе басқа күнге ауыстырасыз.
• Брондау жарнасы. Мысалы 3 000 ₸. Қалғаны қабылдау кезінде төленеді, екінші счётпен.

Екеуінде де уақытты invoice.paid келгенде ғана бекітіңіз. Счёт жасалған сәтте орын бос болып тұра берсін, әйтпесе төлемей кеткен адамдар кестені бітеп тастайды.

Күн бойы бос тұрған кезектерді босатып отырыңыз: счёт expired немесе cancelled болса, орынды қайтадан ашасыз. Бірақ есте болсын — кеш келген төлем болады: жабылған счётқа ақша кейін келіп, invoice.paid оқиғасы late: true белгісімен келуі мүмкін. Ондайда не басқа уақыт ұсынасыз, не ақшаны қайтарасыз: Кеш келген төлем.

Талдау нәтижесіне төлем

Зертханада көбіне рет басқаша: үлгі алынады, нәтиже кейін дайын болады.

1. Үлгі алынған сәтте externalOrderId ретінде зертхана нөмірін беріп счёт жасайсыз.
2. Нәтиже дайын болғанда пациентке хабарлайсыз және счётты телефонына жібересіз.
3. invoice.paid келгенде нәтижені ашасыз — жеке кабинетте, email арқылы немесе қолына бересіз.

Нәтижені төлем расталғанға дейін бермеңіз. invoice.created немесе invoice.pending оқиғасы төлем емес, ол тек счёттың жасалғаны.

Зертханалық панель бірнеше зерттеуден тұрса, бәрін бір счётқа жинаңыз. Бөлек-бөлек шығару пациентті шатастырады әрі айлық лимитті тез жейді.

Чек

Kaspi өз жағынан төлем туралы хабарлама береді, ал сіздің жағыңыздағы чек бөлек мәселе. Не бар:

• Біздің чек беті — счёт бойынша, сілтемесін пациентке беруге болады.
• Email — customer.email толтырылса, чекті солай жіберуге болады.
• Фискалды чек — бұл бөлек тақырып және оны Qut Pay шешпейді. Қай жағдайда міндетті, ОФД-мен қалай жұмыс істейді: Фискалды чек.

Чек бетінде де сипаттама көрінеді — тағы бір себеп, сипаттаманы бейтарап ұстауға. Толығырақ: Чектер және оларды клиентке жеткізу.

Қайтару

Медицинада қайтару жиі: пациент келмеді, қызмет көрсетілмеді, дәрігер ауырып қалды, панельдің бір бөлігі орындалмады.

POST /api/v1/invoices/{id}/refund
{ "amount": 5000, "reason": "Қызмет көрсетілмеді" }

• amount жазбасаңыз толық қайтарылады, жазсаңыз ішінара. Ішінара қайтарылған счёт partially_refunded күйіне өтеді.
• reason — сіздің ішкі жазбаңыз, есепте көрінеді. Оған да диагноз жазбаңыз.
• Қайтару жауабы белгісіз күйде келсе (refund_unknown) қайталап жібере салмаңыз, алдымен счёттың күйін оқыңыз: Екі рет қайтарып жіберуден қалай сақтану керек.

Толық анықтама: Қайтару API.

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

• Кабинеттен қолмен счёт. Тіркеуші сома мен бейтарап сипаттаманы жазып, QR шығарады. МИС-пен байланыстырудың қажеті жоқ.
• Тұрақты төлем сілтемелері. Жиі кездесетін қызметтерге: «Консультация», «Зертханалық зерттеу». Сайтқа да, WhatsApp-қа да қоюға болады: Төлем сілтемелері.
• Telegram бот. /invoice 12000 Маман қабылдауы, /today — күндік түсім.
• Кейін МИС-пен байланыстырғыңыз келсе, API дайын тұрады: Счёт жасау: барлық өрістер.

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

• Сипаттамада ешқашан диагноз, дәрігер аты, талдау түрі жоқ. Бұл бір ғана ереже, бірақ ең маңыздысы.
• Кассир нөмірімен Kaspi Pay қосымшасына кірмеңіз — байланыс үзіледі де, тіркеу орнында счёт шығару тоқтайды: Кассир байланысы үзілді.
• Кассир нөмірі пациентке көрінеді счёт туралы хабарламада. Сондықтан ол нөмір орталықтың жұмыс нөмірі болғаны дұрыс, қызметкердің жеке нөмірі емес.
• Нәтижені төлемге дейін ашпаңыз. Қолжетімділікті тек invoice.paid ашсын.
• Тарифті қабылдау саны бойынша есептеңіз. Күніне 40 қабылдау — айына 1 200 шамасында счёт: Қай тарифті таңдау керек.

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

Пациенттің аты-жөнін счётқа жазуға бола ма? Қажеті жоқ. Ішкі сәйкестендіру үшін metadata.patient_id жеткілікті, ал ол клиентке көрінбейді.

Пациент чек сұраса не беремін? Счёт бойынша чек бетінің сілтемесін бересіз немесе customer.email арқылы жібересіз. Фискалды чек бөлек мәселе.

Алдын ала төлемді қайтару міндет пе? Ол сіздің жазылу ережеңізге байланысты, Qut Pay мұнда араласпайды. Техникалық жағынан толық та, ішінара да қайтара аласыз.

Бірнеше филиал бар, есепті бөлуге бола ма? Иә, әр филиалға бөлек API кілт беріп, кассирге байлайсыз: Нүктелер бойынша бөлек есеп.

Кабинетке кіретін тіркеуші басқа пациенттердің счёттарын көре ме? Кабинеттегі рөліне байланысты. Сипаттама бейтарап болса, ол көрген деректен пациент туралы ештеңе білінбейді — сондықтан да бұл ереже маңызды: Рөлдер мен құқықтар.