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

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

Інтеграція «через п'ять рядків cURL у якомусь файлі» — класична технічна заборгованість у Бітрікс-проєктах. Такий код не логується, не обробляє помилки, не підтримує retry і розвалюється при зміні API-ключа. Повноцінний модуль інтеграції вирішує ці проблеми системно.

Принципи архітектури інтеграційного модуля

Хороший модуль інтеграції складається з кількох шарів:

1. HTTP-клієнт — абстракція над транспортом (cURL/Guzzle), управління аутентифікацією, таймаутами, retry
2. API Gateway — методи, що відповідають конкретним ендпоінтам зовнішнього API
3. Mapper/DTO — перетворення даних між форматом API і форматом Бітрікс
4. Queue/Retry — черга для асинхронних запитів і повторних спроб при помилках
5. Logger — журнал усіх запитів/відповідей для діагностики
6. Admin UI — налаштування підключення, моніторинг, ручний запуск синхронізації

HTTP-клієнт із retry-логікою

namespace Vendor\Integration\Http;

use Bitrix\Main\Web\HttpClient;
use Bitrix\Main\Web\HttpHeaders;

class ApiClient
{
    private HttpClient $http;
    private string $baseUrl;
    private string $apiKey;
    private int $maxRetries = 3;

    public function request(string $method, string $endpoint, array $data = []): array
    {
        $attempt = 0;
        $lastException = null;

        while ($attempt < $this->maxRetries) {
            try {
                $response = $this->doRequest($method, $endpoint, $data);
                $this->logRequest($method, $endpoint, $data, $response);
                return $response;
            } catch (RateLimitException $e) {
                sleep(pow(2, $attempt)); // Експоненціальний backoff
                $attempt++;
                $lastException = $e;
            } catch (ApiException $e) {
                $this->logError($method, $endpoint, $e);
                throw $e; // Не робимо retry для бізнес-помилок
            }
        }

        throw $lastException;
    }
}

Логування запитів

Журнал запитів — обов'язкова частина продуктового модуля. Без нього підтримка перетворюється на вгадування. ORM-таблиця для логів:

// lib/Orm/ApiLogTable.php
class ApiLogTable extends DataManager
{
    public static function getTableName(): string { return 'vendor_integration_log'; }

    public static function getMap(): array
    {
        return [
            new IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new StringField('METHOD'),      // GET/POST/PUT
            new StringField('ENDPOINT'),
            new TextField('REQUEST_BODY'),
            new IntegerField('STATUS_CODE'),
            new TextField('RESPONSE_BODY'),
            new FloatField('DURATION_MS'),  // час виконання
            new StringField('ERROR'),
            new DatetimeField('CREATED_AT'),
        ];
    }
}

В адміністративному розділі реалізується список запитів із фільтрацією за статусом, датою, ендпоінтом. Це перше місце, куди дивиться розробник при діагностиці.

Черга для асинхронної синхронізації

Синхронні виклики зовнішніх API під час користувацького запиту — антипатерн: зовнішній сервіс може бути повільним або недоступним. Важкі операції (оновлення каталогу з ERP, синхронізація замовлень) виносяться в чергу.

Реалізація через агенти Бітрікс:

// Агент запускається за cron кожні N хвилин
public static function processSyncQueue(): string
{
    $items = SyncQueueTable::getList([
        'filter' => ['STATUS' => 'pending', '<ATTEMPTS' => 3],
        'limit'  => 50,
        'order'  => ['CREATED_AT' => 'ASC'],
    ]);

    foreach ($items as $item) {
        try {
            static::processItem($item);
            SyncQueueTable::update($item['ID'], ['STATUS' => 'done']);
        } catch (\Exception $e) {
            SyncQueueTable::update($item['ID'], [
                'STATUS'       => $item['ATTEMPTS'] >= 2 ? 'failed' : 'pending',
                'ATTEMPTS'     => $item['ATTEMPTS'] + 1,
                'LAST_ERROR'   => $e->getMessage(),
                'NEXT_ATTEMPT' => (new \Bitrix\Main\Type\DateTime())->add('PT' . pow(2, $item['ATTEMPTS']) . 'M'),
            ]);
        }
    }

    return '\Vendor\Integration\SyncAgent::processSyncQueue();'; // Повернення для повторного запуску
}

Webhook-обробник

Якщо зовнішня система надсилає події (webhook), модуль реєструє публічний URL для прийому:

// Публічний обробник: /local/api/integration/webhook.php
use Bitrix\Main\Application;

$request = Application::getInstance()->getContext()->getRequest();
$payload = json_decode($request->getInput(), true);

// Перевірка підпису
$signature = $request->getHeader('X-Signature');
if (!WebhookSecurity::verify($payload, $signature)) {
    http_response_code(401);
    exit;
}

// Постановка в чергу обробки
SyncQueueTable::add([
    'TYPE'    => 'webhook_' . ($payload['event'] ?? 'unknown'),
    'PAYLOAD' => json_encode($payload),
    'STATUS'  => 'pending',
]);

http_response_code(200);
echo json_encode(['ok' => true]);

Налаштування модуля

Налаштування (URL API, ключі, режим роботи) зберігаються через \Bitrix\Main\Config\Option:

// Запис налаштування
Option::set('vendor.integration', 'api_key', $encryptedKey);
Option::set('vendor.integration', 'api_url', 'https://api.service.com/v2');

// Читання
$apiKey = Option::get('vendor.integration', 'api_key');

Чутливі дані (API-ключі, паролі) шифруються перед збереженням через \Bitrix\Main\Security\Sign\Signer або стандартну функцію \Bitrix\Main\Crypt.

Типові терміни розробки

Модуль документується на рівні архітектури (діаграма потоків даних) і на рівні експлуатації (інструкція для адміністратора з описом налаштувань та інтерпретацією помилок).