Интеграция сайта и Telegram с amoCRM: заявка → сделка и контакт, поиск существующего клиента, защита от дублей, очередь при сбоях, уведомления менеджерам

Описание

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

За основу взял открытую Python-библиотеку для API amoCRM Krukov/amocrm_api (110 звёзд на GitHub) и сделал на ней готовый сервис приёма заявок, а заодно доработал саму библиотеку.

Решение

Сделал сервис на FastAPI: форма сайта отправляет заявку, а сервис приводит телефон к одному виду, ищет клиента в amoCRM по телефону и e-mail (с проверкой, потому что поиск amoCRM нечёткий), привязывает новую сделку к существующему контакту или создаёт сделку вместе с контактом одним запросом. К сделке добавляется примечание с комментарием, страницей и UTM-метками рекламы, тег источника. Менеджеры сразу получают уведомление в Telegram со ссылкой на сделку. Сделал и бот-форму в Telegram: имя, телефон кнопкой «Поделиться номером», задача.

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

Доработал библиотеку: повтор запросов при превышении лимита amoCRM (7 запросов в секунду), сбоях сервера и обрыве связи, обновление токена заранее, поддержка международной версии Kommo. Исправил ошибки оригинала, в том числе падение установки на Windows. 37 новых тестов плюс 12 тестов оригинала.

Результат

Готовая интеграция «сайт и Telegram → amoCRM», которая не теряет заявки, не плодит дубли клиентов и сделок и сразу сообщает менеджерам. Подключается к любому сайту одной строкой в форме.

Проект — открытый форк с сохранением лицензии MIT. Живого аккаунта amoCRM при разработке не было: проверка шла на имитации API, повторяющей форматы официальной документации, — это честно указано в README.