Автоматизация передачи заказов из интернет-магазина в CRM — отличный способ упростить бизнес-процессы. В этой статье мы разберём, как создать плагин для Webasyst Shop-Script, который выгружает заказы в Битрикс24 через вебхук. Наш пример — плагин «Демо интеграция с Битрикс» — покажет, как настроить структуру, обработать заказы, отправить данные в Битрикс24 и добавить логирование для отладки. Статья подойдёт как новичкам, так и опытным разработчикам.

Зачем нужен такой плагин?

Плагин позволяет:

Автоматически создавать контакты и сделки в Битрикс24 при оформлении заказа в Shop-Script.
Передавать данные о клиенте, товарах, сумме и комментариях.
Настраивать параметры интеграции через бэкенд Webasyst.
Отслеживать процесс выгрузки через логи.

Мы создадим плагин с идентификатором demobitrix, который будет использовать хук order_action.create и отправлять данные через API Битрикс24.

Шаг 1: Подготовка окружения

Перед началом убедитесь, что у вас есть:

Webasyst Shop-Script версии 8.0 или выше (протестировано на 10.1.2, для 11.5.1 проверьте совместимость).
Портал Битрикс24 с настроенным входящим вебхуком (права на crm.contact.list, crm.contact.add, crm.deal.add, crm.deal.productrows.set).
PHP 7.2 или выше (для Shop-Script 11.5.1 может потребоваться PHP 8.x).
Доступ к директории wa-apps/shop/plugins/ на сервере.
Редактор кода (например, VS Code).

Для отладки включите режим debug в wa-config/config.php:

'debug' => true,

И добавьте в wa-config/SystemConfig.class.php:

error_reporting(E_ALL);
ini_set('display_errors', 1);

Шаг 2: Создание структуры плагина

Создайте директорию wa-apps/shop/plugins/demobitrix со следующей структурой:

demobitrix/
├── lib/
│   ├── shopDemobitrixPlugin.class.php
│   ├── order_to_bitrix24.php
│   ├── config/
│   │   ├── plugin.php
│   │   ├── settings.php
│   ├── .htaccess

icon.png: Иконка плагина (200x110 пикселей, PNG, прозрачный фон, например, с логотипом Битрикс24).
lib/shopDemobitrixPlugin.class.php: Основной класс плагина.
lib/order_to_bitrix24.php: Логика отправки данных в Битрикс24.
lib/config/plugin.php: Конфигурация плагина.
lib/config/settings.php: Настройки для бэкенда.
lib/.htaccess: Защита директории lib/.

Все файлы должны быть в кодировке UTF-8.

Шаг 3: Настройка конфигурации плагина

Файл lib/config/plugin.php задаёт основные параметры плагина. Пример:

<?php
return array(
    'name' => 'Демо интеграция с Битрикс',
    'description' => 'Передача заказов из Shop-Script в Битрикс24 через вебхук',
    'version' => '1.0.0',
    'vendor' => '223344', // Ваш Developer ID
    'frontend' => false,
    'handlers' => [
        'order_action.create' => 'orderActionCreate',
    ],
);
?>

name: Название плагина (без цифр, чтобы соответствовать стандартам Webasyst).
handlers: Указывает метод orderActionCreate для хука order_action.create.
frontend: false, так как плагин работает только в бэкенде.

Шаг 4: Создание настроек плагина

Файл lib/config/settings.php определяет пользовательские настройки, доступные в бэкенде Webasyst:

<?php
return array(
    'webhook_url' => array(
        'title' => 'URL вебхука Битрикс24',
        'description' => 'Введите URL входящего вебхука из Битрикс24 (например, https://your-domain.bitrix24.ru/rest/USER_ID/WEBHOOK_KEY/)',
        'value' => '',
        'control_type' => waHtmlControl::INPUT,
    ),
    'deal_category_id' => array(
        'title' => 'ID категории сделки',
        'description' => 'Укажите ID категории (воронки) для создания сделок (например, 0 для основной воронки)',
        'value' => '0',
        'control_type' => waHtmlControl::INPUT,
    ),
    'assigned_by_id' => array(
        'title' => 'ID ответственного менеджера',
        'description' => 'Укажите ID пользователя в Битрикс24, который будет ответственным за сделку (например, 1)',
        'value' => '',
        'control_type' => waHtmlControl::INPUT,
    ),
    'sub_to_order' => array(
        'title' => 'Подпись для заказов',
        'description' => 'Можно указать, например, (с сайта sitename.ru)',
        'value' => '',
        'control_type' => waHtmlControl::INPUT,
    ),
);
?>

Эти настройки позволяют задать URL вебхука, категорию сделки, ответственного менеджера и подпись для названий сделок.

Шаг 5: Обработка заказов в плагине

Основной класс плагина находится в lib/shopDemobitrixPlugin.class.php. Он наследуется от shopPlugin и обрабатывает хук order_action.create, вызываемый при создании заказа. Пример кода:

<?php
class shopDemobitrixPlugin extends shopPlugin
{
    public function orderActionCreate($params)
    {
        $order_id = $params['order_id'] ?? null;
        if (empty($order_id)) {
            waLog::log("Ошибка: ID заказа не передан", 'shop/plugins/demobitrix/logs.log');
            return;
        }

        $order_model = new shopOrderModel();
        $order = $order_model->getById($order_id);
        if (!$order) {
            waLog::log("Ошибка: Заказ с ID $order_id не найден", 'shop/plugins/demobitrix/logs.log');
            return;
        }

        $order_items_model = new shopOrderItemsModel();
        $items = $order_items_model->getByField('order_id', $order_id, true);

        $contact = new waContact($order['contact_id']);
        $order_data = [
            'id' => $order['id'],
            'contact' => [
                'name' => $contact->get('name', 'default') ?: 'Не указано',
                'phone' => $contact->get('phone', 'default') ?: '',
                'email' => $contact->get('email', 'default') ?: '',
            ],
            'total' => $order['total'],
            'items' => array_map(function ($item) {
                return [
                    'name' => $item['name'],
                    'price' => $item['price'],
                    'quantity' => $item['quantity'],
                ];
            }, $items),
            'comment' => $order['comment'] ?? '',
        ];

        waLog::log("Заказ подготовлен для отправки, order_id: $order_id", 'shop/plugins/demobitrix/logs.log');
        include_once wa()->getAppPath('plugins/demobitrix/order_to_bitrix24.php', 'shop');
    }
}
?>

Этот код:

Проверяет наличие ID заказа.
Получает данные заказа и товаров через модели shopOrderModel и shopOrderItemsModel.
Собирает информацию о клиенте через waContact.
Логирует шаги в wa-data/protected/shop/plugins/demobitrix/logs.log.
Передаёт данные в order_to_bitrix24.php.

Совет: Использование глобальной переменной $order_data работает в PHP 7.x, но для PHP 8.x лучше передавать данные через параметры функции, чтобы избежать проблем совместимости.

Шаг 6: Отправка данных в Битрикс24

Файл lib/order_to_bitrix24.php обрабатывает взаимодействие с API Битрикс24. Основные шаги:

Получение настроек плагина.
Проверка или создание контакта в Битрикс24.
Создание сделки с привязкой к контакту.
Добавление товаров в сделку.
Логирование каждого шага.

Пример функции отправки запроса:

<?php
function sendToBitrix24($method, $params, $webhookUrl) {
    $queryUrl = $webhookUrl . $method;
    $queryData = http_build_query($params);
    waLog::log("Отправка запроса в Битрикс24: $queryUrl", 'shop/plugins/demobitrix/logs.log');

    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_SSL_VERIFYPEER => 0,
        CURLOPT_POST => 1,
        CURLOPT_HEADER => 0,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => $queryUrl,
        CURLOPT_POSTFIELDS => $queryData,
    ));

    $result = curl_exec($curl);
    if ($result === false) {
        $error = curl_error($curl);
        waLog::log("cURL Error: $error, URL: $queryUrl", 'shop/plugins/demobitrix/logs.log');
        curl_close($curl);
        return ['error' => $error];
    }
    curl_close($curl);

    $decoded_result = json_decode($result, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        waLog::log("Ошибка декодирования JSON: " . json_last_error_msg() . ", Ответ: $result", 'shop/plugins/demobitrix/logs.log');
        return ['error' => 'Invalid JSON response'];
    }
    return $decoded_result;
}
?>

Используется cURL для отправки POST-запросов к API Битрикс24.
Логируются запросы, ошибки cURL и проблемы с JSON.
Пользовательский ввод (sub_to_order) экранируется через htmlspecialchars для защиты от XSS.

Шаг 7: Защита и безопасность

Чтобы плагин был безопасным:

Добавьте lib/.htaccess:
```
Deny from all
```
Это защитит директорию lib/ от прямого доступа.
Экранируйте пользовательский ввод (htmlspecialchars для sub_to_order).
Не используйте прямые SQL-запросы или операции с файлами в системных директориях (wa-apps/, wa-system/).
Логи записывайте в wa-data/protected/shop/plugins/demobitrix/logs.log через waLog::log.

Шаг 8: Тестирование плагина

Установка:
- Скопируйте плагин в wa-apps/shop/plugins/demobitrix.
- Активируйте в бэкенде Webasyst («Плагины» → «Магазин»).
Настройка:
- Укажите URL вебхука Битрикс24 и другие параметры в настройках.
Тестирование:
- Создайте тестовый заказ в Shop-Script.
- Проверьте логи в wa-data/protected/shop/plugins/demobitrix/logs.log для шагов (подготовка заказа, отправка запроса, создание контакта/сделки).
- Убедитесь, что сделка появилась в Битрикс24.
Совместимость:
- Плагин протестирован на Shop-Script 10.1.2. Для Shop-Script 11.5.1 проверьте:
  - Версию PHP (8.x может требовать замены глобальных переменных на параметры).
  - Права доступа к wa-data/protected/ (chmod 755 или 777).
  - Вызов хука order_action.create (добавьте лог в начале метода).
  - Ошибки cURL (проверьте HTTP-код ответа).

Совет: Если логи не записываются, проверьте права доступа к директории wa-data/protected/shop/plugins/demobitrix/ и включите debug-режим.

Шаг 9: Добавление документации

Создайте файл README.md с инструкциями:

Описание: Что делает плагин.
Системные требования: Shop-Script 8.0+, PHP 7.2+, доступ к Битрикс24.
Установка: Копирование в wa-apps/shop/plugins/demobitrix и активация.
Настройка: Описание полей настроек.
Отладка: Указание пути к логам (wa-data/protected/shop/plugins/demobitrix/logs.log).
Примечания: Совместимость, автономность, отсутствие Premium-функций.

Шаг 10: Советы по улучшению

Избегайте глобальных переменных: Для PHP 8.x передавайте данные через параметры функции вместо global $order_data.
Добавьте обработку ошибок: Логируйте HTTP-коды ответа cURL для диагностики проблем с API.
Тестируйте на разных версиях: Shop-Script 11.5.1 может иметь изменения в хуках или моделях данных, проверьте документацию.

Заключение

Создание плагина для Shop-Script для выгрузки заказов в Битрикс24 — это простой способ автоматизировать работу интернет-магазина. Наш плагин «Демо интеграция с Битрикс» показывает, как использовать хуки, API и логирование для интеграции. Попробуйте создать свой плагин, следуя этим шагам, и автоматизируйте свои процессы!

Готовы сделать всю работу за Вас

^от3000₽

120 минут

Перенесем сайты! Перенесем баланс! Подарим 3 месяца хостинга!

Возврат к списку

+7 (999) 811-66-09

@v2Team

Skype

info@v2team.ru

Поработаем?

Опишите свой запрос, мы расчитаем стоимость вашей задачи.

Заполнить форму Написать на почту

Как создать плагин для Shop-Script для выгрузки заказов в Битрикс24