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

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

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

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

Конектор реалізується як модуль 1С-Бітрікс. Структура директорії:

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

Базовий клас клієнта

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}");
    }
}

Маппер даних

Маппер — окремий клас, відповідальний за перетворення структур даних. Це ключове місце, яке змінюється при зміні контракту зовнішньої системи:

class OrderMapper {
    // Замовлення 1С-Бітрікс → формат зовнішньої 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 → оновлення замовлення 1С-Бітрікс
    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());
            }
        }
    }
}

Сторінка налаштувань модуля

В options.php розміщуємо форму введення параметрів конектора — URL зовнішньої системи, API-ключ, режим (тест/прод), частота синхронізації. Використовуємо стандартний CAdminTabControl 1С-Бітрікс для інтеграції з адміністративним інтерфейсом.

Чутливі дані (API-ключі) шифруємо перед записом у b_option через openssl_encrypt() з ключем із .env.