# CRM жүйесіне қосу

> Bitrix24, amoCRM, Kommo, Altegio, МойСклад — дайын модуль жоқ, бірақ CRM сыртқа HTTP сұрау жібере алса жеткілікті. Мәміле төлем сатысына өткенде счёт шығады, төленгенде карточка өзі жылжиды.

## Қысқаша

Bitrix24, amoCRM, Kommo, Altegio, МойСклад — бұлардың ешқайсысына дайын модулімізде жоқ, қосылу API арқылы жүреді. Талап бір ғана: CRM сыртқа HTTP сұрау жібере алсын (робот, бизнес-процесс, вебхук, сценарий — атауы әр жүйеде әртүрлі). Мәміле «Төлем» сатысына өткенде CRM бізге счёт жасау сұрауын жібереді, клиент төлегенде біз CRM-ге webhook қайтарамыз, карточка «Төленді» сатысына жылжиды. Нұсқаулық: [api.qut.kz/docs/guide/crm](https://api.qut.kz/docs/guide/crm).

## Сценарий

Сатушы клиентпен келісті, мәмілені «Шот жіберу» сатысына апарды. Бұдан кейін бәрі өздігінен жүруі керек:

- клиентке төлем сілтемесі немесе Kaspi-іне счёт барады;
- сатушы «төледіңіз бе?» деп қоңырау шалмайды;
- төлем түскен сәтте карточка жылжиды, жауапты адамға хабарлама келеді;
- ай соңында есеп CRM-нің өзінде тұрады, бөлек кестеде емес.

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

1. **CRM-де триггер.** Мәміле белгілі бір сатыға өткенде робот/бизнес-процесс іске қосылады.
2. **Счёт жасау сұрауы.** CRM `POST https://api.qut.kz/api/v1/invoices` шақырады. Денесінде: `amount` — мәміле сомасы, `description` — клиент көретін мәтін, `externalOrderId` — мәміле нөмірі, `metadata` — жауапты менеджер, воронка, көз.
3. **Жауапты сақтау.** Жауапта `payUrl`, `qrUrl`, `deepLink`, `qrImageUrl`, `expiresAt` келеді. `payUrl`-ды мәміленің өрісіне жазып қойыңыз — сатушы оны клиентке WhatsApp немесе SMS арқылы жібереді.
4. **Клиент төлейді.** QR арқылы, сілтеме арқылы немесе `kind: "phone"` таңдасаңыз — Kaspi қосымшасына келген push арқылы.
5. **Webhook келеді.** Біз сіздің адресіңізге `invoice.paid` жібереміз. Ішінде `externalOrderId` бар — сол арқылы қай мәміле екенін табасыз.
6. **Карточка жылжиды.** 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 рет қайталаймыз — бір төлем бойынша карточка бірнеше рет жылжымауы керек. Толығы: [Идемпоттылық: қайталаудан қорғану](/kb/idempotency).

## Әр CRM-ге бөлек кілт

Бірнеше жүйе қатар жұмыс істесе (CRM, сайт, Telegram бот), әрқайсысына жеке API кілт жасаңыз. Себебі:

- бір кілт сыртқа шығып кетсе, тек соны жойып, қалғанын тимейсіз;
- есепте төлемнің қай көзден келгені көрінеді;
- кілтті нақты кассирге байлауға болады, сонда ол басқа кассирдің счёттарын көрмейді.

Кілттерді [Интеграциялар](https://qut.kz/app) бөлімінен жасайсыз. Толығы: [API кілттер: жасау, сақтау, ауыстыру](/kb/api-keys).

## Кодсыз нұсқасы бар ма

Толық автоматтандыру үшін кем дегенде бір 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 келмей жатыр](/kb/webhook-not-arriving).

**Менеджер бойынша есеп жасауға бола ма?** Иә. `metadata` өрісіне менеджердің идентификаторын жазыңыз — ол webhook-та қайта келеді және экспортта көрінеді.