Долгожданное API для сайтов на 1С-Битрикс
18 декабря 2012
Автор: Заньков Олег
Модуль API позволяет подключаться к данному сайту по протоколу SOAP и производить все необходимые действия (включая административные), не заходя на сайт.
Фактически вы можете превратить сайт в front-end, полностью управляя им из другой системы.
К примеру, можно управлять заказами, товарами, пользователями и прочим в 1С, а вся информация (например, о создании новой скидки на группу товаров) будет отправляться на сайт с помощью SOAP запроса.
Адрес подключения к сервису: /ws/
Для получения информации о функциях зайдите по этому адресу под своим аккаунтом.
В данный момент модуль рботает как административный аккаунт и имеет доступ ко всем модулям и функциям сайта.
Если вы считаете, что модулю критически нехватает какого-то функционала, напишите нам, и мы добавим его в обновление.
Если вы нашли ошибку, сообщите в нашу службу поддержки, и мы быстро исправим её.
Техническая информация
Поскольку API предоставляет низкоуровневые функции, доступ к нему должен быть ограничен паролем. По умолчанию всем функциям необходима предусмотренная Bitrix HTTP — авторизация, в ней передаются логин и пароль от административного аккаунта (желательно использовать https).
Для проверки доступа модуль использует настройки групп пользователей (стандартный вызов $APPLICATION->GetGroupRight)
В основе API лежат оригинальные функции Bitrix.
В API Bitrix получить заказ по ID можно с помощью вызова CSaleOrder::GetByID($ID)
Для выполнения аналогичной операции через API необходимо послать SOAP запрос Order_GetByID(argument), где argument — ID заказа.
На языке PHP это делается так:
API имеет некоторые расширения поверх штатного функционала. К примеру, можно получить заказ сразу со всеми свойствами и корзинами в нём, что уменьшает количество запросов по сети. В таблице списка функций представлена информация о возможных аргументах к каждой функции.
Несколько других примеров:
Добавление элемента в инфоблок
Получение списка пользователей по заданным параметрам (в данном случае ID меньше чем 10)
Обратите внимание, что названия функций соответствуют API Bitrix, а потому, документацию по параметрам можно прочесть в соответствующих разделах справки для разработчиков.
Если в аргументах функции или в типе ответа указано ArrayOf, значит функция принимает или возвращает массив этого типа или массив этих структур.
Например, получение списка пользователей в качестве фильтра принимает массив, каждым элементом которого является структура, представляющая аналог ассоциативного массива для SOAP.
Смотрим на структуру Struct_AssocArray
Таким образом фильтр для пользователей бывших на сайте менее минуты назад с ID более 100 должен выглядеть так:
Для PHP-разработчиков, желающих доработать модуль
В модуль API добавлены события, чтобы Вы могли изменять свойства тех или иных функция для своих нужд.
События модуля linemedia.api "OnClassesGet", "OnStructuresGet" и "OnClassTypesGet" позволяют модифицировать данные, которые предоставляет модуль по умолчанию.
Изначально все параметры и данные, которые используются API - помечены как необязательные. Вот так вы можете сделать их обязательными:
SOAP оперирует наборами данных, которые называются "Структуры". Стурктуры модуля API повторяют объекты Bitrix (пользователь, корзина, заказ, скидка и т.д.). Вы можете модифицировать эти структуры или добавлять свои с помощью соответствующего события:
Если вам недостаточно встроенного функционала, вы можете расширять модуль не только посредством событий, но также и проаналицировав несложную структуру папки/bitrix/modules/linemedia.api/classes/general/api/
В ней содержатся папки модулей, классов и файлы с описаниями.
Вы можете продублировать аналогичную структуру в папке /bitrix/php_interface/api/ и модуль также просканирует её содержимое. Если Вы реализовали функционал, который присутствует в Bitrix, но ещё не реализован нами - пришлите его нам и мы включим его в обновление или сделайте префикс к функциям, чтобы при обновлении Ваш функционал не окаался дублирующим.
Если вы выпускаете свой модуль и хотите чтобы он автоматически добавлялся в API — используйте событие OnModulesScan для добавления в массив своей папки с описаниями функций.
Поскольку SOAP в Bitrix на данный момент имеет некоторые проблемы, используйте вспомогательные фунции вроде clearInput в начале вызовов и formatResponse в конце, чтобы автоматически привести данные к правильному виду и избежать ошибок.
Фактически вы можете превратить сайт в front-end, полностью управляя им из другой системы.
К примеру, можно управлять заказами, товарами, пользователями и прочим в 1С, а вся информация (например, о создании новой скидки на группу товаров) будет отправляться на сайт с помощью SOAP запроса.
Адрес подключения к сервису: /ws/
Для получения информации о функциях зайдите по этому адресу под своим аккаунтом.
В данный момент модуль рботает как административный аккаунт и имеет доступ ко всем модулям и функциям сайта.
Если вы считаете, что модулю критически нехватает какого-то функционала, напишите нам, и мы добавим его в обновление.
Если вы нашли ошибку, сообщите в нашу службу поддержки, и мы быстро исправим её.
Техническая информация
Поскольку API предоставляет низкоуровневые функции, доступ к нему должен быть ограничен паролем. По умолчанию всем функциям необходима предусмотренная Bitrix HTTP — авторизация, в ней передаются логин и пароль от административного аккаунта (желательно использовать https).
Для проверки доступа модуль использует настройки групп пользователей (стандартный вызов $APPLICATION->GetGroupRight)
В основе API лежат оригинальные функции Bitrix.
В API Bitrix получить заказ по ID можно с помощью вызова CSaleOrder::GetByID($ID)
Для выполнения аналогичной операции через API необходимо послать SOAP запрос Order_GetByID(argument), где argument — ID заказа.
На языке PHP это делается так:
$client = new SoapClient(", array("login" => "soap_admin", "password" => "soap_password")); try { $param = new stdClass(); $param->id = 12345; // ID заказа $response = $client->__soapCall("Order_GetByID", array($param)); } catch (SoapFault $e) { echo $e->GetMessage(); $response = null; }
API имеет некоторые расширения поверх штатного функционала. К примеру, можно получить заказ сразу со всеми свойствами и корзинами в нём, что уменьшает количество запросов по сети. В таблице списка функций представлена информация о возможных аргументах к каждой функции.
Несколько других примеров:
Добавление элемента в инфоблок
$param = new stdClass(); $param->iblock_code = "products"; $param->element = array( "NAME" => "Футболка", "PROPERTY_VALUES" => array( array( "CODE" => "color", "NAME" => "Синий", "VALUE" => "blue", ), array( "CODE" => "brand_title", "NAME" => "Бренд", "VALUE" => "Nike", ), ),); $response = $client->__soapCall("IblockElement_Add", array($param));
Получение списка пользователей по заданным параметрам (в данном случае ID меньше чем 10)
$param = new stdClass(); $param->arFilter = array( array( "CODE" => "<ID", "VALUE" => "10", )); $response = $client->__soapCall("User_GetList", array($param));
Обратите внимание, что названия функций соответствуют API Bitrix, а потому, документацию по параметрам можно прочесть в соответствующих разделах справки для разработчиков.
Если в аргументах функции или в типе ответа указано ArrayOf, значит функция принимает или возвращает массив этого типа или массив этих структур.
Например, получение списка пользователей в качестве фильтра принимает массив, каждым элементом которого является структура, представляющая аналог ассоциативного массива для SOAP.
"arFilter" => array("varType" => "ArrayOfStruct_AssocArray", "arrType" => "Struct_AssocArray", "strict" => "no"
Смотрим на структуру Struct_AssocArray
"Struct_AssocArray" = array( "CODE" => array("varType" => "string", "VALUE" => array("varType" => "string",);
Таким образом фильтр для пользователей бывших на сайте менее минуты назад с ID более 100 должен выглядеть так:
$param->arFilter = array( array( "CODE" => ">ID", "VALUE" => "100", ), array( "CODE" => "<LAST_ACTIVITY", "VALUE" => "60",// 1 min ),);
Для PHP-разработчиков, желающих доработать модуль
В модуль API добавлены события, чтобы Вы могли изменять свойства тех или иных функция для своих нужд.
События модуля linemedia.api "OnClassesGet", "OnStructuresGet" и "OnClassTypesGet" позволяют модифицировать данные, которые предоставляет модуль по умолчанию.
Изначально все параметры и данные, которые используются API - помечены как необязательные. Вот так вы можете сделать их обязательными:
AddEventHandler("linemedia.api", "OnMethodsGet", "modifyMethodsAPI";function modifyMethodsAPI(&$methods){ // обязательное поле логина при проверке данных пользователя $methods["CAPIUser"]["User_CheckAuthorization"]["input"]["login"]["strict"] = "strict";}
SOAP оперирует наборами данных, которые называются "Структуры". Стурктуры модуля API повторяют объекты Bitrix (пользователь, корзина, заказ, скидка и т.д.). Вы можете модифицировать эти структуры или добавлять свои с помощью соответствующего события:
AddEventHandler("linemedia.api", "OnStructuresGet", "modifyStructuresAPI"); function modifyStructuresAPI(&$structures) { // Теперь в поле "вес" можно передавать строку, а не число и это делать обязательно // разрешение передавать строку через SOAP не гарантирует того, что Bitrix вставит её в БД именно в таком виде, см. API функций Bitrix. $structures["Struct_Basket"]["WEIGHT"] = array("varType" => "string", "strict" => "strict"); }
Если вам недостаточно встроенного функционала, вы можете расширять модуль не только посредством событий, но также и проаналицировав несложную структуру папки/bitrix/modules/linemedia.api/classes/general/api/
В ней содержатся папки модулей, классов и файлы с описаниями.
Вы можете продублировать аналогичную структуру в папке /bitrix/php_interface/api/ и модуль также просканирует её содержимое. Если Вы реализовали функционал, который присутствует в Bitrix, но ещё не реализован нами - пришлите его нам и мы включим его в обновление или сделайте префикс к функциям, чтобы при обновлении Ваш функционал не окаался дублирующим.
Если вы выпускаете свой модуль и хотите чтобы он автоматически добавлялся в API — используйте событие OnModulesScan для добавления в массив своей папки с описаниями функций.
Поскольку SOAP в Bitrix на данный момент имеет некоторые проблемы, используйте вспомогательные фунции вроде clearInput в начале вызовов и formatResponse в конце, чтобы автоматически привести данные к правильному виду и избежать ошибок.