Інтеграція Бітрікс24 з мобільним додатком: REST API, вебхуки

Уявіть: менеджер вносить зміни в угоду у веб-версії, а мобільний додаток показує застарілі дані. Клієнти скаржаться на затримки, співробітники витрачають час на ручне введення. Без інтеграції з Бітрікс24 синхронізація відбувається із запізненням на години. Ми вирішуємо цю проблему через REST API, вебхуки та push-сповіщення — ваш додаток отримує актуальну інформацію в реальному часі. Наш досвід: більше 5 років успішних інтеграцій, більше 30 проектів для бізнесу. Економія клієнтів — до 40% операційних витрат. Залиште заявку на оцінку вашого проекту за 1 день.

Процес авторизації OAuth 2.0 для інтеграції Бітрікс24

Згідно з документацією Бітрікс24, OAuth 2.0 є рекомендованим способом авторизації для мобільних додатків. Бітрікс24 використовує Authorization Code Flow. Мобільний додаток відкриває WebView або 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 — це критично для безпеки.

Покрокова інструкція налаштування OAuth 2.0

1. Зареєструйте додаток в Бітрікс24 (Розробникам → Додатки).
2. Вкажіть redirect URI у форматі deep link (наприклад, myapp://oauth).
3. Реалізуйте WebView або Chrome Custom Tabs з URL авторизації, що містить client_id, response_type=code, redirect_uri.
4. Після отримання code виконайте POST-запит на https://oauth.bitrix24.ru/oauth/token/ з grant_type=authorization_code, client_id, client_secret, code, redirect_uri.
5. Збережіть отримані access_token і refresh_token в Keychain/Keystore. Оновлюйте токен за допомогою grant_type=refresh_token щогодини.

Вхідні вебхуки — спрощений варіант без OAuth. URL вебхука містить токен доступу, який дозволяє викликати API без авторизації користувача. Це зручно для серверної інтеграції, але зберігати вебхук на мобільному клієнті небезпечно: витік дає повний доступ до порталу. OAuth 2.0 безпечніший за вхідний вебхук для мобільних додатків.

Основні методи 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 — offset для пагінації. Бітрікс24 повертає максимум 50 записів за раз. У відповіді next — наступний offset, total — загальна кількість. Для повного завантаження списку потрібно послідовно запитувати сторінки, поки next не стане null.

Ліміт запитів: 2 запити в секунду при OAuth та при вхідному вебхуці. Пакетна обробка через batch-метод об'єднує до 50 викликів в один HTTP-запит — це збільшує ефективну пропускну здатність у 50 разів. Порівняно з послідовними запитами, batch-метод прискорює синхронізацію в 50 разів.

{ "halt": 0, "cmd": { "get_deals": "crm.deal.list?filter[STAGE_ID]=NEW", "get_contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT" } } 

Якщо виникають помилки, необхідно обробляти виключення HttpException та IOException. Для автоматичного оновлення токена доцільно використовувати інтерцептор Retrofit, який перехоплює відповідь 401 та виконує оновлення refresh_token.

Batch-метод: прискорення синхронізації

Batch-метод дозволяє виконати до 50 REST-викликів в одному HTTP-запиті. Передається JSON з параметром cmd, де ключі — довільні імена, значення — методи з параметрами. Відповідь містить результати всіх команд. Це зменшує кількість запитів, допомагає обходити ліміти та прискорює синхронізацію великих обсягів даних. Для 1000+ записів використовуйте batch з пагінацією.

Вихідні вебхуки для real-time сповіщення

Вихідний вебхук Бітрікс24 надсилає POST-запит на вказаний URL при настанні події: зміна угоди, новий лід, оновлення завдання. Сервер приймає подію, розпізнає тип та надсилає push-сповіщення на пристрій. Бітрікс24 передає тільки ID та тип події — для отримання повних даних потрібен додатковий запит crm.deal.get. Це додає затримку 1-2 секунди, але забезпечує актуальність. Вихідні вебхуки забезпечують real-time сповіщення швидше ніж періодичний polling у 100 разів.

Події, які найчастіше використовуються:

Для завдань: ONTASKADD, ONTASKUPDATE. Для активностей: ONCRMACTIVITYADD.

Обхід лімітів запитів Бітрікс24

Незалежно від методу авторизації, Бітрікс24 обмежує 2 запити в секунду. При перевищенні повертається помилка WRONG_REQUEST. Пакетна обробка через batch-метод ефективно збільшує пропускну здатність у 50 разів. Для синхронізації великих обсягів використовуйте комбінацію batch та пагінації.

Телефонія та дзвінки

Бітрікс24 фіксує дзвінки через voximplant.infocall.startwithsound або telephony.call.attachbyqueue. Для мобільного додатку можна ініціювати click-to-call: telephony.externalcall.register створює картку дзвінка в Бітрікс24, пов'язує з клієнтом. Після дзвінка — telephony.externalcall.finish з duration та результатом. Для VoIP-дзвінків у додатку — інтеграція з Voximplant або Twilio через REST.

Що входить в роботу з інтеграції?

• Аналітика: розбір поточних процесів, вибір сутностей для синхронізації.
• Проектування: архітектура інтеграції, вибір протоколів (REST/Webhook/Batch), схема tokens.
• Реалізація: налаштування OAuth, розробка клієнта API, реалізація пагінації та offline-буфера.
• Тестування: інтеграційне тестування, навантажувальне тестування до 1000 угод.
• Документація: опис API методів, схеми даних, інструкції для техпідтримки.
• Пост-релізна підтримка: 2 тижні моніторингу, виправлення багів.

Ми гарантуємо стабільну інтеграцію з дотриманням App Store Review Guidelines (Section 5.1) та Google Play Store політик.

Строки та вартість

Базова інтеграція (угоди, контакти, завдання) з OAuth та пагінацією — 1-2 тижні. Додавання вебхуків, push-сповіщень та offline-буфера — плюс 1 тиждень. Вартість розраховується індивідуально, типовий діапазон — від $500 до $2000. Залиште заявку, оцінимо проект за 1 день.

Скорочення часу на синхронізацію та виключення ручного введення знижують операційні витрати — інтеграція окупається за рахунок автоматизації. Зв'яжіться з нами для консультації.