# Подключить свою CRM

> Bitrix24, amoCRM, Kommo, Altegio, МойСклад — готового модуля нет, подключение идёт через API. Достаточно, чтобы CRM умела отправлять HTTP-запрос наружу. Сделка переходит на стадию оплаты — выставляется счёт.

## Коротко

Готового модуля для Bitrix24, amoCRM, Kommo, Altegio и МойСклад у нас нет — подключение делается через API. Требование одно: CRM должна уметь отправлять HTTP-запрос наружу (робот, бизнес-процесс, исходящий вебхук, сценарий — называется в каждой системе по-своему). Сделка переходит на стадию «Оплата» — CRM отправляет нам запрос на создание счёта. Клиент платит — мы возвращаем вебхук, карточка сама уезжает на стадию «Оплачено». Инструкция: [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"`, через push в приложении Kaspi.
5. **Приходит вебхук.** Мы отправляем на ваш адрес `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` |
| Узнать об оплате | Вебхук: `invoice.paid`, `invoice.cancelled`, `invoice.expired` |

Авторизация — заголовок `X-API-Key: qp_live_…`. Ключ должен лежать в серверной части CRM, не в скрипте, который выполняется в браузере клиента.

## Идемпотентность — то, что спасает от дублей

Роботы в CRM срабатывают повторно: менеджер двигает сделку туда-сюда, бизнес-процесс перезапускается, обрывается сеть и запрос уходит второй раз. Результат — три счёта на одну сделку.

Чтобы этого не было, добавляйте к каждому запросу заголовок `Idempotency-Key`. Значение должно быть устойчивым — например, номер сделки вместе с суммой. При повторе с тем же ключом новый счёт не создаётся, возвращается прежний (HTTP 200, в ответе `idempotentReplay: true`).

Обработка вебхука тоже должна быть идемпотентной: проверяйте пару `(invoice.id, status)`. Если вы ответите не 2xx, мы повторим доставку 11 раз — карточка не должна проехать по воронке несколько раз из-за одной оплаты. Подробнее: [Идемпотентность: защита от дублей](/kb/ru/idempotency).

## Отдельный ключ на каждую CRM

Если параллельно работают несколько систем (CRM, сайт, Telegram-бот), заведите каждой свой API-ключ. Причины:

- если один ключ утечёт, вы удалите только его и не тронете остальные;
- в отчётах видно, из какого источника пришла оплата;
- ключ можно привязать к конкретному кассиру — тогда он не увидит счета других кассиров.

Ключи создаются в разделе [Интеграции](https://qut.kz/app). Подробнее: [API-ключи: создание, хранение, ротация](/kb/ru/api-keys).

## Есть ли вариант без кода

Для полной автоматизации нужно написать хотя бы один HTTP-запрос. Но есть промежуточные варианты:

| Вариант | Без кода | Что получается |
|---|---|---|
| Действие «отправить вебхук» в CRM | Да, настраивается кнопками | Счёт выставляется автоматически, но для возврата статуса в CRM нужен ещё один шаг |
| Через n8n | Да, визуальный редактор | CRM ↔ Qut Pay в обе стороны, есть готовые workflow |
| Постоянная ссылка на оплату | Да | Менеджер отправляет ссылку вручную, счёт сам не создаётся |
| Счёт вручную из кабинета | Да | Подходит при небольшом объёме, с CRM не связано |

Вариант с n8n чаще всего оказывается самым практичным: n8n принимает исходящий вебхук CRM, создаёт у нас счёт, а наш вебхук отправляет обратно в API вашей CRM. Программист не нужен.

## Особые замечания

- **Altegio и МойСклад** — не CRM, а системы записи и склада. Логика та же: событие → счёт → вебхук → обновление статуса. В Altegio удобно выставлять счёт на депозит в момент подтверждения записи.
- **У облачного Bitrix24** есть ограничения на исходящие запросы, проверьте частоту срабатывания робота.
- **Если сумма изменилась**, закройте старый счёт через `cancel` и создайте новый. Менять сумму у существующего счёта нельзя.
- **Окно сканирования QR ограничено.** Если сделка живёт несколько дней, отправляйте клиенту не картинку QR, а ссылку `payUrl` — страница покажет свежий QR в момент открытия. Точное время берите из поля `expiresAt`.
- **Поздние оплаты случаются.** Если деньги по счёту `expired` или `cancelled` придут позже, событие `invoice.paid` придёт с признаком `late: true`. Предусмотрите в CRM ветку, которая переоткрывает такую сделку.
- **Тестируйте.** Сначала прогоните весь цикл на ключе песочницы (`qp_test_…`) — реальные деньги не двигаются, оплату вы симулируете сами.

## Вопросы и ответы

**Есть ли готовое приложение для Bitrix24?** Нет. В маркетплейсе нашего модуля нет, подключение идёт через API. В инструкции есть готовые примеры запросов.

**Нужен ли программист?** Не обязательно. Если робот вашей CRM умеет отправлять HTTP-запрос или вы используете n8n, всё собирается без кода. Но на первой настройке с техническим человеком проще.

**Можно ли подключить несколько организаций к одной CRM?** Да. У каждой организации свой кассир и свой ключ, а какой ключ использовать — выбираете по стадии или воронке.

**Что делать, если вебхук не приходит?** Адрес должен быть на `https`, на реальном домене и открываться без авторизации. Порядок проверки: [Вебхук не приходит](/kb/ru/webhook-not-arriving).

**Можно ли строить отчёт по менеджерам?** Да. Запишите идентификатор менеджера в `metadata` — он вернётся в вебхуке и будет виден в выгрузке.