Розробка локальних застосунків Бітрікс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 місяці |
Зв'яжіться з нами для оцінки вашого проекту — ми підберемо оптимальне рішення та реалізуємо його в обумовлені терміни.