# CACR Отправка заявок с сайта в Мессенджер MAX - Установка и работа

## 1. Что делает плагин

`cacr-relay-cf7-max` ставится на клиентский WordPress-сайт, перехватывает заявки из Contact Form 7 и других форм (если они отправляют email через `wp_mail`, включая отправку из форм сайта через `wp-admin/admin-post.php`) и отправляет их **только через портал `cacr.ru`**.

Актуальные возможности, которые стоит указывать при публикации:
- отправка заявок в MAX в личные сообщения, приватные чаты и группы;
- для групповых чатов можно включить кнопку «Принять заявку», чтобы в сообщении было видно, кто взял заявку и во сколько;
- настройка получателя выполняется в кабинете CACR, а на сайте хранится только ключ интеграции;
- как допуслуга может быть включена маршрутизация заявок по формам и полям формы без создания нескольких ключей на одном сайте;
- тестовая отправка заявки из настроек для проверки цепочки сайт -> CACR -> MAX;
- передача только лидов (системные письма WordPress отфильтровываются);
- поддержка Contact Form 7 и любых форм сайта, которые отправляют через `wp_mail`.

Поток:
1. Плагин отправляет лид на `https://cacr.ru/wp-json/mb/v1/max-cf7/lead`.
2. Портал проверяет ключ интеграции, домен и лицензию.
3. Портал отправляет заявку в выбранный получатель MAX: личные сообщения, приватный чат или группа.
   - Если для интеграции включены правила маршрутизации, сначала проверяются они.
   - Если ни одно правило не совпало или у правила не настроен свой получатель, используется получатель по умолчанию.
4. Служебные письма WordPress (комментарии, обновления и системные уведомления) в relay не попадают (фильтрация по контексту запроса + теме/телу письма).
5. Один и тот же MAX-аккаунт или один и тот же приватный чат можно использовать сразу для нескольких сайтов: каждый сайт привязывается своим bind-кодом.

## 2. Ключ интеграции (важно)

Ключ интеграции генерируется **в кабинете CACR**, а не на клиентском сайте.

Правильный порядок:
1. Войти в кабинет: `https://cacr.ru/cabinet/bots/max_cf7/`.
2. На странице бота `max_cf7` создать подключение для домена сайта.
   - Подключение можно создать сразу, без предварительной оплаты.
   - Сначала выполняется настройка подключения, затем оплата и активация.
3. Выполнить bind получателя и `Пинг` сайта.
   - Если подписка еще не оплачена, успешный `Пинг` подтвердит связь с сайтом, но подключение останется в `draft` до оплаты и активации.
4. В блоке подписки оплатить тариф `max_cf7`.
   - Платежи подписки `max_cf7` идут через отдельный боевой YooKassa shop `1277064` (не общий с Telegram-ботами).
   - Первый платеж сохраняет способ оплаты в YooKassa и включает автопродление по умолчанию (если метод поддерживает рекуррентные списания).
   - Лимит подключений: `1 активная подписка = 1 сайт`.
5. После оплаты перевести подключение в рабочий режим (`status = active`) и выполнить проверку доставки.
6. Получить `site_token` (ключ интеграции): для `max_cf7` он создается автоматически при создании подключения, перевыпуск делается кнопкой `Новый ключ`.
7. При необходимости в разделе `Интеграции` проверить, что подключение отображается в списке подключенных интеграций.
   - Кнопка `Пинг` проверяет только связь кабинета с сайтом клиента.
   - Кнопка `Тестовая заявка` отправляет диагностическое сообщение в уже привязанного получателя MAX.
8. Вставить этот ключ в настройки плагина на клиентском сайте.

Автопривязка получателя:
1. После создания подключения на странице `max_cf7` кабинет сразу покажет код привязки; при необходимости в строке подключения можно нажать `Код привязки` повторно.
2. Для лички отправить боту команду вида `/bind XXXXXXXX`.
3. Для приватного чата добавить бота в чат и отправить в этом чате команду `/bindchat XXXXXXXX`.
4. Портал автоматически зафиксирует получателя (обычно в течение 1 минуты).
5. Если несколько сайтов должны слать заявки в одну личку или одну группу, повторите bind для каждого подключения сайта отдельно.

## 3. Установка на сайт клиента

1. Скопировать папку `cacr-relay-cf7-max` в `/wp-content/plugins/` и убедиться, что bootstrap-файл называется `cacr-relay-cf7-max.php`.
2. Активировать плагин в админке WordPress.
3. Открыть `Настройки -> CACR Отправка заявок с сайта в Мессенджер MAX`.
4. Вставить `Ключ интеграции (из кабинета CACR)`.
5. Настроить получателя (личка / приватный чат / группа) в кабинете CACR.
6. Проверить отправку через кнопку `Отправить тестовую заявку в MAX` в настройках плагина.
7. Нажать `Проверить ключ и лицензию`.

Примечание:
- в клиентском плагине нет переключателя отключения передачи лидов;
- при наличии валидного ключа отправка выполняется только через `cacr.ru`.
- Contact Form 7 не является обязательным: если форма не CF7, но отправляет письмо через `wp_mail`, лид тоже будет передан.
- Поддерживаются формы сайта на `admin-post.php`; отправки `admin-post.php` из админки WordPress в relay не попадают.
- Если планируется маршрутизация заявок по скрытому полю `route_key`, для generic mail-потока это поле должно присутствовать в теле письма, иначе портал не сможет использовать его в условиях.

## 3.1. Допуслуга: маршрутизация заявок внутри одного сайта

Рекомендуемая модель:
- `1 сайт = 1 интеграция = 1 ключ`.
- В кабинете CACR у интеграции остается текущий получатель по умолчанию.
- Дополнительно включаются правила маршрутизации, которые направляют отдельные формы в другие MAX чаты/группы/аккаунты.

Поддерживаемые признаки для маршрутизации:
- `source` (`cf7` или `generic_mail_form`);
- `form_id`;
- `form_title`;
- `page_url`;
- поля формы (`fields.*`), например `route_key`, `service`, `department`.

Рекомендуемая практика:
1. Для CF7 использовать `form_id` или hidden-поле `route_key`.
2. Для кастомных форм через `wp_mail` добавлять `route_key` в форму и в шаблон письма.
3. Использовать правила только для исключений, а основную доставку держать на получателе по умолчанию.
4. Всегда оставлять fallback на получателя по умолчанию.

## 4. Проверка лицензии

- Плагин проверяет лицензию через `cacr.ru`.
- Если подписка неактивна/неоплачена, отправка лидов блокируется.
- На странице `https://cacr.ru/cabinet/bots/max_cf7/` можно:
  - оплатить подписку,
  - увидеть статус и даты действия (`с` / `до`),
  - увидеть лимит сайтов и текущее количество подключений,
  - включить/выключить автопродление,
  - отключить автопродление (доступ сохранится до конца оплаченного периода).
- Кнопка ручной сверки `Проверить оплату` в пользовательском UI не используется; статус обновляется сервером (webhook + reconcile).
- Если интеграция превышает лимит сайтов, проверка лицензии вернет `reason = site_limit_exceeded`, и отправка лидов будет заблокирована.
- Для QA можно временно включить bypass на портале: `Settings` -> `MAX CF7 Test Mode`.
- В админке отображаются даты действия лицензии:
  - `Действует с` (`valid_from`)
  - `Действует до` (`valid_until`)

## 5. Диагностика

- Включите `Debug лог` в настройках плагина.
- Проверьте `php error_log` на сообщения с префиксом `[mb-max-cf7-relay]`.
- Для проверки связи из кабинета используется endpoint сайта клиента: `POST /wp-json/mb/v1/integration/ping`.
- Если подписка еще не оплачена, успешный `Пинг` подтверждает связь с сайтом, но не запускает рабочую отправку лидов до активации подключения.
- Для проверки полного сценария после оплаты и bind в кабинете `CACR -> /cabinet/bots/max_cf7/` используйте отдельную кнопку `Тестовая заявка`.
- Для проверки полной цепочки (плагин -> CACR -> MAX) используйте кнопку `Отправить тестовую заявку в MAX` в настройках плагина.
- Если лид из нестандартной формы не уходит, проверьте, что форма реально вызывает `wp_mail`, отправляется из `POST`-запроса и не инициируется из `/wp-admin/`.