Интеграция DLE с внешними сервисами: ошибки без сюрпризов

Интеграция DLE с CRM, платежами, почтой или Telegram может выглядеть как несколько строк PHP, но сбой в одной из них приводит к потерянным заявкам, дублям заказов и заблокированным ключам. Ниже — практический разбор для DataLife Engine 17.x и PHP 8.2: какие подходы использовать, где ставить защиту и что проверять до публикации.

Сначала определите, кто инициирует обмен

У интеграции есть два разных направления. DLE может отправлять данные во внешний сервис после действия пользователя, либо внешний сервис может обращаться к сайту через webhook. Эти сценарии нельзя считать взаимозаменяемыми.

• Исходящий запрос из DLE. Например, сайт передаёт заявку в CRM или отправляет уведомление в Telegram.
• Входящий webhook. Платёжная система или CRM вызывает URL на сайте и сообщает о новом статусе.
• Периодический обмен. Cron-задача забирает новые записи или повторяет неудачные попытки.

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

Главная ошибка интеграции — считать успешным сам факт вызова PHP-кода. Успехом считается только подтверждённая обработка данных внешним сервисом.

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

Три подхода и их цена

Выбор способа зависит от того, где находится источник истины и насколько критична потеря события.

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

Ошибки, которые чаще всего ломают интеграцию

1. Жёстко зашитые URL и ключи

Адрес тестового сервиса, токен и идентификатор проекта не должны находиться в шаблоне. При переносе на другой домен такой код либо отправит данные не туда, либо потребует ручного поиска по десяткам файлов.

Храните настройки отдельно от шаблонов и не публикуйте секреты в Git. Минимум, который стоит вынести в конфигурацию: URL сервиса, таймаут, идентификатор проекта и секрет подписи. Файл с настройками должен быть недоступен из браузера, а секреты — заменяться при утечке.

2. Отсутствие таймаута

Если внешний сервер не отвечает, PHP-процесс может ждать слишком долго. Для посетителя это выглядит как зависшая форма или ошибка 504, хотя запись в DLE уже могла сохраниться.

У исходящего запроса задайте ограничение времени соединения и общий таймаут. Для пользовательского действия обычно нужен короткий предел, а повторную отправку лучше вынести в cron. Точное значение зависит от сервиса и хостинга: его проверяют нагрузочным тестом, а не выбирают по умолчанию.

3. Проверяется только HTTP-код

Ответ с кодом 200 ещё не означает успешную обработку. Сервис может вернуть JSON с полем ошибки, сообщение о неверной структуре или статус, который означает «принято на проверку», а не «обработано».

Проверяйте одновременно код ответа, корректность JSON и обязательное поле результата из документации конкретного API. Логируйте технический идентификатор запроса, но не полный токен, пароль и персональные данные пользователя.

4. Дубли из-за повторной отправки

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

Создавайте уникальный ключ события: например, идентификатор записи DLE плюс тип операции. Перед повторной отправкой проверяйте, есть ли уже успешный результат. Если внешний API поддерживает idempotency key, передавайте его согласно официальной документации сервиса.

5. Неправильная кодировка

Русский текст превращается в кракозябры, когда тело запроса собрано вручную, заголовок не соответствует формату или JSON кодируется дважды. Не смешивайте application/x-www-form-urlencoded и application/json: это разные форматы передачи.

Для JSON сначала сформируйте массив PHP, затем один раз преобразуйте его в JSON и отправьте с заголовком Content-Type: application/json. Не склеивайте JSON строками.

Безопасный исходящий запрос из PHP

Ниже — небольшой адаптер для PHP 8.2. Он не использует внутренние имена DLE и подходит как часть модуля, где уже получены и проверены данные формы. URL и ключ оставлены заглушками.

<?php
declare(strict_types=1);

function sendJsonRequest(string $url, array $payload): array
{
    $json = json_encode(
        $payload,
        JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
    );

    $handle = curl_init($url);
    if ($handle === false) {
        throw new RuntimeException('Не удалось инициализировать cURL');
    }

    curl_setopt_array($handle, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $json,
        CURLOPT_HTTPHEADER => [
            'Accept: application/json',
            'Content-Type: application/json',
            'Authorization: Bearer YOUR_API_KEY',
        ],
        CURLOPT_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $responseBody = curl_exec($handle);
    $curlError = curl_error($handle);
    $statusCode = (int) curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
    curl_close($handle);

    if ($responseBody === false) {
        throw new RuntimeException('Ошибка сети: ' . $curlError);
    }

    if ($statusCode < 200 || $statusCode >= 300) {
        throw new RuntimeException('Сервис вернул HTTP ' . $statusCode);
    }

    $response = json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);

    return [
        'status_code' => $statusCode,
        'response' => $response,
    ];
}

$result = sendJsonRequest('https://api.example.test/v1/leads', [
    'event_id' => 'dle-record-123',
    'name' => 'Имя посетителя',
    'email' => 'user@example.test',
]);

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

Что проверять во входящем webhook

Webhook — это публичная точка входа. Любой человек может отправить туда POST-запрос, поэтому одного секретного URL недостаточно.

1. Проверьте метод и тип тела. Отклоняйте неожиданный HTTP-метод и запросы без нужного формата.
2. Проверьте подпись. Используйте алгоритм и заголовок из документации сервиса. Не придумывайте собственную схему, если поставщик уже описал стандарт.
3. Проверьте обязательные поля. Идентификатор события, статус и сумма должны иметь ожидаемый тип и диапазон.
4. Проверьте повтор. Если событие уже обработано, верните корректный ответ без повторного изменения заказа.
5. Сохраните исходное событие. Это позволит восстановить цепочку при споре с платёжной системой или CRM.

CSRF-защита формы DLE и проверка подписи внешнего webhook решают разные задачи. Первая защищает действие пользователя на вашем сайте, вторая подтверждает источник серверного сообщения.

Что ломается в продакшене

• Сервис отвечает 401 или 403. Обычно истёк ключ, неверны права приложения или перепутаны тестовый и боевой URL.
• Сервис отвечает 400. Проверьте формат тела, обязательные поля, типы данных и кодировку.
• Появляются дубли. Найдите место, где статус события записывается после отправки, и добавьте уникальный ключ до повторного запуска.
• На сайте 502 или 504. Уберите медленный внешний вызов из синхронного рендера страницы и перенесите повторную обработку в очередь или cron.
• Webhook работает в тесте, но не в проде. Проверьте HTTPS-сертификат, DNS, доступность порта, правила WAF и ограничения хостинга.

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

Как выбирать архитектуру

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

Проверяйте не только успешный сценарий. Отдельно воспроизведите таймаут, неверный ключ, повторный webhook, повреждённый JSON и ответ с HTTP 200, но ошибкой внутри тела. Именно эти случаи обычно обнаруживаются уже после запуска.

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

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