Разработка middleware для интеграции 1С-Битрикс

Разработка middleware для интеграции 1С-Битрикс

Прямая интеграция двух систем (Битрикс24 ↔ 1С, Битрикс24 ↔ SAP) создаёт жёсткую связность: изменение API одной системы ломает другую. Middleware — промежуточный слой, который принимает данные из одной системы, трансформирует и передаёт в другую. Обе системы знают только middleware, не знают друг о друге.

Когда нужен middleware

• Три и более системы обмениваются данными между собой.
• Форматы данных систем существенно различаются и требуют сложной трансформации.
• Нужна буферизация: одна система недоступна, данные накапливаются и передаются позже.
• Нужен аудит: полная история всех обменов данными с возможностью воспроизвести любую операцию.
• Разные команды разрабатывают интеграции независимо.

Архитектурные варианты middleware

Вариант 1. PHP-middleware внутри Битрикса — отдельный модуль в /local/modules/, принимает запросы по HTTP, трансформирует, проксирует. Минус: привязан к инфраструктуре Битрикса.

Вариант 2. Независимый микросервис (Node.js, Python FastAPI, Go) — живёт отдельно, Битрикс — один из источников/получателей. Плюс: масштабируется независимо, не ест ресурсы PHP.

Вариант 3. iPaaS-платформы — Make (Integromat), n8n, Apache Camel. Визуальное построение трансформаций без кода. Подходит для не-разработчиков, но ограничен в сложных трансформациях.

PHP-middleware: структура и контракты

// Центральный маршрутизатор middleware
class IntegrationBus {
    private array $handlers = [];

    public function register(string $eventType, callable $handler): void {
        $this->handlers[$eventType][] = $handler;
    }

    public function dispatch(string $eventType, array $payload): array {
        $results = [];
        foreach ($this->handlers[$eventType] ?? [] as $handler) {
            try {
                $results[] = $handler($payload);
            } catch (\Throwable $e) {
                $this->logError($eventType, $payload, $e);
                $results[] = ['error' => $e->getMessage()];
            }
        }
        return $results;
    }
}

// Регистрация обработчиков в init.php
$bus = IntegrationBus::getInstance();

// Заказ с сайта → в CRM и в учётную систему
$bus->register('order.created', [CrmConnector::class, 'handleNewOrder']);
$bus->register('order.created', [AccountingConnector::class, 'createInvoice']);
$bus->register('order.created', [WarehouseConnector::class, 'reserveGoods']);

Трансформация данных (маппинг)

Трансформация — самая сложная часть middleware. Используем паттерн Pipeline:

class TransformationPipeline {
    private array $pipes = [];

    public function pipe(callable $transformation): self {
        $this->pipes[] = $transformation;
        return $this;
    }

    public function process(array $data): array {
        return array_reduce(
            $this->pipes,
            fn($carry, $pipe) => $pipe($carry),
            $data
        );
    }
}

// Пример: заказ Битрикс → формат SAP
$pipeline = (new TransformationPipeline())
    ->pipe(fn($d) => normalizeCustomerData($d))     // нормализация клиента
    ->pipe(fn($d) => enrichWithFiasData($d))         // добавляем ФИАС по адресу
    ->pipe(fn($d) => convertCurrencyFields($d))      // конвертация валюты
    ->pipe(fn($d) => mapStatusCodes($d, 'bitrix2sap'))  // маппинг статусов
    ->pipe(fn($d) => validateSapSchema($d));          // валидация схемы SAP

Аудит и воспроизводимость

Каждое сообщение логируется до и после трансформации:

// Таблица аудита
CREATE TABLE integration_audit (
    id            BIGSERIAL PRIMARY KEY,
    event_type    VARCHAR(100),
    source_system VARCHAR(50),
    target_system VARCHAR(50),
    payload_in    JSONB,
    payload_out   JSONB,
    status        VARCHAR(20), -- success, error, retry
    error_msg     TEXT,
    duration_ms   INT,
    created_at    TIMESTAMP DEFAULT NOW()
);

При ошибке в downstream-системе — воспроизводим операцию по ID записи аудита без повторного запроса к источнику.

Кейс: трёхстороннее взаимодействие

Производственная компания: 1С:ERP (остатки и цены) ↔ сайт Битрикс ↔ RetailCRM (обработка заказов). Без middleware каждая пара систем имела свою интеграцию — итого 6 двусторонних связей, 6 точек отказа.

После введения middleware-хаба: 3 системы → 3 коннектора к middleware. Изменение API 1С затронуло только 1С-коннектор, не затронув RetailCRM-интеграцию.