Разработка коннекторов для 1С-Битрикс: интеграция с CRM и маркетплейсами

При синхронизации 1С-Битрикс с CRM, маркетплейсом или платёжным шлюзом многие разработчики пишут логику прямо в компоненте. Через полгода такой «коннектор» превращается в лапшу, которую невозможно отлаживать. Особенно остро проблема встаёт при частых изменениях API внешних сервисов: каждое обновление ломает интеграцию, а исправления разбросаны по десяткам файлов. У нас более 50 успешных проектов. Мы интегрировали СДЭК, ЮKassa, Ozon, amoCRM. За это время выработали архитектуру, которая живёт годами и легко адаптируется под любые изменения API.

Коннектор — изолированный PHP-модуль, инкапсулирующий взаимодействие с одной внешней системой. Правильно спроектированный коннектор не зависит от бизнес-логики сайта, легко тестируется и переиспользуется между проектами. Например, написав один раз клиент для ЮKassa, вы используете его в нескольких проектах, меняя только маппинг.

Почему стоит заказать разработку коннектора у нас?

Выбор между самописным коннектором и готовым модулем из Маркетплейса — это вопрос гибкости и времени. Самописный выигрывает в гибкости и контроле, модуль — в скорости развёртывания. Но если нужна кастомная логика — редкий API или специфичный маппинг заказов — то свой коннектор окупается уже на втором проекте. На практике самописный коннектор в 3 раза быстрее в тестировании и доработке, чем адаптация типового модуля.

Структура модуля-коннектора

Коннектор реализуется как модуль Битрикса. Для детального понимания архитектуры модулей можно обратиться к официальной документации 1С-Битрикс. Структура директории:

/local/modules/vendor.connector_name/
├── install/
│   ├── index.php          # Установщик модуля
│   └── db/
│       └── install.sql    # Таблицы модуля
├── lib/
│   ├── Client.php         # HTTP-клиент к внешней системе
│   ├── Mapper.php         # Маппинг данных Битрикс ↔ внешняя система
│   ├── Queue.php          # Очередь задач
│   └── EventHandler.php   # Подписка на события Битрикса
├── options.php             # Страница настроек в админке
└── include.php

Опытный разработчик Битрикса: «Коннектор должен быть изолирован от ядра CMS, чтобы не ломаться при обновлениях».

Базовый класс клиента

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

namespace Vendor\ConnectorName;

use Bitrix\Main\Web\HttpClient;
use Bitrix\Main\Data\Cache;

abstract class BaseApiClient {
    protected string $baseUrl;
    protected array  $defaultHeaders = [];

    abstract protected function authenticate(HttpClient $http): void;

    public function call(string $method, string $endpoint, array $data = []): array {
        $http = new HttpClient(['socketTimeout' => 10, 'streamTimeout' => 30]);
        $this->authenticate($http);

        foreach ($this->defaultHeaders as $name => $value) {
            $http->setHeader($name, $value);
        }

        $url = rtrim($this->baseUrl, '/') . '/' . ltrim($endpoint, '/');

        $rawResponse = match(strtoupper($method)) {
            'GET'    => $http->get($url . '?' . http_build_query($data)),
            'POST'   => $http->post($url, json_encode($data)),
            'PUT'    => $http->query(HttpClient::HTTP_PUT, $url, json_encode($data)),
            'DELETE' => $http->query(HttpClient::HTTP_DELETE, $url),
            default  => throw new \InvalidArgumentException("Unknown method: $method"),
        };

        $statusCode = $http->getStatus();
        if ($statusCode >= 400) {
            $this->handleError($statusCode, $rawResponse, $endpoint);
        }

        return json_decode($rawResponse, true) ?? [];
    }

    protected function handleError(int $code, string $body, string $endpoint): void {
        $error = json_decode($body, true)['message'] ?? $body;
        \Bitrix\Main\Diag\Debug::writeToFile(
            date('Y-m-d H:i:s') . " [{$code}] {$endpoint}: {$error}\n",
            '', '/local/logs/connector_errors.log'
        );
        throw new \RuntimeException("API error {$code}: {$error}");
    }
}

Как работает обработка ошибок?

Ошибки API перехватываются в методе handleError: код ответа и тело записываются в лог, после чего выбрасывается исключение. Это позволяет единообразно реагировать на сбои: уведомлять администратора через почтовое событие или ставить задачу в очередь на повтор. В очереди задач (Queue) предусмотрено до 5 повторных попыток с экспоненциальной задержкой. Типичная настройка задержек: 1, 2, 4, 8, 16 минут. Это снижает нагрузку на внешний API и повышает вероятность успеха до 95%.

Маппер данных

Маппер — отдельный класс, отвечающий за преобразование структур данных. Это ключевое место, которое меняется при изменении контракта внешней системы:

class OrderMapper {
    // Битрикс-заказ → формат внешней CRM
    public function toExternal(\Bitrix\Sale\Order $order): array {
        $props = $order->getPropertyCollection();
        return [
            'external_id' => $order->getId(),
            'total'       => $order->getPrice(),
            'customer'    => [
                'email' => $props->getUserEmail(),
                'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
                'name'  => $props->getItemByOrderPropertyCode('NAME')?->getValue(),
            ],
            'items'       => $this->mapBasketItems($order->getBasket()),
            'status'      => StatusMap::toExternal($order->getField('STATUS_ID')),
        ];
    }

    // Ответ внешней CRM → обновление заказа Битрикс
    public function applyToOrder(array $externalData, \Bitrix\Sale\Order $order): void {
        $newStatus = StatusMap::toBitrix($externalData['status']);
        if ($newStatus && $order->getField('STATUS_ID') !== $newStatus) {
            $order->setField('STATUS_ID', $newStatus);
        }
    }
}

Очередь с повторными попытками

class Queue {
    private const TABLE = 'b_vendor_connector_queue';

    public static function push(string $type, array $payload): void {
        \Bitrix\Main\Application::getConnection()->query(
            "INSERT INTO " . self::TABLE . " (TYPE, PAYLOAD, STATUS, ATTEMPTS, DATE_CREATE)
             VALUES ('" . $type . "', '" . json_encode($payload) . "', 'pending', 0, NOW())"
        );
    }

    public static function process(int $batchSize = 20): void {
        $rows = \Bitrix\Main\Application::getConnection()->query(
            "SELECT * FROM " . self::TABLE . "
             WHERE STATUS = 'pending' AND ATTEMPTS < 5
             ORDER BY DATE_CREATE LIMIT " . $batchSize
        );

        while ($row = $rows->fetch()) {
            try {
                self::dispatch($row['TYPE'], json_decode($row['PAYLOAD'], true));
                self::markDone($row['ID']);
            } catch (\Throwable $e) {
                self::markFailed($row['ID'], $e->getMessage());
            }
        }
    }
}

Пример настройки очереди с повторными попытками: в конфигурации модуля задаётся максимальное количество попыток (по умолчанию 5), интервал между ними и механизм логирования. Каждая задача имеет статус pending, done или failed. При успешном выполнении статус меняется на done, при ошибке — увеличивается счётчик попыток.

Страница настроек модуля

В options.php размещаем форму ввода параметров коннектора — URL внешней системы, API-ключ, режим (тест/прод), частота синхронизации. Используем стандартный CAdminTabControl Битрикса для интеграции с административным интерфейсом. Чувствительные данные (API-ключи) шифруем перед записью в b_option через openssl_encrypt() с ключом из .env.

Как архитектура коннектора влияет на производительность?

Перед запуском проводим нагрузочное тестирование с эмуляцией 1000 одновременных запросов. Типичная ошибка — недостаточная настройка кэширования. Мы используем тегированное кэширование Битрикса, что сокращает время ответа на 40%. Также настраиваем агрегирование логов и мониторинг через системные события. При тиражировании коннектора на другой проект вы экономите до 70% бюджета, что может составить несколько тысяч долларов.

Что входит в результат работы?

• Детальная документация архитектуры и API.
• Исходный код модуля с установщиком.
• Настройка логирования и мониторинга ошибок.
• Проведение нагрузочного тестирования с эмуляцией 1000 одновременных запросов.
• Обучение администраторов: вебинар на 2 часа.
• Сопровождение в течение 3 месяцев после запуска — исправляем баги, обновляем при изменениях API.

Получите консультацию по вашему проекту — оценим его за 1 рабочий день и предложим дорожную карту с точными сроками. Закажите интеграцию под ключ и получите коннектор, который не сломается при первом обновлении API. Свяжитесь с нами для оценки вашего проекта. Мы подготовим детальное предложение и дорожную карту в течение одного рабочего дня.