Розробка локальних застосунків Bitrix24
Локальний застосунок у Bitrix24 — найшвидший спосіб розпочати розробку інтеграції: не потрібно проходити модерацію Market, не потрібен публічний домен на старті (можна використовувати ngrok), не потрібно реєструватися як розробник. Все налаштовується прямо в налаштуваннях порталу за 15 хвилин.
Типовий сценарій: потрібно пов'язати Bitrix24 з внутрішньою системою компанії — 1С, складською програмою або власною CRM. Зовнішній доступ обмежений, публікувати в Market немає сенсу. Саме для таких завдань призначені локальні застосунки.
Реєстрація локального застосунку
Шлях у порталі: Застосунки → Розробникам → Інше → Локальний застосунок.
Параметри при створенні:
-
Тип авторизації:
Серверний застосунок(OAuth) абоJavaScript-застосунок(JS SDK без серверної частини) - Handler URL: адреса вашого застосунку, куди Bitrix24 відкриє iframe при запуску
- Start URL: URL для старту застосунку з меню (може збігатися з Handler URL)
-
Права: набір скоупів —
crm,task,user,disk,catalogтощо
Після створення отримуєте client_id і client_secret. Для JavaScript-типу секрет не потрібен — токен генерується на порталі і передається в iframe через параметри запиту.
Різниця між JavaScript та серверним типом
| Параметр | JavaScript-застосунок | Серверний застосунок |
|---|---|---|
| Авторизація | Токен з параметрів URL/postMessage | OAuth 2.0 Authorization Code |
| Серверна частина | Не потрібна | Обов'язкова |
| Зберігання секрету | Немає секрету | client_secret на сервері |
| Фонова робота | Ні | Так (cron, черги) |
| Підписка на події | Через BX24.js | Через event.bind REST |
| Коли використовувати | UI-віджети, дашборди | Синхронізація, автоматизація |
Розробка 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 http 3000
# Отримуємо: https://abc123.ngrok.io
Цю URL вказуємо як Handler URL у налаштуваннях застосунку.
Обробка 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 — дзвінки та телефонія
Обмеження локальних застосунків
- Працюють лише на одному порталі
- Не можна публікувати в Market
- При зміні домену порталу потрібна переконфігурація
- Немає підтримки кількох redirect_uri
Для більшості внутрішньокорпоративних інтеграцій ці обмеження несуттєві. Якщо в майбутньому знадобиться масштабування — код локального застосунку переноситься в тиражний без кардинального переопрацювання.
Терміни розробки
| Завдання | Термін |
|---|---|
| Налаштування локального застосунку + базова авторизація | 0,5–1 день |
| Простий віджет (лише читання даних CRM) | 1–3 дні |
| Інтеграція з внутрішньою системою (двостороння) | 1–3 тижні |
| Повноцінний корпоративний застосунок | 1–2 місяці |
Локальні застосунки — оптимальний старт для MVP: швидке розгортання, мінімум бюрократії, повний доступ до REST API. Перехід у тиражний формат при необхідності займає 2–3 дні додаткової роботи.