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

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

Пряма інтеграція двох систем (Bitrix24 ↔ 1С, Bitrix24 ↔ SAP) створює жорстку зв'язаність: зміна API однієї системи ламає іншу. Middleware — проміжний шар, який приймає дані з однієї системи, трансформує і передає в іншу. Обидві системи знають тільки middleware, не знають одна про одну.

Коли потрібен middleware

• Три і більше систем обмінюються даними між собою.
• Формати даних систем суттєво відрізняються і вимагають складної трансформації.
• Потрібна буферизація: одна система недоступна, дані накопичуються і передаються пізніше.
• Потрібен аудит: повна історія всіх обмінів даними з можливістю відтворити будь-яку операцію.
• Різні команди розробляють інтеграції незалежно.

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

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

Варіант 2. Незалежний мікросервіс (Node.js, Python FastAPI, Go) — живе окремо, 1С-Бітрікс — одне з джерел/отримувачів. Плюс: масштабується незалежно, не споживає ресурси 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
        );
    }
}

// Приклад: замовлення 1С-Бітрікс → формат SAP
$pipeline = (new TransformationPipeline())
    ->pipe(fn($d) => normalizeCustomerData($d))        // нормалізація клієнта
    ->pipe(fn($d) => enrichWithAddressData($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 (залишки та ціни) ↔ сайт 1С-Бітрікс ↔ RetailCRM (обробка замовлень). Без middleware кожна пара систем мала свою інтеграцію — разом 6 двосторонніх зв'язків, 6 точок відмови.

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