Рассмотрим часто возникающую задачу интеграции платформы 1С:Предприятие с корпоративным порталом Битрикс24. Нам необходимо программно обращаться к порталу, получать списки сущностей (например, задач или сделок) и загружать их в учетную систему. Разберем по шагам, как правильно настроить авторизацию, сформировать HTTP-запрос, получить ответ и распарсить данные в формате JSON.
Первое, с чем мы сталкиваемся при начале работы с API — это вопрос авторизации. Проанализируем два основных способа: использование входящих вебхуков и протокол OAuth 2.0.
Входящий вебхук — это специальный URL-адрес, который генерируется в интерфейсе Битрикс24. Он выступает в роли своеобразного "шнурка", за который можно программно дергать портал через HTTP-запросы. В структуру этого URL уже вшит идентификатор пользователя, от имени которого будут выполняться действия, и уникальный секретный токен. Выглядит он примерно так: https://ваш_портал.bitrix24.ru/rest/ID_пользователя/секретный_код/. Для частной интеграции одной базы 1С с конкретным порталом это самый простой и предпочтительный метод. При возникновении проблем с подключением можно использовать утилиту для проверки доступности вебхука из 1С.
OAuth 2.0 — это более сложный протокол, в котором используется строка авторизации с параметром client_id. Данный метод применяется преимущественно при разработке тиражных приложений для Маркетплейса Битрикс24. В этом случае требуется получать специальный access_token, который действует ограниченное время (обычно час), и регулярно обновлять его с помощью refresh_token.
Важное замечание: При работе через вебхуки передача логина и пароля в параметрах создания объекта HTTPСоединение является избыточной. Входящий вебхук уже самодостаточен. Нам не нужно использовать Basic-авторизацию, достаточно просто обращаться по сгенерированному адресу.
Посмотрим на практический пример получения закрытых задач за определенный период. Мы сформируем запрос, получим ответ и поместим его в объект ТаблицаЗначений.
Для начала инициализируем базовые настройки соединения:
АдресПортала = "ваш_портал.bitrix24.ru";
// Секретный URL вебхука без адреса сервера
ВебхукURL = "rest/1/1234567890abcdef/";
ДатаСреза = ТекущаяДата();
ДатаСрезаЗапроса = Формат(ДатаСреза - 60 * 60 * 24, "ДФ=yyyy-MM-dd; ДЛФ=D");
// Создаем защищенное соединение. Логин и пароль передавать не нужно!
Соединение = Новый HTTPСоединение(АдресПортала, , , , , 5, Новый ЗащищенноеСоединениеOpenSSL);
Теперь сформируем URL для вызова конкретного метода API. В нашем случае это tasks.task.list. Мы используем фильтрацию, чтобы получить задачи, закрытые позже определенной даты, и имеющие статус "5" (завершена).
// Формируем путь и параметры GET-запроса
ПутьКМетоду = ВебхукURL + "tasks.task.list?filter[>CLOSED_DATE]=" + ДатаСрезаЗапроса + "&filter[status]=5";
Запрос = Новый HTTPЗапрос(ПутьКМетоду);
Ответ = Соединение.Получить(Запрос);
// Получаем тело ответа в виде строки (оно придет в формате JSON)
РезультатЗапроса = Ответ.ПолучитьТелоКакСтроку();
Ответ от Битрикс24 всегда приходит в формате JSON. Нам необходимо преобразовать эту строку в понятные для 1С объекты: Соответствия и Массивы. Начиная с версии 1С:Предприятие 8.3.6, платформа имеет мощные встроенные средства для работы с JSON. Нам не нужно писать сложные парсеры, достаточно использовать метод ПрочитатьJSON.
Рассмотрим функцию, которая выполняет это преобразование:
&НаСервере
Функция ПрочитатьJSONНаСервере(СтрокаJSON, ПрочитатьВСоответствие = Истина)
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);
// Функция вернет Соответствие или Структуру в зависимости от флага
Возврат ПрочитатьJSON(ЧтениеJSON, ПрочитатьВСоответствие);
КонецФункции
Применим эту функцию к полученному результату и заполним ТаблицаЗначений:
ОтветСПортала = ПрочитатьJSONНаСервере(РезультатЗапроса, Истина);
// Подготавливаем таблицу значений
ТЗ = Новый ТаблицаЗначений;
ТЗ.Колонки.Добавить("Ответственный");
ТЗ.Колонки.Добавить("НаименованиеЗадачи");
ТЗ.Колонки.Добавить("Заказчик");
// В объекте ОтветСПортала (Соответствие) есть ключ "result", внутри которого "tasks" (Массив)
МассивЗадач = ОтветСПортала.Получить("result").Получить("tasks");
Если МассивЗадач <> Неопределено Тогда
Для Каждого ТекЗадача Из МассивЗадач Цикл
НоваяСтрока = ТЗ.Добавить();
НоваяСтрока.НаименованиеЗадачи = ТекЗадача.Получить("title");
// Получаем вложенные объекты
ОтветственныйДанные = ТекЗадача.Получить("responsible");
Если ОтветственныйДанные <> Неопределено Тогда
НоваяСтрока.Ответственный = ОтветственныйДанные.Получить("name");
КонецЕсли;
ГруппаДанные = ТекЗадача.Получить("group");
Если ГруппаДанные <> Неопределено Тогда
НоваяСтрока.Заказчик = ГруппаДанные.Получить("name");
КонецЕсли;
КонецЦикла;
КонецЕсли;
Проанализируем важный нюанс, который часто упускают начинающие разработчики. REST API Битрикс24 имеет жесткое ограничение: любой списочный метод (например, tasks.task.list, crm.deal.list) возвращает максимум 50 записей за один вызов.
Если по вашему фильтру найдено 150 задач, первый запрос вернет только первые 50. Чтобы получить остальные, нам нужно организовать цикл. В ответе Битрикс24, помимо блока result, есть блок next. Если этот ключ присутствует, значит, есть еще данные.
Доработаем наш алгоритм с учетом пагинации (постраничной навигации):
Старт = 0;
ЕстьЕщеДанные = Истина;
Пока ЕстьЕщеДанные Цикл
// Добавляем параметр start для сдвига выборки
ПутьСПагинацией = ПутьКМетоду + "&start=" + Формат(Старт, "ЧГ=0");
Запрос = Новый HTTPЗапрос(ПутьСПагинацией);
Ответ = Соединение.Получить(Запрос);
ОтветСПортала = ПрочитатьJSONНаСервере(Ответ.ПолучитьТелоКакСтроку(), Истина);
МассивЗадач = ОтветСПортала.Получить("result").Получить("tasks");
// ... обработка элементов массива ...
// Проверяем наличие ключа next
ЗначениеНекст = ОтветСПортала.Получить("next");
Если ЗначениеНекст <> Неопределено Тогда
// Битрикс сам подсказывает, с какого элемента начать следующий запрос
Старт = ЗначениеНекст;
Иначе
ЕстьЕщеДанные = Ложь;
КонецЕсли;
КонецЦикла;
При написании интеграций необходимо помнить про лимиты Битрикс24. Стандартное ограничение — не более 2 обращений к API в секунду. Если ваша 1С начнет выгружать или обновлять данные в быстром цикле (например, создавать сотни документов), портал вернет ошибку "503 Service Unavailable" или "QUOTA_EXCEEDED".
Для решения этой проблемы выясним возможности метода batch. Он позволяет упаковать до 50 независимых команд (вызовов API) в один единственный HTTP-запрос к порталу. Таким образом, вы можете за один вызов создать 50 задач или обновить 50 сделок, обойдя ограничение на количество запросов в секунду.
Разберем еще один частый вопрос: как скачать файл из Битрикс24, если у вас есть только внутренняя ссылка (например, /bizproc/processes/18/file/...). Прямое обращение по такой ссылке через HTTPСоединение вернет страницу авторизации HTML, а не сам файл, так как ссылка требует наличия сессионных cookie браузера.
Правильный алгоритм работы с файлами через API состоит из двух этапов:
disk.file.get), передавая идентификатор файла. В ответ мы получаем JSON с метаданными. Внутри этого ответа будет содержаться ключ DOWNLOAD_URL. Это специальная, сгенерированная порталом временная ссылка, по которой можно скачать бинарные данные файла без дополнительной авторизации.HTTPСоединение (если файл лежит на другом поддомене или используем абсолютный URL) и применяем метод Соединение.Получить(Запрос, ИмяВыходногоФайла). В этом случае 1С автоматически скачает содержимое по временной ссылке и сохранит его на жесткий диск сервера 1С.Мы подробно рассмотрели базовые принципы работы с REST API Битрикс24 из 1С. Использование вебхуков, правильное формирование запросов с учетом пагинации и лимитов, а также штатные средства парсинга JSON позволяют строить надежные и масштабируемые интеграционные решения. Для реализации обратного процесса обмена можно использовать готовое решение для создания задач Битрикс24 из документов 1С.