Інтеграція Бітрікс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 день.

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

Інтеграція API в мобільний додаток: з чого почати

Запит йде, відповідь не приходить, timeout — 30 секунд. Користувач дивиться на спінер. Мережі немає — мобільна карта в метро. Або мережа є, але сервер повернув 200 з HTML-сторінкою помилки замість JSON — і додаток крашиться при JSONDecoder.decode(). Ми бачимо такі кейси на кожному другому проєкті. Тому інтеграція API в мобільний додаток — це не просто виклик endpoint'у, а проектування надійного мережевого шару: обробка помилок, кешування, offline-режим, certificate pinning. Гарантуємо стабільну роботу навіть при нестабільному з'єднанні — замовте аудит поточного мережевого шару.

Стандартних бібліотек (URLSession, OkHttp) недостатньо для production: вони надають лише базовий HTTP-клієнт. Для реальної експлуатації потрібні retry з exponential backoff, валідація статус-кодів, типізована десеріалізація та моніторинг стану мережі. Без цього додаток втрачає дані та користувачів. Ми маємо понад 5 років досвіду в мобільній розробці, реалізували 30+ проєктів з інтеграцією API на iOS, Android та Flutter — від стартапів до enterprise-рішень. Сертифіковані iOS/Android розробники гарантують якість коду.

Як вибрати протокол для інтеграції API?

REST залишається стандартом для більшості проєктів. Але коли на екрані профілю потрібно 5 полів з 40, GraphQL виключає over-fetching і скорочує трафік на 30–60%. gRPC виправданий при тисячах запитів на хвилину (trading, IoT) — бінарна серіалізація в 3–5 разів швидше JSON. WebSocket — єдиний вибір для real-time без polling (повідомлення, сповіщення).

Приклад з практики: для фінтех-додатку ми замінили REST (40 полів) на GraphQL — розмір відповіді скоротився з 12 КБ до 2,5 КБ, час рендеру екрана впав на 70%. Економія трафіку була значною при 100 000 активних користувачів.

Як забезпечити надійність з'єднання та offline-first?

Користувачі втрачають мережу в метро, ліфті, тунелі. Мобільний додаток зобов'язаний працювати без інтернету — хоча б у read-only режимі. Ми впроваджуємо патерн offline-first:

1. При відкритті екрану спочатку показуємо дані з локального кешу (Core Data / Room).
2. Паралельно виконуємо мережевий запит, оновлюємо UI після відповіді.
3. Якщо мережа недоступна — показуємо кешовані дані та позначку «немає з'єднання».
4. При відновленні мережі автоматично синхронізуємо зміни.

Для кешування HTTP-відповідей використовуємо URLCache (iOS) та OkHttp Cache (Android) з підтримкою Cache-Control. Для структурованих даних — SwiftData / Room. NWPathMonitor / ConnectivityManager.NetworkCallback відстежують стан мережі та тригерять оновлення. Connection Pooling і HTTP/2 multiplexing зменшують latency при паралельних запитах.

REST та вибір клієнтської бібліотеки

Alamofire (iOS) — де-факто стандарт для Swift-проєктів. Поверх URLSession додає request chaining, response validation, automatic retry, certificate pinning через ServerTrustManager. AF.request() з .validate() повертає помилку для будь-якого статус-коду поза 200–299. Без .validate() Alamofire вважає 404 та 500 успішними відповідями. З Swift Concurrency — async-версія через serializingDecodable.

Retrofit (Android) — анотаційний HTTP-клієнт поверх OkHttp. Інтерфейс з анотаціями компілюється в реалізацію. @GET, @POST, @Path, @Query, @Body — декларативний опис API. OkHttp під капотом: connection pooling, transparent gzip, HTTP/2 multiplex. HttpLoggingInterceptor — логування в debug-збірці. Authenticator — автоматичний refresh токена при 401. Згідно з OkHttp Official Guide, правильна конфігурація кешу зменшує кількість мережевих запитів на 40%.

Ktor (KMM/Flutter) — мультиплатформний HTTP-клієнт. На iOS працює через Darwin engine (URLSession), на Android — через OkHttp. Єдиний код для обох платформ при KMM-архітектурі.

GraphQL: коли REST не справляється

REST повертає фіксовану структуру. Екран профілю вимагає name, avatar, email — сервер віддає 40 полів. Over-fetching. GraphQL вирішує це: клієнт запитує рівно потрібні поля. Це критично для мобайлу, де трафік і час парсингу — реальні обмеження. Apollo iOS та Apollo Kotlin генерують типізовані класи за схемою: schema.graphql + query-файли → строгі типи на етапі компіляції. Subscriptions через WebSocket — real-time без polling. Обмеження: GraphQL складніше кешувати на рівні HTTP. Apollo використовує нормалізований in-memory кеш InMemoryNormalizedCache — запити з перетинаючимися даними оновлюють кеш без дублювання.

WebSocket: real-time без зайвого трафіку

Polling (setInterval кожні 5 секунд) — витрата батареї та трафіку. WebSocket — постійне двоспрямоване з'єднання. iOS: URLSessionWebSocketTask (нативний, iOS 13+). Android: OkHttp WebSocket. Обов'язкова обробка reconnect: при onFailure — експоненційний backoff (1с → 2с → 4с → 8с → максимум 60с). Socket.IO — надбудова з автоматичним reconnect, але для нових проєктів краще нативний WebSocket (менше залежностей). TLS 1.3 забезпечує безпеку з'єднання.

Чому важливий certificate pinning?

Корпоративний проксі може перехопити HTTPS через підміну сертифіката. Certificate pinning запобігає цьому: додаток приймає тільки конкретний сертифікат або публічний ключ. Alamofire: ServerTrustManager з PinnedCertificatesTrustEvaluator. OkHttp: CertificatePinner з SHA-256 хешем. Операційна складність: при ротації сертифіката старі версії додатку перестають працювати. Рішення — pinning на публічний ключ CA або підтримка кількох пінів з grace period. Правильне впровадження pinning гарантує захист від MITM-атак.

Що входить у роботу

Ми передаємо: вихідний код мережевого шару, документацію по використовуваних бібліотеках, інструкцію з ротації сертифікатів, підтримку протягом 2 тижнів після здачі.

Терміни та вартість

Реалізація мережевого шару з REST, retry, кешуванням та offline-режимом — 1–2 тижні. Додавання GraphQL або WebSocket — ще 1–2 тижні. gRPC — 2–3 тижні, включаючи кодогенерацію. Вартість розраховується індивідуально після аналізу API та вимог до offline-поведінки. Оцінимо проєкт за 1 день — зв'яжіться з нами для консультації. Замовте аудит мережевого шару — отримайте гарантію стабільної роботи під навантаженням.