Когда речь заходит об интеграции, звучат слова «REST», «вебхук», «токен», «плейсмент». На них обычно кивают, не понимая сути. Разберём по-человечески: это нужно не для программирования, а чтобы осмысленно ставить задачи и принимать работу.
Что ожидают и что получают
| Ожидание | Реальность |
|---|---|
| «Настроим интеграцию — и всё будет синхронизироваться» | Синхронизация — это набор правил: что, когда и в какую сторону передаётся |
| «API — это кнопка, которая всё делает» | API — это способ обратиться к системе с запросом; логику пишет человек |
| «Вебхук — то же самое, что API» | Наоборот: API вы вызываете сами, вебхук вызывает вас |
| «Один раз настроили — работает всегда» | Ломается при истечении токена, смене полей и обновлениях на другой стороне |
REST API без программирования
Представьте меню действий в ресторане. Вы не заходите на кухню — вы называете блюдо, вам приносят результат. REST API — это такое меню для программы: список адресов, по которым можно попросить систему что-то сделать или что-то отдать.
- Адрес (endpoint) — конкретное действие: создать сделку, получить список задач, обновить контакт.
- Метод — что именно делаем: создать, прочитать, изменить, удалить.
- Данные запроса — то, что передаём: название сделки, сумма, ответственный.
- Ответ — что вернула система: созданный объект или сообщение об ошибке.
Пример: пришла заявка с сайта. Программа обращается к API Битрикс24 с данными клиента и получает в ответ номер созданной сделки. Дальше с этой сделкой работают менеджеры — как с обычной.
Чем вебхук отличается от запроса
| Запрос к API | Вебхук | |
|---|---|---|
| Кто начинает | Ваша программа обращается к Битрикс24 | Битрикс24 обращается к вашему адресу |
| Когда | Когда нужно вам — по расписанию или по событию | Когда произошло событие на стороне системы |
| Что нужно | Токен и знание методов | Публичный адрес, который примет данные |
| Чем полезен | Забрать данные, создать объект | Мгновенно узнать о новом событии |
| Где ломается | Истёк токен, неверные поля | Адрес недоступен, ответ долгий, повторы |
Практический вывод: чтобы «заявка с сайта сразу попадала в CRM», нужен входящий вебхук или интеграция через REST. Чтобы «каждую ночь выгружать сделки в 1С» — запросы по расписанию. Подробнее о приёме заявок — в статье сайт и CRM.
Токены: главный источник тихих сбоев
Токен — это пропуск. Пока он действует, интеграция работает; когда истекает, обмен прекращается. Обычно без громкой ошибки: заявки просто перестают приходить.
- Входящий вебхук — постоянный адрес с ключом. Фактически это пароль в ссылке: кто увидел — тот имеет доступ.
- Refresh-токен приложения — обновляется автоматически, но у него есть срок жизни (в Битрикс24 — 180 дней бездействия, а access-токен живёт час).
- Права. Токен может быть с доступом ко всей CRM или только к задачам — это задаётся при создании.
- Хранение. Не в переписке и не в коде на виду: пароли и доступы.
Простая привычка, которая экономит недели: у каждой интеграции есть владелец и календарное напоминание «проверить обмен» раз в месяц.
Как выглядит нормальная схема обмена
Любая рабочая интеграция состоит из четырёх частей, и если хотя бы одной нет — она рано или поздно встанет:
- Событие. Понятно, что запускает обмен: новая заявка, изменение статуса, время по расписанию.
- Передача. Данные уходят по адресу — с токеном, в нужном формате, с ограничением частоты.
- Проверка. Система-получатель подтверждает приём, а не молчит.
- Реакция на сбой. Повтор, уведомление владельцу, запись в журнал.
Частая ошибка — считать пункт четыре необязательным. Интеграция без обработки ошибок выглядит рабочей ровно до первого истечения токена.
Почему интеграция «молча падает»
- Истёк токен — обмен остановился, ошибок никто не увидел.
- Изменилось поле — например, стадия переименована, а правило ищет старое название.
- Превышен лимит запросов — система отвечает отказом на часть вызовов, данные теряются частями.
- Таймаут — внешняя система отвечает дольше, чем ждёт интеграция.
- Кодировка и формат — суммы с запятой вместо точки, даты в другом формате.
- Права — новый сотрудник не тот, от чьего имени идёт обмен.
- Дубли и повторы — вебхук отправлен дважды, и в CRM две одинаковые заявки.
Коды ответов: что они значат
| Код | Что означает | Что делать |
|---|---|---|
| 200 | Успех | Ничего, но проверить, что данные действительно появились |
| 400 | Неверный запрос | Проверить состав и формат полей |
| 401 | Не авторизован | Токен удалён, истёк или отозван |
| 403 | Нет прав | Проверить права пользователя или токена |
| 429 | Слишком много запросов | Ввести ограничение и повтор с задержкой |
| 500 | Ошибка на стороне системы | Повтор, логи, обращение к вендору |
Важно понимать: код 200 не гарантирует, что данные дошли куда надо. Поэтому в нормальной интеграции есть журнал: сколько отправлено, сколько принято, сколько восстановлено.
Как проверять интеграцию
- Тестовый портал — прогонять сценарии до боевого запуска.
- Журнал обмена — запись каждого запроса и ответа, с датой и результатом.
- Контрольные цифры — например, число заявок на сайте и число сделок в CRM за день.
- Оповещение — если обмен не прошёл N раз подряд, приходит уведомление, а не выясняется через месяц.
- Ручной повтор — возможность перезапустить обработку конкретной записи.
Что спрашивать у подрядчика
- Что именно передаётся, в какую сторону и с какой частотой?
- Что происходит при ошибке: повтор, уведомление или тишина?
- Где хранится токен и кто имеет к нему доступ?
- Как проверяется, что данные дошли (какие контрольные цифры)?
- Что будет при обновлении внешней системы?
- Кто владелец интеграции после запуска?
Что зафиксировать в договоре
- Схему обмена: системы, направления, события, частота.
- Правила обработки ошибок и сроки реакции.
- Журнал и оповещения — как часть результата, а не «пожелание».
- Передачу токенов и доступов заказчику с инструкцией.
- Тестовый контур и порядок переноса на боевой.
- Границы: что не входит — например, изменения на стороне внешнего сервиса.
Частые вопросы
Нужен ли программист, чтобы настроить вебхук?
Для входящего вебхука — нет, достаточно создать его в интерфейсе и передать ссылку. Для обработки данных на другой стороне — обычно да.
Чем вебхук опасен?
Он даёт доступ по ссылке: кто её получил, тот может читать и менять данные в рамках прав. Поэтому ссылки не пересылают в чатах и не хранят в открытых файлах.
Можно ли обойтись без интеграции?
Иногда да — через экспорт и импорт вручную. Но если операция повторяется ежедневно, ручной обмен почти всегда дороже и с ошибками.
Почему интеграция работает, а отчёты не сходятся?
Обычно расходится логика: разные стадии, дубли, часть записей не прошла. Начинать нужно с контрольных цифр за день.
Сколько времени занимает интеграция?
Простой приём заявок с сайта — от одного дня. Обмен с 1С по номенклатуре и документам — от пяти рабочих дней.
Кто должен следить за обменом после запуска?
Администратор портала или подрядчик по договору поддержки. Без владельца интеграции «молча падают» именно потому, что следить некому.
Что сделать на этой неделе
- Выпишите все внешние системы, с которыми обменивается ваш портал.
- По каждой отметьте, что передаётся и с какой частотой.
- Проверьте, есть ли журнал обмена и кто его смотрит.
- Узнайте, когда последний раз меняли токены и кто ими владеет.
- Сверьте контрольные цифры за прошлый день: заявки на сайте против сделок в CRM.
Интеграция — это не «связь между системами», а набор правил: какое событие, в какую сторону, с какими данными и что делать, если не получилось.
