Қысқаша
Bitrix24, amoCRM, Kommo, Altegio, МойСклад — бұлардың ешқайсысына дайын модулімізде жоқ, қосылу API арқылы жүреді. Талап бір ғана: CRM сыртқа HTTP сұрау жібере алсын (робот, бизнес-процесс, вебхук, сценарий — атауы әр жүйеде әртүрлі). Мәміле «Төлем» сатысына өткенде CRM бізге счёт жасау сұрауын жібереді, клиент төлегенде біз CRM-ге webhook қайтарамыз, карточка «Төленді» сатысына жылжиды. Нұсқаулық: api.qut.kz/docs/guide/crm.
Сценарий
Сатушы клиентпен келісті, мәмілені «Шот жіберу» сатысына апарды. Бұдан кейін бәрі өздігінен жүруі керек:
- клиентке төлем сілтемесі немесе Kaspi-іне счёт барады;
- сатушы «төледіңіз бе?» деп қоңырау шалмайды;
- төлем түскен сәтте карточка жылжиды, жауапты адамға хабарлама келеді;
- ай соңында есеп CRM-нің өзінде тұрады, бөлек кестеде емес.
Жұмыс схемасы қадамдап
- CRM-де триггер. Мәміле белгілі бір сатыға өткенде робот/бизнес-процесс іске қосылады.
- Счёт жасау сұрауы. CRM
POST https://api.qut.kz/api/v1/invoicesшақырады. Денесінде:amount— мәміле сомасы,description— клиент көретін мәтін,externalOrderId— мәміле нөмірі,metadata— жауапты менеджер, воронка, көз. - Жауапты сақтау. Жауапта
payUrl,qrUrl,deepLink,qrImageUrl,expiresAtкеледі.payUrl-ды мәміленің өрісіне жазып қойыңыз — сатушы оны клиентке WhatsApp немесе SMS арқылы жібереді. - Клиент төлейді. QR арқылы, сілтеме арқылы немесе
kind: "phone"таңдасаңыз — Kaspi қосымшасына келген push арқылы. - Webhook келеді. Біз сіздің адресіңізге
invoice.paidжібереміз. ІшіндеexternalOrderIdбар — сол арқылы қай мәміле екенін табасыз. - Карточка жылжиды. CRM мәмілені «Төленді» сатысына апарады, тарихқа жазба қосады.
Қандай API әдісі керек
| Қадам | Әдіс |
|---|---|
| Счёт жасау | POST /api/v1/invoices |
| Бірнеше мәмілеге бірден | POST /api/v1/invoices/bulk, 1-100 счёт |
| Күйді сұрау | GET /api/v1/invoices/{id} |
| Мәміле күшін жойса | POST /api/v1/invoices/{id}/cancel |
| Ақшаны қайтару | POST /api/v1/invoices/{id}/refund |
| Төлем туралы хабар | Webhook: invoice.paid, invoice.cancelled, invoice.expired |
Аутентификация — X-API-Key: qp_live_… тақырыбы. Кілт CRM-нің сервер жағындағы баптауында тұрсын, клиент браузерінде орындалатын скриптке салмаңыз.
Идемпоттылық — дубльден сақтайтын нәрсе
CRM-дегі роботтар қайталанып қосылады: сатушы мәмілені сатыдан сатыға бірнеше рет жылжытады, бизнес-процесс қайта іске қосылады, желі үзіліп қалады да қайталама сұрау кетеді. Нәтижесі — бір мәмілеге үш счёт.
Мұның алдын алу үшін әр сұрауға Idempotency-Key тақырыбын қосыңыз. Мәні тұрақты болсын — мысалы мәміле нөмірі мен сома біріктірілген жол. Сол кілтпен қайталасаңыз жаңа счёт жасалмайды, бұрынғысы қайтады (HTTP 200, жауапта idempotentReplay: true).
Webhook өңдеуі де идемпотентті болсын: (invoice.id, status) жұбын тексеріңіз. 2xx емес жауап берсеңіз, біз 11 рет қайталаймыз — бір төлем бойынша карточка бірнеше рет жылжымауы керек. Толығы: Идемпоттылық: қайталаудан қорғану.
Әр CRM-ге бөлек кілт
Бірнеше жүйе қатар жұмыс істесе (CRM, сайт, Telegram бот), әрқайсысына жеке API кілт жасаңыз. Себебі:
- бір кілт сыртқа шығып кетсе, тек соны жойып, қалғанын тимейсіз;
- есепте төлемнің қай көзден келгені көрінеді;
- кілтті нақты кассирге байлауға болады, сонда ол басқа кассирдің счёттарын көрмейді.
Кілттерді Интеграциялар бөлімінен жасайсыз. Толығы: API кілттер: жасау, сақтау, ауыстыру.
Кодсыз нұсқасы бар ма
Толық автоматтандыру үшін кем дегенде бір HTTP сұрау жазу керек. Бірақ аралық нұсқалар бар:
| Нұсқа | Кодсыз ба | Не болады |
|---|---|---|
| CRM-дегі «вебхук жіберу» әрекеті | Иә, батырмалармен бапталады | Счёт автоматты шығады, бірақ күйді CRM-ге қайтару үшін тағы бір қадам керек |
| n8n арқылы | Иә, визуалды редактор | CRM ↔ Qut Pay екі бағытта, дайын workflow-лар бар |
| Тұрақты төлем сілтемесі | Иә | Сатушы сілтемені қолмен жібереді, счёт өздігінен жасалмайды |
| Кабинеттен қолмен счёт | Иә | Аз көлемге жарайды, CRM-мен байланыспайды |
n8n нұсқасы көбіне ең тиімдісі: CRM-нің шығыс вебхугын n8n қабылдайды, бізге счёт жасайды, бізден келген webhook-ты қайтадан CRM API-іне жібереді. Программист керек емес.
Ерекше ескертулер
- Altegio мен МойСклад — CRM емес, жазылу және қойма жүйелері. Логикасы сол: оқиға → счёт → webhook → күй жаңарту. Altegio-да жазылу расталған сәтте депозит счётын шығару ыңғайлы.
- Bitrix24 «облако» нұсқасында шығыс сұрауға шектеу бар, роботтың орындалу жиілігін тексеріңіз.
- Сома өзгерсе ескі счётты
cancelарқылы жауып, жаңасын жасаңыз. Бір счёттың сомасын өзгерту мүмкін емес. - QR-дың сканерлеу терезесі шектеулі. Мәміле бірнеше күн тұратын болса, клиентке QR суретін емес,
payUrlсілтемесін беріңіз, бет ашылған сәтте жаңа QR көрсетеді. Нақты уақытынexpiresAtөрісінен алыңыз. - Кеш төлем болады.
expiredнемесеcancelledсчётқа ақша кейін келсе,invoice.paidоқиғасыlate: trueбелгісімен келеді. CRM-де ондай мәмілені қайта ашатын тармақ болсын. - Сынау. Алдымен sandbox кілтімен (
qp_test_…) бүкіл циклді өткізіңіз — нақты ақша жүрмейді, төлемді өзіңіз симуляциялайсыз.
Жиі қойылатын сұрақтар
Bitrix24-ке дайын қосымша бар ма? Жоқ. Маркетплейсте модуліміз жоқ, қосылу API арқылы жүреді. Нұсқаулықта дайын сұрау мысалдары берілген.
Программист керек пе? Міндетті емес. CRM-дің өз роботы HTTP сұрау жібере алса немесе n8n қолдансаңыз, кодсыз да жинауға болады. Бірақ бірінші баптау кезінде техникалық адамның болғаны жеңіл.
Бір CRM-ге бірнеше ұйым қосуға бола ма? Иә. Әр ұйымның өз кассирі мен кілті болады, CRM-де қай ұйымның кілтін қолдану керегін сатысы немесе воронкасы бойынша таңдайсыз.
Webhook келмей жатса не істеу керек? Адрес https болуы керек, нақты домен болсын, авторизациясыз ашылсын. Тексеру реті: Webhook келмей жатыр.
Менеджер бойынша есеп жасауға бола ма? Иә. metadata өрісіне менеджердің идентификаторын жазыңыз — ол webhook-та қайта келеді және экспортта көрінеді.