Цель интеграции

Односторонняя связь Telegram-бота с CRM: обеспечить гарантированную доставку заявок с полным контекстом анкеты и исключением дублей.

Основные требования

• Надёжность и дроп-безопасность:
  • Использовать механизм очереди с автоматическими повторными попытками (ретраи).
  • Политика повторных попыток: через 1 мин, 5 мин, 15 мин, 60 мин (8 попыток).
• Защита от дублей:
  • Поиск контакта в CRM сначала по номеру телефона (обязательно), при отсутствии - по идентификатору в Telegram (telegram_user_id).
  • Контроль идемпотентности: на основе поля submission_id хранить ссылку на созданную сделку. При повторной отправке - не создавать дубликат, а догружать недостающие шаги.

Обязательный функционал интеграции

• Авторизация (OAuth2):
  • Поддержка токенов доступа и обновления.
  • Хранение токенов в базе данных и/или защищённых секретах.
  • Автоматическое обновление токена при устаревании.
• Работа с контактами:
  • Создание нового либо обновление существующего.
  • Фиксировать имя, номер телефона (формат E.164), идентификатор и ник в Telegram.
• Создание сделки:
  • Если у контакта есть активная сделка - дополнить её созданной заметкой "Повторная заявка".
  • Если активных сделок нет - создать новую с корректными: воронка, статус, ответственный сотрудник, кастомные поля.
• Связывание: контакт обязателен для сделки (создать связь, если отсутствует).
• Заметки (notes):
  • Создать заметку с типом "Анкета Telegram".
  • Заметка должна содержать полный слепок переданных данных (анкета, UTM-метки).
• Задачи (tasks):
  • Создать задачу "Связаться" для ответственного менеджера с дедлайном, рассчитанным по стандартному соглашению об уровне обслуживания (SLA).
  • Привязать задачу к соответствующей сделке и контакту.

Данные, передаваемые из бота (lead payload)

Событие срабатывает после прохождения пользователем квиза и валидации номера телефона (нажатие кнопки "Отправить заявку"). Пейлоад содержит:

• уникальный идентификатор отправки (submission_id)
• дата и время создания (created_at)
• идентификатор/юзернейм Telegram (telegram_user_id / username)
• номер телефона в международном формате E.164 (phone)
• имя пользователя (name)
• ответы квиза (тип визуала, площадь, сезонность, срок, бюджет, локация, дополнительные опции, комментарий)
• UTM-метки заявки.

Обработка ошибок и логирование

• 401/403 - Ошибка авторизации - выполнить процедуру обновления токена и повторить запрос.
• 429 - Превышение лимита (требуется пауза); 5xx и тайм-ауты - помещать в начало планировщика на повтор согласно политике ретрая (см. п. Надёжность).
• 4xx - Ошибки валидации зарпоса - немедленный алерт администратору, т.к. это свидетельство технической ошибки интеграции.
• Логирование: сохранять полный URL точки доступа (endpoint), полученный HTTP-код, краткое описание ошибки (обязательно с маскировкой персональных данных), объект запроса/ответа (без ПДн).
• Алерты: неудачные повторы и ошибки валидации доводятся до DevOps / разработчика через настроенные каналы (Telegram/email/Slack).

Критерии приёмки (Acceptance Criteria)

• При получении заявки от пользователя создаётся или обновляется контакт в CRM.
• Для контакта создаётся или дополняется сделка.
• Контакты привязаны к сделке.
• У сделки появляется заметка и задача на менеджера.
• Повторное нажатие той же заявки (с одинаковым submission_id) не создаёт новых сущностей - находится и обновляется запись-дубль без создания дублирующих задач/заметок.
• Аварий надёжности: при сбое старой задачи (темпоральной недоступности или плановом обслуживании) очередная заявка из очереди в конечном счёте доставляется после повторных попыток (максимум установка лимита 8).
• Токены OAuth2 автоматически обновляются по истечению.