Інтеграція Bitrix24 з мобільним додатком
Bitrix24 надає REST API через OAuth 2.0 — це стандартний та добре задокументований спосіб інтеграції. Більшість методів працюють передбачувано, але є нюанси: обмеження кількості запитів, різні формати даних в різних планах, та невочевидна поведінка вебхуків при певних подіях.
OAuth 2.0 та токени
Bitrix24 використовує OAuth 2.0 Authorization Code Flow. Мобільний додаток відкриває WebView або SFSafariViewController / Chrome Custom Tabs з URL авторизації:
https://{portal}.bitrix24.ru/oauth/authorize/?
client_id={app_id}&
response_type=code&
redirect_uri={deeplink}
Після авторизації надходить code, обмінюється на access_token та refresh_token. access_token живе 1 годину, refresh_token — 30 днів. Оновлення токена — стандартний grant_type=refresh_token. Не забувайте зберігати refresh_token у Keychain/Keystore.
Вебхуки Bitrix24 — спрощений варіант без OAuth. Вхідний вебхук — URL з токеном, через який додаток викликає API без авторизації користувача. Зручно для серверної інтеграції, небезпечно при зберіганні webhook URL на мобільному клієнті (витік дає доступ до портала).
Основні методи API
Робота зі угодами:
// Retrofit
interface Bitrix24Api {
@GET("crm.deal.list")
suspend fun getDeals(
@Query("auth") token: String,
@Query("filter[STAGE_ID]") stageId: String,
@Query("select[]") fields: List<String>,
@Query("start") offset: Int
): Bitrix24ListResponse<Deal>
}
start — зміщення для пагінації. Bitrix24 повертає максимум 50 записів за раз. У відповіді next — наступне зміщення, total — загальна кількість. Для повного завантаження списку потрібні кілька запитів.
Обмеження: 2 запити в секунду при OAuth, 2 запити в секунду на вхідний вебхук. При пакетній синхронізації — використовуйте метод batch: до 50 методів в одному HTTP-запиті:
{
"halt": 0,
"cmd": {
"get_deals": "crm.deal.list?filter[STAGE_ID]=NEW",
"get_contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT"
}
}
Вебхуки для оновлень в реальному часі
Вихідний вебхук Bitrix24 — POST на вказаний URL при подіях (зміна угоди, новий лід). Сервер приймає, розпізнає подію, відправляє push-уведомлення на пристрій.
Bitrix24 відправляє вебхук з полями подіï, але не з повними даними об'єкта — тільки ID та тип події. Потрібен додатковий запит crm.deal.get для отримання актуальних даних. Це додає затримку 1-2 секунди від подіï до відображення в додатку.
Подіï, які найчастіше потрібні: ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMLEADADD, ONCRMACTIVITYADD. Для завдань: ONTASKUPDATE, ONTASKADD.
Телефонія та дзвінки
Bitrix24 реєструє дзвінки через voximplant.infocall.startwithsound або telephony.call.attachbyqueue. Для мобільного додатка можна ініціювати click-to-call: telephony.externalcall.register створює карточку дзвінка в Bitrix24, пов'язує з клієнтом. Після дзвінка — telephony.externalcall.finish з тривалістю та результатом.
Якщо потрібен VoIP прямо в додатку — інтеграція з Voximplant (партнер Bitrix24) або Twilio через Bitrix24 REST.
Терміни
Базова інтеграція (угоди, контакти, завдання) з OAuth та пагінацією: 1-2 тижні. Додавання вебхуків, push-уведомлень та офлайн-буфера: плюс 1 тиждень. Вартість розраховується індивідуально.