Интеграция DLE со сторонними сервисами без лишних ошибок

Интеграция DLE с CRM, платёжным сервисом или рассылкой часто начинается с правки файлов движка, а заканчивается потерянными заявками, дублями заказов и обновлением, после которого сайт перестаёт отправлять данные. Для DLE 17.x безопаснее сначала определить границу между CMS и внешней системой, а уже потом выбирать способ обмена: готовое расширение, отдельный обработчик, планировщик или прямое чтение базы. Ниже — практическая схема, которая помогает не переделывать интеграцию после первого сбоя.

Сначала опишите событие, а не сервис

Ошибка большинства интеграций начинается с формулировки «подключим CRM». Это слишком широко. CRM может получать новую заявку, обновлять статус, создавать контакт или только забирать статистику. Для каждого действия нужны разные права, формат данных и обработка ошибок.

Составьте короткую карту обмена:

• событие: что произошло в DLE — опубликована статья, отправлена форма, изменён профиль или создан заказ;
• источник: где появляется достоверное значение — в форме сайта, базе DLE или внешнем сервисе;
• получатель: какая система должна принять данные;
• результат: что считается успехом — HTTP-ответ, созданная запись или изменение статуса;
• повтор: что произойдёт, если запрос придёт дважды или внешний сервис будет недоступен.

Например, «новая заявка с сайта уходит в CRM» — это ещё не спецификация. Нужно решить, какие поля обязательны, кто назначает идентификатор заявки, можно ли отправлять персональные данные и как оператор узнает о неудачной доставке.

Четыре способа связать DLE с внешней системой

У DLE нет универсального встроенного REST-слоя, который одинаково подходит для любой задачи и любой установки. Возможности зависят от версии, шаблона, установленных модулей и того, какие точки расширения предоставляет конкретное решение. Поэтому не закладывайте в архитектуру название функции или путь к файлу, пока не проверили их в документации и на тестовой копии.

Главное правило для DLE: внешняя интеграция должна переживать обновление CMS без редактирования ядра и повторную доставку одного события без создания дубля.

Идемпотентность¹ означает, что повторная обработка одного и того же события не меняет результат. Для заявки это может быть проверка по внешнему идентификатору, а для обновления статьи — запись с тем же ключом вместо создания второй записи.

Готовое расширение

Выбирайте его, если сценарий стандартный и у модуля есть совместимость с вашей версией DLE, дата обновления и понятный способ отключения. До установки проверьте, какие файлы он меняет, где хранит ключи, пишет ли ошибки в журнал и что происходит при ответе внешнего сервиса с кодом 4xx или 5xx.

Не ставьте модуль сразу на рабочий сайт. Сделайте копию файлов и базы, установите расширение на тестовый домен и проверьте удаление: после деактивации не должны оставаться незакрытые обработчики, фоновые задания и открытые точки входа.

Отдельный обработчик

Это лучший вариант, если нужно связать несколько систем или преобразовать данные по своим правилам. Обработчик может принимать событие, проверять подпись, сохранять исходное тело запроса и ставить задачу на отправку в CRM. Логику не стоит прятать в шаблоне: шаблон отвечает за вывод страницы, а не за доставку критичных данных.

Если обработчик размещён внутри сайта, ограничьте его назначение и права. Если интеграция важна для бизнеса, отдельный небольшой сервис рядом с DLE обычно проще обновлять и тестировать. В любом случае не храните секреты в шаблоне, открытом JavaScript и репозитории.

Планировщик и очередь

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

У задачи должны быть статус, число попыток, время следующей попытки и текст последней ошибки. Повторяйте запросы только для временных сбоев. Ошибка авторизации, неправильный формат поля или удалённый объект требуют исправления данных, а не бесконечных повторов.

Прямой доступ к базе

Прямое чтение может быть приемлемым для отчётной витрины, если подключение имеет права только на чтение и запросы не мешают рабочей базе. Запись напрямую в таблицы DLE — крайняя мера. Вы можете обойти валидацию, не обновить связанное поле, сломать кэш или потерять совместимость при обновлении.

Если внешней системе нужно менять данные в DLE, ищите штатный механизм расширения или оформляйте операцию через слой, который понимает правила CMS. Название таблицы не означает, что она является публичным интерфейсом.

Что проверить до первого боевого запроса

1. Зафиксируйте контракт. Запишите поля, типы значений, обязательность, допустимые статусы и кодировку. Проверка: два разработчика независимо описывают один и тот же JSON без расхождений.
2. Разделите тестовые и боевые ключи. Проверьте, что тестовая заявка не попадает в настоящий отдел продаж и что секрет не отображается в HTML. Проверка: ключ из тестовой среды не даёт доступа к боевой.
3. Добавьте идентификатор события. Он должен сохраняться в журнале и передаваться получателю. Проверка: повтор одного запроса находится по тому же идентификатору и не создаёт вторую сущность.
4. Настройте тайм-аут и повтор. Не оставляйте запрос без ограничения времени и не повторяйте любой ответ подряд. Проверка: при остановленном внешнем сервисе сайт не зависает, а задача получает понятный статус ошибки.
5. Сохраните безопасный журнал. Логируйте время, событие, статус, длительность и идентификатор, но не пароль, токен и полные персональные данные. Проверка: по журналу можно восстановить маршрут заявки без раскрытия секрета.
6. Проведите отрицательные тесты. Отправьте пустое обязательное поле, повторите событие, отключите внешний сервис и передайте просроченную подпись. Проверка: система не создаёт дубли и сообщает об ошибке администратору.

Авторизация и вебхуки: где чаще всего ломается защита

Для исходящих запросов используйте секрет, который хранится на сервере и доступен только процессу интеграции. Для входящих вебхуков проверяйте подпись или другой механизм, предусмотренный поставщиком сервиса. Сам URL обработчика не является защитой: его могут найти в логах, истории браузера или документации проекта.

Проверяйте не только подпись, но и время запроса, формат тела, размер сообщения и допустимые события. Ограничение по IP полезно лишь тогда, когда поставщик публикует стабильный список адресов и вы готовы его обновлять.

Не отвечайте внешнему сервису «успешно» до сохранения события. Иначе отправитель прекратит повторы, а запись останется потерянной. Но и не выполняйте долгую синхронизацию до ответа: сначала безопасно примите событие, затем обработайте его отдельным заданием, если это допускает сценарий.

Что ломается первым

• Дубли. Пользователь дважды нажал кнопку или сервис повторил вебхук. Решение — уникальный внешний идентификатор и проверка перед созданием записи.
• Разные статусы. В DLE используется одно значение, в CRM другое. Составьте явную таблицу соответствий, а неизвестный статус отправляйте в ошибку, а не превращайте молча в «новый».
• Кириллица и даты. Стороны могут ожидать разные форматы даты, часовые пояса и кодировку. Храните время с указанием часового пояса и приводите формат на границе системы.
• Слишком большие ответы. Выгрузка всего каталога одним запросом упирается в память и тайм-аут. Используйте страницы, ограничение полей и отметку последнего обработанного объекта.
• Обновление DLE. Правка ядра исчезает при замене файлов. Храните изменения в расширении или отдельном сервисе, а перед обновлением прогоняйте тестовый сценарий на копии.

Когда выбирать какой подход

Берите готовый модуль, если он поддерживает вашу ветку DLE и закрывает ровно нужный сценарий. Отдельный обработчик выбирайте, когда бизнес-правила важнее скорости запуска или участвуют несколько получателей. Очередь нужна там, где потеря события дороже задержки в несколько минут. Прямое чтение базы оставляйте для отчётности и не используйте как универсальный способ управления контентом.

Инвалидация кэша и синхронизация медиафайлов — отдельные задачи: здесь рассматривается только обмен событиями и данными.

Что делать дальше

Создайте тестовый экземпляр DLE той же ветки 17.x, что работает на продакшене, и опишите один сценарий от начала до конца: например, отправка формы, создание заявки, повтор события и недоступность CRM. После запуска смотрите не только на HTTP-коды, но и на долю необработанных событий, возраст самой старой задачи, число повторов и расхождение записей между системами.

Перед обновлением DLE сохраните резервную копию, проверьте расширения и повторите этот сценарий. Если интеграция влияет на оплату, заявки или персональные данные, добавьте отдельный журнал аудита и определите ответственного за разбор ошибок.

¹ Идемпотентность — свойство операции сохранять тот же результат при повторном выполнении с теми же исходными данными.