При синхронізації 1С-Бітрікс з CRM, маркетплейсом або платіжним шлюзом багато розробників пишуть логіку прямо в компоненті. Через півроку такий «конектор» перетворюється на спагеті, яке неможливо налагоджувати. Особливо гостро проблема постає при частих змінах API зовнішніх сервісів: кожне оновлення ламає інтеграцію, а виправлення розкидані по десятках файлів. У нас більше 50 успішних проєктів. Ми інтегрували СДЕК, ЮKassa, Ozon, amoCRM. За цей час виробили архітектуру, яка живе роками і легко адаптується під будь-які зміни API.
Конектор — ізольований PHP-модуль, що інкапсулює взаємодію з однією зовнішньою системою. Правильно спроєктований конектор не залежить від бізнес-логіки сайту, легко тестується та перевикористовується між проєктами. Наприклад, написавши один раз клієнт для ЮKassa, ви використовуєте його в кількох проєктах, змінюючи лише мапінг.
Чому варто замовити розробку конектора у нас?
Вибір між саморобним конектором та готовим модулем з Маркетплейсу — це питання гнучкості та часу. Саморобний виграє в гнучкості та контролі, модуль — у швидкості розгортання. Але якщо потрібна кастомна логіка — рідкісний API або специфічний мапінг замовлень — то свій конектор окупається вже на другому проєкті. На практиці саморобний конектор у 3 рази швидший у тестуванні та доопрацюванні, ніж адаптація типового модуля.
| Критерій | Саморобний конектор | Готовий модуль |
|---|---|---|
| Гнучкість | Максимальна | Обмежена налаштуваннями |
| Час запуску | 2–4 дні | 1 день |
| Залежність від вендора | Немає | Є (оновлення, зміни API) |
| Тестування | Повне покриття | Обмежено |
Структура модуля-конектора
Конектор реалізується як модуль Бітрікс (конектор бітрікс). Для детального розуміння архітектури модулів зверніться до офіційної документації 1С-Бітрікс. Структура директорії:
/local/modules/vendor.connector_name/
├── install/
│ ├── index.php # Інсталятор модуля
│ └── db/
│ └── install.sql # Таблиці модуля
├── lib/
│ ├── Client.php # HTTP-клієнт (API клієнт бітрікс)
│ ├── Mapper.php # Мапер даних бітрікс
│ ├── Queue.php # Черга завдань бітрікс
│ └── EventHandler.php # Підписка на події Бітрікс
├── options.php # Сторінка налаштувань конектора
└── include.php
Досвідчений розробник Бітрікс зазначив: «Конектор має бути ізольований від ядра CMS, щоб не ламатися при оновленнях». Наші послуги включають розробку модуля Бітрікс для інтеграції 1с-бітрікс, створення API клієнта Бітрікс, реалізацію мапера даних бітрікс, черги завдань бітрікс, обміну даними бітрікс, інтеграції CRM бітрікс, налаштування конектора, розробки на бітрікс, бітрікс24 інтеграції та конектора для маркетплейсу.
Базовий клас клієнта
На відміну від прямих викликів 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 (шифрування AES-256).
Як архітектура конектора впливає на продуктивність?
Перед запуском проводимо навантажувальне тестування з емуляцією 1000 одночасних запитів. Типова помилка — недостатнє налаштування кешування. Ми використовуємо теговане кешування Бітрікс, що скорочує час відповіді на 40%. Також налаштовуємо агрегування логів та моніторинг через системні події. При тиражуванні конектора на інший проєкт ви економите до 70% бюджету, що може скласти кілька тисяч доларів. Наш конектор у 3 рази швидше працює при навантаженні, ніж типові модулі з Маркетплейсу.
Що входить в результат роботи?
- Детальна документація архітектури та API.
- Вихідний код модуля з інсталятором.
- Налаштування логування та моніторингу помилок.
- Проведення навантажувального тестування з емуляцією 1000 одночасних запитів.
- Навчання адміністраторів: вебінар на 2 години.
- Супровід протягом 3 місяців після запуску — виправляємо баги, оновлюємо при змінах API.
| Завдання | Трудозатрати |
|---|---|
| Базова структура модуля | 4–6 год |
| HTTP-клієнт з обробкою помилок | 4–6 год |
| Мапер даних | 4–8 год |
| Черга з повторними спробами | 4–6 год |
| Сторінка налаштувань та тести | 4–6 год |
Отримайте консультацію по вашому проєкту — оцінимо його за 1 робочий день та запропонуємо дорожню карту з точними термінами. Замовте інтеграцію під ключ і отримайте конектор, який не зламається при першому оновленні API. Зв'яжіться з нами для оцінки вашого проєкту. Ми підготуємо детальну пропозицію та дорожню карту протягом одного робочого дня. Ми гарантуємо 3 місяці безкоштовної підтримки, маємо сертифікати партнерства 1С-Бітрікс та понад 10 років досвіду.
Покроковий план розробки конектора
- Аналіз API зовнішньої системи (вивчення документації, тестові запити).
- Створення структури модуля (генерація файлів, інсталятор).
- Реалізація HTTP-клієнта з обробкою помилок та аутентифікацією.
- Мапінг даних (клас Mapper для перетворення структур).
- Черга завдань з повторними спробами (Queue).
- Сторінка налаштувань в адмінці (options.php).
- Тестування: модульне, інтеграційне, навантажувальне.
Вартість розробки типового конектора — від $500 до $2000 залежно від складності. Економія при повторному використанні сягає 70%.