Настройка и использование REST API

Интеграция с Битрикс24 на REST API проходит один и тот же путь независимо от задачи: вы авторизуетесь, вызываете методы, получаете события об изменениях и удерживаете нагрузку в пределах лимитов. Материалы ниже отвечают на практические вопросы каждого этапа — как безопасно обратиться к REST, какой тип приложения выбрать и настроить, чем отличается коробочная версия и как оптимизировать нагрузку.

Описания конкретных методов и их параметров сюда не входят: их смотрите в Справочнике методов. Если вы еще не выполнили ни одного запроса, начните с раздела Первые шаги.

С чего начатьС чего начать

1. Выберите способ авторизации: вебхук для проверки метода и простой интеграции, OAuth 2.0 для приложения — Авторизация в REST
2. Соберите первый запрос и разберите ответ — Как вызывать методы REST API
3. Оформите интеграцию как приложение, если нужны интерфейс, управление доступом или работа от имени разных пользователей — Варианты установки приложений
4. Подпишитесь на нужные события и подготовьте обработчик к пиковой нагрузке — Рекомендации по производительности
5. Проверьте требования безопасности и, для коробочной версии, сетевые доступы перед выходом на клиента — Облако и коробка Битрикс24

Настроить вызовы RESTНастроить вызовы REST

Посмотрите материалы, которые объясняют, как формировать запросы, кодировать данные и получать последовательные выборки.

• Как устроен вызов метода и что учесть в рабочей интеграции — Как вызывать методы REST API.
• Как выглядит базовый запрос и чем отличаются форматы ответов — Как выполняется запрос.
• Как выполнять последовательные вызовы методов и передавать результаты между запросами — Как выполнить пакет запросов batch.
• Что делать, если параметры содержат спецсимволы — Кодирование данных.
• Как правильно получать списки и работать с параметром start — Особенности списочных методов.
• Почему запрос перестал работать после смены домена и как обработать редирект — Особенности вызовов REST при изменении адреса Битрикс24.

Выполнить авторизациюВыполнить авторизацию

Выберите метод авторизации — от простых вебхуков до полного цикла OAuth 2.0, настройте автоматическое продление токенов и обработку ошибок. Метод всегда выполняется от имени конкретного пользователя и ограничен его правами и выданными скоупами.

• Чем отличаются вебхуки и OAuth-протокол — Авторизация в REST.
• Как работает OAuth авторизация шаг за шагом — Полный протокол авторизации OAuth 2.0.
• Как выполнять авторизацию прямо в интерфейсе приложения или через событие установки — Упрощенный вариант получения токенов.
• Как не потерять доступ ночью и когда обновлять refresh_token — Автоматическое продление токенов OAuth 2.0.
• Как разобраться с ошибками invalid_client, insufficient_scope и другими — Коды ошибок.
• Как сохранить работу вебхуков и приложений после увольнения сотрудника — Системный пользователь.

Установить и настроить приложениеУстановить и настроить приложение

Выберите подходящий сценарий и следуйте инструкциям для локальных, тиражных или конфигурационных решений.

• Выбрать подходящий вариант приложения — Варианты установки приложений в Битрикс24.
• Как добавить локальное приложение — Обзор установки локальных приложений.
• Как создать и установить тиражное решение — Обзор установки тиражных приложений.
• Когда нужно вызывать installFinish и что проверить перед запуском — Завершение установки приложений.
• Как публиковать готовые сайты, отраслевые CRM и умные сценарии — Установка шаблонов сайтов, Установка отраслевых CRM, Установка решений с умными сценариями.
• Какие данные удаляются при удалении приложения и как обработать событие удаления — Удаление приложений.

Настроить работу приложения в облаке и коробкеНастроить работу приложения в облаке и коробке

Сравните требования облачной и коробочной версии, настройте сеть и при необходимости расширьте API.

• Что учесть при подготовке приложения к коробке — Облако и коробка Битрикс24.
• Что важно учесть для работы приложения в коробочной версии — Особенности REST API в коробочной версии.
• Почему метод может быть недоступен — Версионность модулей в коробочном Битрикс24.
• Какие домены открыть и где получить список IP для очередей событий — Необходимые сетевые доступы.
• Что делать, если корпоративная сеть изолирована и нужно заменить сервер авторизации — Авторизация приложений в изолированной коробке Битрикс24.
• Как добавить собственные методы и новые скоупы — Добавление своих методов в REST API коробочной версии Битрикс24.
• Какие требования безопасности учитывать при разработке — Рекомендации по безопасности в приложениях на REST API.

Реализовать интерактивный интерфейс и мгновенные событияРеализовать интерактивный интерфейс и мгновенные события

Используйте Push&Pull, чтобы мгновенно реагировать на действия пользователя в интерфейсе.

• Какие варианты интерактивности доступны и какие методы использовать — Интерактивность в приложениях.
• Как принимать сообщения Push&Pull на странице приложения — Push&Pull в браузере.
• Как создать и настроить свой Push&Pull клиент — Собственный Push&Pull клиент.
• Как получить адреса серверов и каналы приложения — pull.application.config.get.
• Как отправить событие в канал приложения — pull.application.event.add.
• Как отправить push-уведомление пользователям приложения — pull.application.push.add.

Оптимизировать работу под нагрузкойОптимизировать работу под нагрузкой

Применяйте рекомендации по оптимизации запросов, работе с очередями и контролю лимитов.

• Как снизить количество запросов и ускорить ответы — Рекомендации по производительности.
• Как выгружать тысячи элементов и избегать подсчета общего количества — Как получить большие объемы данных.
• Как построить входящую очередь и защитить обработчики от всплесков — Входящая очередь событий.
• Какие ограничения действуют для REST API — Лимиты.