Розробка локальних застосунків Бітрікс24 під ключ
Нам часто телефонують з одним і тим же болем: потрібно терміново зв'язати Бітрікс24 з внутрішньою системою — 1С, складом або власною CRM, а публікувати в Маркеті немає сенсу. Ліцензія обмежена одним порталом, доступ ззовні частково закритий. Ми пропонуємо рішення: локальний застосунок — він налаштовується за 15 хвилин і дає повний доступ до REST API без бюрократії. Досвід наших інженерів — понад 10 років в екосистемі Бітрікс, тому гарантуємо надійність та продуктивність навіть на високонавантажених порталах.
Локальний застосунок — найшвидший спосіб почати інтеграцію: не потрібно проходити модерацію Маркету, не потрібен публічний домен на старті (використовуємо ngrok), не потрібно реєструватися як розробник. Все налаштовується прямо в налаштуваннях порталу. Отримайте консультацію щодо вашого проекту — ми оцінимо обсяг і запропонуємо оптимальну архітектуру.
Реєстрація локального застосунку
Шлях у порталі: Застосунки → Розробникам → Інше → Локальний застосунок.
Параметри при створенні:
- Тип авторизації:
Серверний застосунок (OAuth) або JavaScript-застосунок (JS SDK без серверної частини)
- Handler URL: адреса вашого застосунку, куди Бітрікс24 відкриє iframe при запуску
- Start URL: URL для старту застосунку з меню (може збігатися з Handler URL)
- Права: набір скопів —
crm, task, user, disk, catalog тощо
Після створення отримуєте client_id та client_secret. Для JavaScript-типу секрет не потрібен — токен генерується на порталі та передається в iframe через параметри запиту.
Як працює OAuth у локальних застосунках?
У серверному типі використовується стандартний протокол OAuth 2.0 з Authorization Code. При першому відкритті застосунку Бітрікс24 передає в Query параметри AUTH_ID, REFRESH_ID та AUTH_EXPIRES. Сервер зберігає access token, а при закінченні — оновлює через refresh token, надсилаючи POST-запит на https://{domain}/oauth/token/. Access token живе 3600 секунд, refresh token — 30 днів, тому потрібно передбачити циклічне оновлення. Бібліотека клієнта (наприклад, bitrix24-api) робить це автоматично. Детальніше про протокол — у Wikipedia. Додаткову інформацію можна знайти в офіційній документації Бітрікс24.
Різниця між JavaScript та серверним типом
| Параметр |
JavaScript-застосунок |
Серверний застосунок |
| Авторизація |
Токен з параметрів URL/postMessage |
OAuth 2.0 Authorization Code |
| Серверна частина |
Не потрібна |
Обов'язкова |
| Зберігання секрету |
Немає секрету |
client_secret на сервері |
| Фонова робота |
Ні |
Так (cron, черги) |
| Підписка на події |
Через BX24.js |
Через event.bind REST |
| Коли використовувати |
UI-віджети, дашборди |
Синхронізація, автоматизація |
JavaScript-тип підходить для MVP за 1–3 дні, серверний — для корпоративних інтеграцій, які можуть займати 1–3 тижні. Локальний застосунок стартує в 2–3 рази швидше за тиражний, тому що не потребує модерації.
Розробка JavaScript-типу локального застосунку
Мінімальний робочий приклад:
<!DOCTYPE html>
<html>
<head>
<script src="//api.bitrix24.com/api/v1/"></script>
</head>
<body>
<div id="app"></div>
<script>
BX24.init(function() {
var auth = BX24.getAuth();
// auth.domain — домен порталу
// auth.access_token — токен для REST-запитів
BX24.callMethod('user.current', {}, function(result) {
if (result.error()) {
document.getElementById('app').innerHTML = 'Помилка: ' + result.error();
return;
}
var user = result.data();
document.getElementById('app').innerHTML =
'Привіт, ' + user.NAME + '!';
});
BX24.fitWindow();
});
</script>
</body>
</html>
Файл //api.bitrix24.com/api/v1/ — це Bitrix24 JS SDK, завантажується з CDN Bitrix. Підключати напряму з порталу не потрібно.
Розробка серверного типу
Для серверного локального застосунку потрібен HTTPS-endpoint (для розробки підійде ngrok). Покрокова інструкція:
- Встановіть ngrok та запустіть тунель:
ngrok http 3000
# Отримуємо: https://abc123.ngrok.io
- Зареєструйте локальний застосунок, вказавши цей URL як Handler URL.
- Реалізуйте обробку OAuth callback.
Обробка OAuth callback на Node.js:
const express = require('express');
const axios = require('axios');
const app = express();
// Handler URL — точка входу
app.get('/', (req, res) => {
const { AUTH_ID, REFRESH_ID, AUTH_EXPIRES, DOMAIN, PLACEMENT } = req.query;
// Зберігаємо токени
saveTokens({
domain: DOMAIN,
accessToken: AUTH_ID,
refreshToken: REFRESH_ID,
expiresIn: parseInt(AUTH_EXPIRES)
});
res.sendFile(__dirname + '/public/index.html');
});
// Refresh token endpoint
app.post('/refresh', async (req, res) => {
const { refresh_token, domain } = req.body;
const response = await axios.post(
`https://${domain}/oauth/token/`,
new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
refresh_token
})
);
res.json(response.data);
});
Що таке скопи та як їх вибирати?
Права доступу (скопи) визначають, які дані застосунок може читати або змінювати. Локальні застосунки запитують їх при встановленні. Якщо після реєстрації потрібно додати новий скоп — користувач повинен перевстановити застосунок (натиснути кнопку оновлення прав). Це важливий UX-момент: плануйте права заздалегідь, особливо якщо застосунок вже в продакшені.
Повний список скопів
crm — угоди, ліди, контакти, компанії
task — завдання та проекти
user — користувачі порталу
disk — файли та папки
calendar — події календаря
sonet_group — групи та робочі простори
catalog — товарний каталог
sale — магазин та замовлення
telephony — дзвінки та телефонія
Обмеження локальних застосунків
- Працюють тільки на одному порталі
- Не можна опублікувати в Маркеті
- При зміні домену порталу потрібна переконфігурація
- Немає підтримки кількох redirect_uri
Для більшості внутрішньокорпоративних інтеграцій ці обмеження несуттєві. Якщо в майбутньому знадобиться масштабування — код локального застосунку переноситься в тиражний без кардинальної переробки.
Що входить в роботу
Ми розробляємо локальний застосунок під ключ. До складу робіт входить:
- Аналіз поточних процесів порталу та зовнішніх систем
- Проектування архітектури (мікросервіси або моноліт)
- Реалізація REST-методів для синхронізації
- Підключення вебхуків для подієвої обробки
- Налаштування OAuth та зберігання refresh токенів
- Тестування на бойовому порталі
- Передача документації з описом API та схеми прав
- Навчання адміністраторів порталу роботі з застосунком
- Гарантійна підтримка протягом 3 місяців
Типові помилки при розробці
Одна з поширених проблем — забути про refresh токен. Якщо не оновлювати access token, через годину застосунок перестане працювати. Інша — неправильний вибір скопів: не вистачає прав на запис, і синхронізація падає. Ми використовуємо одноманітний підхід: всі виклики REST обгорнуті в обробник, який автоматично продовжує токен та логує помилки. Завдяки цьому час пошуку багів скорочується на 60%.
Терміни розробки
| Завдання |
Термін |
| Налаштування локального застосунку + базова авторизація |
0,5–1 день |
| Простий віджет (тільки читання даних CRM) |
1–3 дні |
| Інтеграція з внутрішньою системою (двостороння) |
1–3 тижні |
| Повноцінний корпоративний застосунок |
1–2 місяці |
Зв'яжіться з нами для оцінки вашого проекту — ми підберемо оптимальне рішення та реалізуємо його в обумовлені терміни.
Розробка та налаштування модулів 1С-Бітрікс
Головна пастка Бітрікса — init.php. Засунули туди обробник OnBeforeIBlockElementUpdate, потім ще один — через рік файл на 2000 рядків, і при кожному хіті вся ця купа виконується. Ми переносимо бізнес-логіку в повноцінні модулі з D7 ORM, власними таблицями та адміністративним інтерфейсом. Модуль можна вимкнути, перенести на інший проєкт, покрити тестами — з init.php нічого з цього не вийде. Досвід команди — 10+ років у Бітрікс, сертифіковані спеціалісти, гарантія на код 6 місяців. Замовте консультацію — розповімо, як перевести legacy-код у модульну архітектуру.
Як модульна архітектура підвищує продуктивність?
Чому init.php — найгірше місце для бізнес-логіки?
Init.php не підтримує автозавантаження класів, не має ізольованого простору імен, не піддається модульному тестуванню і не вимикається без правки самого файлу. Кожен обробник, написаний там, спрацьовує на кожному запиті, навіть якщо він не потрібен. У модулі ви реєструєте обробника через EventManager, і він виконується тільки при настанні події. Різниця в продуктивності — до 3 разів при 10+ обробниках.
Стандартні модулі: типові проблеми та рішення
Інформаційні блоки. Архітектура ІБ — перше, що ми рев'юїмо на будь-якому проєкті. Класична помилка: один інфоблок каталогу з 80 властивостями, з яких 30 — множинні. Таблиця b_iblock_element_property роздувається до мільйонів рядків, CIBlockElement::GetList на фільтрації за трьома властивостями йде в повне сканування. Переносимо довідники в Highload-блоки, прибираємо множинні властивості де можна, проєктуємо структуру з прицілом на те, що каталог виросте в 5 разів.
Інтернет-магазин (sale). Бізнес-правила кошика — окрема історія. Налаштовуємо пріоритети знижок, щоб дві акції не дали 60% замість 30%, підключаємо платіжні обробники, прописуємо кастомну валідацію через OnSaleOrderBeforeSaved.
Пошук. Вбудований модуль search з морфологією працює до 10–15 тисяч елементів. Далі — Elasticsearch. Налаштовуємо через API модуля пошуку Бітрікс, індексуємо через CSearchFullText або кастомні індексатори.
Highload-блоки для довідників, логів, користувацьких даних — замість роздутих ІБ. Прямі запити через Bitrix\Highloadblock\HighloadBlockTable, власні таблиці замість EAV-структури стандартних інфоблоків. Мільйон записів — без деградації.
Поштові події. Налаштування — не лише шаблони в b_event_message. Головне — SPF, DKIM, DMARC на DNS, інакше транзакційні листи летять у спам. Перевіряємо доставність, налаштовуємо bounce-обробку.
Проектування інфоблоків для продуктивності
Використовуємо Highload-блоки для довідкових даних (кольори, розміри, виробники), які не беруть участі в складних вибірках. Для торгових пропозицій — окремий інфоблок з прив'язкою через IBLOCK_ELEMENT_PROPERTY. Увімкнемо INDEX_PROPERTY для часто фільтрованих властивостей. Кешування теговане: при зміні елемента скидається лише пов'язаний кеш. Highload-блоки обробляють до 10 разів швидше, ніж інфоблоки з множинними властивостями, на об'ємах від 100 000 записів.
Розробка кастомних модулів
Кожен модуль — за структурою /local/modules/vendor.modulename/:
-
install/index.php — клас встановлення, створення таблиць через $DB->RunSQLBatch()
-
lib/ — класи D7 ORM, спадкоємці Bitrix\Main\ORM\Data\DataManager
-
admin/ — адміністративні сторінки через CAdminList, CAdminForm
-
include.php — автозавантаження, реєстрація обробників через EventManager::getInstance()->registerEventHandler()
- REST API endpoints через
\Bitrix\Rest\RestManager
Модуль реєструється в системі, з'являється у списку «Встановлені рішення», має свої налаштування в /bitrix/admin/settings.php?mid=vendor.modulename. Його можна вмикати, вимикати, оновлювати через UpdateSystem або свій механізм міграцій.
Приклади реалізованих завдань:
- Управління акціями — візуальний конструктор умов через
CAdminCalendar, таймери через агенти (CAgent::AddAgent), аналітика ефективності у зв'язці з модулем sale
- Калькулятор вартості — React-віджет на фронті, REST API у модулі, формули зберігаються в Highload-блоці
- Система бронювання — real-time календар, блокування через
$DB->StartTransaction() / $DB->Commit() при одночасних запитах, синхронізація з channel manager через webhook
Компоненти та композитний кеш
Кастомізація компонентів — через result_modifier.php і component_epilog.php, не через правку template.php стандартного шаблону. Так ядро оновлюється безболісно.
Композитний кеш (технологія «Композитний сайт») — сервер віддає готовий HTML, минаючи PHP-роутинг. Динамічні зони (кошик, авторизація) підвантажуються через CBitrixComponent::setFrameMode(true) та AJAX. TTFB падає до 30–50 мс. Але є нюанси: не всі компоненти сумісні, $APPLICATION->ShowPanel() ламає композит, потрібна акуратна розмітка <div id="bx-composite-...">.
Маркетплейс: аудит перед встановленням
Перед встановленням модуля з маркетплейсу — обов'язковий аудит. Перевіряємо: SQL-запити без підготовлених виразів (привіт, SQL-ін'єкції), пряме звернення до $_REQUEST без фільтрації, використання застарілого API старого ядра замість D7, конфлікти з модулем композитного кешування. Модуль без оновлень більше року та з парою десятків встановлень — швидше за все, проблема на найближчому оновленні PHP. Типовий випадок: модуль викликає CIBlockElement::GetList з нескинутим кешем — сайт падає при 5000 елементів.
Міграція на D7
При оновленні PHP або переході на нову редакцію — рефакторинг застарілих викликів:
-
CIBlockElement::GetList() → Bitrix\Iblock\Elements\ElementTable::getList()
-
CSaleOrder::GetList() → Bitrix\Sale\Order::getList()
-
CModule::IncludeModule() → Bitrix\Main\Loader::includeModule()
Тестування на staging, відкат через git при проблемах.
Згідно з офіційною документацією 1С-Бітрікс, D7 ORM є рекомендованим засобом для роботи з даними, забезпечуючи безпеку типів і автогенерацію запитів.
Порівняння підходів: Init.php vs Модуль
| Критерій |
Init.php |
Модуль з D7 ORM |
| Продуктивність |
Виконується на кожному хіті |
Виконується тільки при події |
| Тестованість |
Немає автозавантаження, тести неможливі |
Повна підтримка PHPUnit |
| Підтримуваність |
Кодова база зростає безконтрольно |
Ізольована структура, версіонування |
| Міграції |
Немає |
Власні таблиці, керування через install |
| Кешування |
Не підтримує автоінвалідацію |
Теговане кешування, скидання за подією |
Вартість та склад розробки модулів
Що входить у розробку модуля?
- Технічне завдання та архітектурна схема
- Код з дотриманням PSR-4 та код-стайлу Бітрікс
- Unit-тести (PHPUnit) на бізнес-логіку
- Інтеграційні тести на події та REST API
- Документація з встановлення, налаштування та API
- Передача доступів до репозиторію та документації
- Навчання адміністраторів роботі з модулем
- Гарантійна підтримка 6 місяців
Орієнтовні терміни та складність:
| Складність |
Приклади |
Терміни |
| Простий |
Віджет зворотного дзвінка, банерна система, простий калькулятор |
3–5 днів |
| Середній |
Система бронювання, конфігуратор товарів, модуль відгуків з модерацією |
1–2 тижні |
| Складний |
Мультирегіональність, кастомна програма лояльності, інтеграція з ERP |
2–4 тижні |
| Enterprise |
Маркетплейс-платформа, складні бізнес-процеси з безліччю ролей |
1–3 місяці |
Вартість розраховується індивідуально — зв'яжіться з нами для оцінки вашого проєкту.
Тестування модулів
Unit-тести через PHPUnit покривають бізнес-логіку: розрахунок знижок, валідацію, формування документів. Моки для Bitrix\Main\Application::getConnection() дозволяють тестам не залежати від БД. Інтеграційні тести перевіряють обробники подій на реальній базі — OnAfterIBlockElementAdd, OnSaleOrderSaved та інші. REST API endpoints тестуємо через curl або PHPUnit HTTP-клієнт. Критично для модулів, що працюють з b_sale_order, b_catalog_price — де помилка коштує грошей.
Сумісність перевіряється на PHP 7.4, 8.0, 8.1, 8.2 та редакціях: Стандарт, Малий бізнес, Бізнес. Перевіряємо конфлікти з популярними модулями маркетплейсу — вони люблять перехоплювати ті самі події. Навантажувальне тестування: заміри на 10K, 100K, 1M записів, профілювання через Xdebug на предмет витоків пам'яті та N+1 запитів.
Приклади з практики
Модуль акцій для мережі електроніки. Штатні знижки модуля sale не покривали сценарії «2+1», подарунок при покупці від суми, комбіновані умови. Зібрали візуальний конструктор: маркетолог створює правила через drag-and-drop, без тікетів у розробку. Календар акцій, автодеактивація через агенти, аналітика у прив'язці до b_sale_order — конверсія, середній чек, кількість застосувань. Час запуску нової акції впав з двох днів до півгодини.
Калькулятор для будівельників. Параметри (площа, матеріали, поверховість) → формула → попередній кошторис → заявка в CRM через CRest::call('crm.lead.add'). Регіональні коефіцієнти та сезонні націнки — з Highload-блоку, ціни матеріалів — з обміну з 1С. Кількість цільових заявок зросла на третину: клієнти бачать розбивку за статтями до дзвінка менеджеру.
Бронювання для мережі готелів. Real-time доступність через AJAX-запити до кастомної таблиці vendor_booking_slots, розрахунок тарифів за сезоном, синхронізація з Booking.com через channel manager API. Блокування номера при одночасному бронюванні — через SELECT ... FOR UPDATE у транзакції. Таймзони обробляються через \DateTimeZone — гість із Владивостока та менеджер із Москви бачать одну картину.
Оцінимо проєкт за 1 день. Пишіть — розповімо, що входить у розробку під ключ. Зв'яжіться з нами для консультації за вашим проєктом. Замовте розробку модуля під ключ — отримайте готове рішення з документацією та підтримкою.
