Каталог решений - Интеграция с Битрикс24 WebHooks [Rest API]

Интеграция Платформы 1С и Битрикс24 может быть реализована либо с помощью готовых решений либо можно написать что-то свое, например какое-то управление задачами. Тут описаны основные моменты которые могут быть не очевидны при разработке интеграции. 

Итак, у Битрикс24 есть система Веб-хуков:

1. Входящие — используется для работы с данными вашего Битрикс24 через API. Позволяет отправлять команды описанные в API в Битрикс24.

2. Исходящие — используется для получения информации о событиях, происходящих в вашем Битрикс24. Позволяет получать изменения происходящие в Битрикс24.

Веб-хуки — способ отправки уведомлений пользователю. Пуш уведомления, только в рамках интеграции.

Настройка входящих веб-хуков

Для этого требуется перейти в раздел "Разработчикам" в своем Битрикс

Далее перейти "Другое"

Открыть раздел "Входящий вебхук"

На странице будет предоставлен адрес вызова rest api вида — https://rs24.bitrix24.ru/rest/<id пользователя>/<идентификатор доступа>/. Нажимаем сохранить и копируем нужные данные. Так же можно задать права для полученной интеграции.

Эти данные требуются для подключения к порталу и отправки уведомлений.

Для этого потребуется выполнить примерно такой код:

// Функция - Отправить запрос
//
// Параметры:
//  Метод			 - Строка	 - имя метода который требуется выполнить
//  Параметры		 - Структура	 - Структура параметров для выполнения метода
//  СтрокаЗапроса	 - Строка	 - Строка запроса сгенерированная заранее, если задана, то не будет генерироваться обработчиком
// 
// Возвращаемое значение:
//   Соотвествие - Результат выполнения метода
//
Функция ОтправитьЗапрос(Метод, Параметры, СтрокаЗапроса = Неопределено)
	
    Идентификатор = ОбщегоНазначения.ЗначениеРеквизитаОбъекта(ПараметрыСеанса.ТекущийПользователь, "Bitrix24_Идентификатор");
	АдресПортала  = "rs24.bitrix24.ru";
	IDПользователя= ОбщегоНазначения.ЗначениеРеквизитаОбъекта(ПараметрыСеанса.ТекущийПользователь, "Bitrix24_ID");
	
	Соединение = Новый HTTPСоединение(АдресПортала,,,,,, Новый ЗащищенноеСоединениеOpenSSL); // Создаем защищенное соединение с порталом.
	Если СтрокаЗапроса = Неопределено Тогда
		СтрокаЗапроса = СформироватьАдресЗапроса(Идентификатор, Параметры, Метод, IDПользователя); //Формируем адрес запроса, по стандарту REST API
	КонецЕсли;
							
	Запрос = Новый HTTPЗапрос(СтрокаЗапроса); // Создает HTTP запрос											
	
	Запрос.УстановитьТелоИзСтроки("");
			
	Ответ = Соединение.Получить(Запрос); // Отправляет на обработку серверу и получаем ответ
	СтрокаОтвета = Ответ.ПолучитьТелоКакСтроку(); // Получаем результат выполнения как строку
	ДанныеJSON	 = РаскодироватьJSON(СтрокаОтвета); //Убираем экранирование символов

	Возврат ПрочитатьJSONНаСервере(ДанныеJSON, Истина); // Читаем JSON

КонецФункции

// Функция - Сформировать адрес запроса
//
// Параметры:
//  СтруктураНастроек		 - Структура	 - Структура настроек
//  ДополнительныеПараметры	 - 	 - 
//  Метод					 - Текст	 - Имя вызываемого метода
// 
// Возвращаемое значение:
// Текст  - Сформированный на основе настроек Адрес запроса
//
Функция  СформироватьАдресЗапроса(Идентификатор, ДополнительныеПараметры, Метод, IDПользователя)
	
	АдресЗапроса = "rest/" + IDПользователя + "/" + Идентификатор + "/" + Метод;
	НомерПараметра = 0;
	Для Каждого Настройка Из ДополнительныеПараметры Цикл
		Если НомерПараметра = 0 Тогда
			АдресЗапроса = АдресЗапроса + "?" + Настройка.Ключ+"=" + Настройка.Значение;			
		Иначе     
			АдресЗапроса = АдресЗапроса + "&" + Настройка.Ключ+"=" + Настройка.Значение; //Если параметр 2 и более то нужно использовать &	
		КонецЕсли;
	КонецЦикла;
		
	Возврат АдресЗапроса;
	
КонецФункции

Для редактирования полей в задачах, немного иная схема строки запроса. Тут нужно передать "массив", но у битрикса он какой-то свой, в отличие от Telegram.

На примере изменения поля "Крайний срок"
 

// Процедура - Изменить крайний срок задачи
//
// Параметры:
//  НомерЗадачи	 - Число	 - Номер задачи
//  НоваяДата	 - Дата	 	 - Новая дата крайнего срока
//
Процедура ИзменитьКрайнийСрокЗадачи(НомерЗадачи, НоваяДата, Отказ) Экспорт
	
	Идентификатор = ОбщегоНазначения.ЗначениеРеквизитаОбъекта(ПараметрыСеанса.ТекущийПользователь, "Bitrix24_Идентификатор");
	IDПользователя= ОбщегоНазначения.ЗначениеРеквизитаОбъекта(ПараметрыСеанса.ТекущийПользователь, "Bitrix24_ID");

	Метод = "tasks.task.update"; // метод для обновления полей задачи
	Параметры = Новый Структура("taskId", Формат(НомерЗадачи, "ЧГ=0")); //параметр taskid обязательный, нужно чтобы понять какую задачу изменять
	
	СтрокаЗапроса = СформироватьАдресЗапроса(Идентификатор, Параметры, Метод, IDПользователя); // Генерим запрос пока по стандарту
	
	СтрокаЗапроса =СтрокаЗапроса + "&fields" + "[DEADLINE]=" + ПреобразоватьДату(НоваяДата, Истина); // Тут добавляем параметр fields и прибавляем к нему поле/поля, в данном случае DEADLINE в скобках []. 
                                                                                                     //После знак = и значение. Причем даты нужны в формате ISO 8601, поэтому преобразовываем его с помощью функции.
	
	Результат = ОтправитьЗапрос(Метод, Параметры, СтрокаЗапроса); //Далее отправляем запрос по стандарту.	
	
	ТекстОшибки = Результат.Получить("error_description"); //Тут проверяем результат на ошибку, может не хватить прав.
	Если ЗначениеЗаполнено(ТекстОшибки) Тогда
		ОбщегоНазначения.СообщитьПользователю(ТекстОшибки,,,,Отказ);
	КонецЕсли;
	
КонецПроцедуры

// Функция - Преобразовать дату
//
// Параметры:
//  ИсхДата		 - Дата	 - Дата которую требуется преобразовать
//  ИСОФормат	 - Булево	 - Нужно преобразовать в ИСО формат, иначе будет декодировано из него.
// 
// Возвращаемое значение:
//   Дата, Неопределено - Преобразованная дата
//
Функция ПреобразоватьДату(ИсхДата , ИСОФормат=Истина)
	
	Если НЕ ЗначениеЗаполнено(ИсхДата) Тогда
      		Возврат Неопределено
	КонецЕсли;
	
    	Если ИСОФормат Тогда
       		Возврат Формат(ИсхДата,"ДФ=yyyy-MM-ddThh:mm:ss");
	Иначе 
       		Возврат XMLЗначение(Тип("Дата"), ИсхДата);
	КонецЕсли 
	
КонецФункции

Настройка исходящих веб-хуков

Тут немного замудреннее, особенно когда не знаешь. 

Тем же путем переходим в раздел "Разработчикам" -> "Другое" -> "Исходящий вебхук"

Далее нужно заполнить URL обработчика по следующим правилам:
http://<адрес или имя>:<внешний порт>/<имя публикации>/hs/<Имя http сервиса, у меня это — Bitrix24>/<имя шаблона, у меня это — WebHook>/<имя метода, у меня это — pushPost>/

Итого примерный адрес — http://223.234.43.23:8323/Bitrix24/hs/Bitrix24/WebHook/pushPost/

IP адрес обязательно должен быть общедоступным, иначе Битрикс не достучится до него.

Токен приложения нужно чтобы проверить из какой интеграции пришел веб-хук.

Далее публикуем http сервис вручную или средствами платформы, если http сервис в расширении, то в ручном варианте.

И чтобы Битрикс попал в базу без авторизации, нужно в настройках подключения к ИБ указать имя пользователя и пароль. 
Также желательно включить отладку, чтобы отлаживать код и данные.

Далее выполняем действия, например создаем или изменяем задачу и получаем запрос от битрикс.

Далее уже начинаем работать с телом запроса.

Раскодируем строку, получим данные из события и обработаем их.
 

// Процедура - Обработать событие
//
// Параметры:
//  Событие	 -  Строка	 - Параметры события произошедшего в Битрикс
//
Процедура ОбработатьСобытие(Событие) Экспорт
 
 	СтрокаБезКодировки = РаскодироватьСтроку(Событие , СпособКодированияСтроки.URLВКодировкеURL);	
	СтруктураСобытия   = ПолучитьСобытиеКакСтруктуру(СтрокаБезКодировки);
	
	Событие = "";
	СтруктураСобытия.Свойство("Событие", Событие);
	Если СтруктураСобытия.Событие = "ONTASKUPDATE" Тогда
    	 	ОбновитьЗадачу(СтруктураСобытия.ID);	
	КонецЕсли;  
	 
 КонецПроцедуры
 
// Функция - Получить событие как структуру
//
// Параметры:
//  СтрокаДанных - 	Строка   - Параметры события произошедшего в Битрикс
// 
// Возвращаемое значение:
//   Структура - Структра данных о событии 
//								Событие - Строка  - Тип события в Битрикс
//								ID - Строка - ID объекта события Битрикс
//
Функция ПолучитьСобытиеКакСтруктуру(СтрокаДанных)
	
    //Тут вроде бы JSON должен быть, но прилетает что-то не то, опытным путем сделал через поиск в строке.

	Результат = Новый Структура();
	
	НачалоСобытия = СтрНайти(СтрокаДанных, "event=")+ 6;
	КонецСобытия  =	СтрНайти(СтрокаДанных, "&", НаправлениеПоиска.СНачала, НачалоСобытия);
	Событие		  = Сред(СтрокаДанных, НачалоСобытия, КонецСобытия- НачалоСобытия);
	Результат.Вставить("Событие", Событие);
	//Получаем ID и событие задачи. Далее уже можно развивать на другие события и делать проверки.
	НачалоID 	  = СтрНайти(СтрокаДанных, "[ID]=",, КонецСобытия)+5;
	КонецID		  = СтрНайти(СтрокаДанных, "&",,НачалоID); 
	ID			  = Сред(СтрокаДанных, НачалоID, КонецID - НачалоID);
	Результат.Вставить("ID", ID);	
	
	Возврат Результат;

КонецФункции // ПолучитьСобытиеКакСтруктуру(СтрокаДанных) 

Далее уже можно свободно читать API Битрикс24 и делать что-то свое. 

Ссылка на API — https://www.bitrix24.ru/apps/api.php.