Интеграция Битрикс24 с мобильным приложением
Битрикс24 предоставляет REST API через OAuth 2.0 — это стандартный и хорошо задокументированный способ интеграции. Большинство методов работают предсказуемо, но есть нюансы: лимиты на количество запросов, разные форматы данных в разных планах, и неочевидное поведение webhook'ов при определённых событиях.
OAuth 2.0 и токены
Битрикс24 использует 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.
Webhook'и Битрикс24 — упрощённый вариант без OAuth. Входящий webhook — 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 — offset для пагинации. Битрикс24 возвращает максимум 50 записей за раз. В ответе next — следующий offset, total — общее количество. Для полной загрузки списка нужно несколько запросов.
Лимит: 2 запроса в секунду при OAuth, 2 запроса в секунду на входящий webhook. При пакетной синхронизации — batch метод: до 50 методов за один HTTP-запрос:
{
"halt": 0,
"cmd": {
"get_deals": "crm.deal.list?filter[STAGE_ID]=NEW",
"get_contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT"
}
}
Webhook'и для real-time обновлений
Исходящий webhook Битрикс24 — POST на указанный URL при событии (изменение сделки, новый лид). Сервер принимает, распознаёт событие, отправляет push-уведомление на устройство.
Битрикс24 отправляет webhook с полями события, но не с полными данными объекта — только ID и тип события. Нужен дополнительный запрос crm.deal.get для получения актуальных данных. Это добавляет задержку 1-2 секунды от события до отображения в приложении.
События, которые чаще всего нужны: ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMLEADADD, ONCRMACTIVITYADD. Для задач: ONTASKUPDATE, ONTASKADD.
Телефония и звонки
Битрикс24 фиксирует звонки через voximplant.infocall.startwithsound или telephony.call.attachbyqueue. Для мобильного приложения можно инициировать click-to-call: telephony.externalcall.register создаёт карточку звонка в Битрикс24, связывает с клиентом. После звонка — telephony.externalcall.finish с duration и результатом.
Если нужен VoIP прямо в приложении — интеграция с Voximplant (партнёр Битрикс24) или Twilio через Битрикс24 REST.
Сроки
Базовая интеграция (сделки, контакты, задачи) с OAuth и пагинацией: 1-2 недели. Добавление webhook'ов, push-уведомлений и offline-буфера: плюс 1 неделя. Стоимость рассчитывается индивидуально.