Интеграция Битрикс24 с мобильным приложением через REST API и вебхуки

Интеграция Битрикс24 с мобильным приложением

Представьте: менеджер вносит изменения в сделку в веб-версии, а мобильное приложение показывает устаревшие данные. Клиенты жалуются на задержки, сотрудники тратят время на ручной ввод. Без интеграции с Битрикс24 синхронизация происходит с опозданием на часы. Мы решаем эту проблему через REST API, вебхуки и push-уведомления — ваше приложение получает актуальную информацию в реальном времени. Наш опыт: более 5 лет успешных интеграций, более 30 проектов для бизнеса. Оставьте заявку на оценку вашего проекта за 1 день.

Процесс авторизации OAuth 2.0

Согласно документации Битрикс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 раз.

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

Что такое batch-метод и как он ускоряет синхронизацию?

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

Как исходящие вебхуки обеспечивают real-time уведомления?

Исходящий вебхук Битрикс24 отправляет POST-запрос на указанный URL при наступлении события: изменение сделки, новый лид, обновление задачи. Сервер принимает событие, распознаёт тип и отправляет push-уведомление на устройство. Битрикс24 передаёт только ID и тип события — для получения полных данных требуется дополнительный запрос crm.deal.get. Это добавляет задержку 1-2 секунды, но обеспечивает актуальность.

События, которые чаще всего используются:

Для задач: 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 неделя. Стоимость рассчитывается индивидуально — оставьте заявку, оценим проект за 1 день.

Сокращение времени на синхронизацию и исключение ручного ввода снижают операционные затраты — интеграция окупается за счёт автоматизации. Свяжитесь с нами для консультации.

Интеграция API в мобильное приложение: с чего начать

Запрос уходит, ответ не приходит, timeout — 30 секунд. Пользователь смотрит на спиннер. Сети нет — мобильная карта в метро. Или сеть есть, но сервер вернул 200 с HTML-страницей ошибки вместо JSON — и приложение крашит при JSONDecoder.decode(). Мы видим такие кейсы на каждом втором проекте. Поэтому интеграция API в мобильное приложение — это не просто вызов endpoint'а, а проектирование надёжного сетевого слоя: обработка ошибок, кэширование, offline-режим, certificate pinning. Закажите аудит текущего сетевого слоя — оценим проект за 1 день.

Почему стандартные библиотеки недостаточны? URLSession и OkHttp предоставляют базовый HTTP-клиент, но для production нужны retry с exponential backoff, валидация статус-кодов, типизированная десериализация и мониторинг состояния сети. Без этого приложение теряет данные и пользователей. Мы уже 5 лет занимаемся мобильной разработкой и реализовали более 30 проектов с интеграцией API на iOS, Android и Flutter — от стартапов до enterprise-решений.

Как выбрать протокол для интеграции 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%. Экономия трафика составила около 15 000 ₽ в месяц при 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 отслеживают состояние сети и триггерят обновление.

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.

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 — запросы с пересекающимися данными обновляют кеш без дублирования. Apollo GraphQL Documentation

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 (меньше зависимостей).

gRPC: для высоконагруженных сервисов

gRPC с protobuf — бинарная сериализация: меньше размер, быстрее парсинг. grpc-swift для iOS, grpc-kotlin для Android. Protobuf-схема компилируется в типизированные классы. Streaming (server-side, client-side, bidirectional) — нативная возможность. Порог применения: высокая частота запросов (trading, IoT) или критичная latency. Для обычного CRUD REST проще в дебаге и мониторинге.

Certificate Pinning и безопасность

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

Что входит в работу

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

Сроки и стоимость

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