Внешняя REST-интеграция (API-ключ)
Внешняя REST-интеграция — это управляемая «дверь», через которую другая система (ERP, бэкенд сайта, 1С или интеграционная прослойка, собственное приложение) может создавать и обновлять задачи и сделки в LadVen OS по стандартному API с ключом доступа. При этом никто не передаёт логин и пароль и не работает под администратором.
Каждый вызов выполняется от отдельного служебного аккаунта (бота) с минимально необходимыми правами: только те действия, которые вы разрешили, и только в тех отделах, проектах, воронках и этапах, которые вы задали. Все запросы проходят обычные правила портала — доступ, проверки, автоматизацию, уведомления — и записываются в журнал, который можно посмотреть по каждой интеграции.
Подключение добавляется один раз в Хабе интеграций (раздел CRM → Интеграции, маршрут /crm/integrations).
Когда использовать
REST-интеграция нужна, когда «что-то происходит в другой системе — и в LadVen OS должна автоматически появиться задача или сделка». Типичные сценарии:
- ERP или сайт создаёт задачу или обращение, когда приходит заказ, заявка или тикет;
- собственное приложение держит задачи и сделки в синхронизации с внешней базой;
- внешняя система прикрепляет файлы, оставляет комментарии, фиксирует время или двигает сделку по этапам по мере работы на другой стороне.
Чем это отличается от форм и веб-хуков: форма сайта и веб-хук — это односторонний приём заявок в CRM. REST-интеграция — это программная двусторонняя связь: внешняя система и читает (получает задачи, сделки, историю), и пишет (создаёт и обновляет). Сам портал не рассылает исходящие веб-хуки через это подключение — внешняя сторона обращается к порталу сама.
Как настроить
Подключение создаётся пошаговым мастером (CRM → Интеграции → добавить «Внешняя REST-интеграция»). По шагам, в рабочих терминах:
- Название и активность. Дайте понятное имя интеграции и решите, включать ли её сразу. Можно сразу запустить проверку соединения.
- Служебный аккаунт. Выберите существующего бота или создайте нового прямо в мастере (имя и логин). Это не сотрудник и не администратор: интеграция работает от его имени. Если выбрать аккаунт с правами администратора, мастер предупредит — так задумано, интеграции дают минимум прав.
- Сценарий и уровень прав. Выберите набор операций под задачу: «Задачи и CRM», «Только задачи» или «Только CRM». Затем уровень прав: только чтение, создание и редактирование или управление. Права применяются к служебному аккаунту до выдачи ключа.
- Разрешённые действия. Отметьте конкретные операции, которые интеграции можно выполнять. Принцип — минимум необходимого: включайте только то, что реально нужно. Всё, что не отмечено, будет отклонено до выполнения.
- Область. Ограничьте интеграцию нужными отделами, проектами, воронками и этапами. Это рамка поверх прав аккаунта: даже разрешённое действие сработает только внутри заданной области.
- Поля и лимиты. Задайте, какие поля задач и сделок интеграция может менять, лимит запросов в минуту и допустимый всплеск, а также белый список IP-адресов, с которых разрешены вызовы.
- Создание ключа и проверка. Сохраните — портал один раз покажет ключ доступа на экране результата с кнопкой копирования. Здесь же можно запустить проверку соединения.
После создания у подключения есть журнал запросов: какие операции вызывались, с каким результатом и с подробностями по каждому вызову (чувствительные данные в записях скрыты).
Безопасность и ключ доступа
REST-интеграция построена на принципе наименьших прав — это важно для владельца бизнеса:
- Ключ показывается один раз. Скопируйте его и сразу сохраните в менеджере секретов. Портал больше не покажет этот ключ и не хранит его в открытом виде. Если ключ нужно сменить — перевыпустите его, заново пройдя мастер для этого подключения.
- Отдельный служебный аккаунт. Интеграция не работает под человеком или администратором; у неё своя зона ответственности и свои права.
- Рамки доступа. Разрешённые действия, область (отделы, проекты, воронки, этапы), белый список полей, лимит запросов и белый список IP ограничивают, что и откуда может делать интеграция.
- Журнал. Каждый вызов записан — можно разобрать, кто и что менял через интеграцию.
Никогда не показывайте на скриншотах и не публикуйте реальный ключ, заголовок авторизации, IP-адреса из белого списка или логин служебного аккаунта. Для иллюстраций используйте очевидно ненастоящие значения.
Частые ошибки
- Дать интеграции аккаунт администратора вместо служебного бота.
- Включить больше действий, чем нужно, вместо минимально необходимого набора.
- Не скопировать одноразовый ключ при создании.
- Не задать белый список IP и лимит запросов.
- Задать слишком широкую область — весь портал вместо одной нужной воронки.
- Ждать, что портал сам начнёт слать исходящие веб-хуки: интеграция работает входящими вызовами, внешняя система обращается к порталу.
Как проверить, что работает
- Запустите проверку соединения в конце мастера (или включите запуск проверки сразу).
- Убедитесь, что карточка подключения показывает активное и исправное состояние.
- Посмотрите журнал запросов — там должны быть успешные вызовы.
- Проверьте, что тестовая задача или сделка появилась с правильным ответственным, воронкой и этапом, а автоматизация и уведомления отработали как обычно.