Документ описывает использование API Bitrix24, включая его возможности и архитектуру, начиная с 2010 года и развития маркетплейса с 2013 года. Рассматриваются основные объекты REST API, механизмы авторизации и работа с данными, а также примеры вызовов методов API и работы с приложениями. Также упоминается инфраструктура Bitrix24 и особенности взаимодействия с пользователями через уведомления и календари.

2. API
Битрикс24
-­‐
изнутри,
с
пристрастием
Сербул
Александр
руководитель
направления
контроля
качества
интеграции
и
внедрений
1С-­‐Битрикс
AlexSerbul

3. Битрикс24
–
с
чем
будем
общаться
через
API
Рабочие инструменты в «социальном» формате – в облаке

4. Битрикс
–
Маркетплейс.
С
чего
все
началось.
С 2010 года. Более 1000 решений в каталоге.

5. Битрикс24
–
Маркетплейс
-­‐
развитие
C лета 2013 партнеры и разработчики активно создают приложения.

6. Scrum + SMS = крепкий сон менеджера обеспечен! ;-)
Битрикс24
-­‐
Маркетплейс

7. Установка и запуск приложения в iframe
Битрикс24
-­‐
Маркетплейс

8. Объекты
в
REST
API
Битрикс24:
ü пользователи
и
их
иерархия,
структура
компании
ü отправка
уведомлений
–
email,
push
на
моб.
устройства,
desktop
app.
ü работа
с
задачами
ü CRM
ü календари
ü работа
с
абстрактными
древовидными
данными
(инфоблоками)
Битрикс24
–
REST
API

9. RFC
6749
-­‐
философия
на
тему
редиректов
J
Написали
свой
OAuth2.0
веб-­‐сервис
на
PHP.
Поддержали
самый
полный
flow
–
«4.1.
AuthorizaDon
Code
Grant».
«1.3.1.
Authorizaqon
Code»
–
время
жизни
30
сек.
«3.3.
Access
Token
Scope»
–
поддерживаем
уровни,
не
мельче
модуля
«6.
Refreshing
an
Access
Token»
–
обновляем
Access
Token,
время
жизни
–
1
час
«7.1.
Access
Token
Types»
–
простой
токен
пока
(строка),
думаем
про
MAC
и
подписи
OAuth
2.0
–
детали
поддержки
протокола

10. 1) «Внутреннее»
–
архив
html+js+ресурсы
загружается
в
облако
Битрикс24
2) «Встраиваемое»
-­‐
через
iframe
на
портале
пользователи;
контроллер
iframe
-­‐
на
сайте
партнера/разработчика
3) «Внешнее»
-­‐
доступ
только
к
API
Битрикс24
Типов
может
быть
больше,
думаем
как
их
классифицировать.
Типы
приложений

11. Все
настраивается
в
«личном
кабинете»
разработчика:
• URI
приложения
–
для
контроля
адреса
приложения
и
iframe
• Список
прав
(scope)
–
ограничение
доступа
приложения
к
API
• Пароль
приложения
–
для
получения
Access
Token
Настройка
прав
OAuth
2.0
–
Access
Token
Scope

12. 1.
h€ps://my.bitrix24.ru/oauth/authorize/?
client_id=First_APP&
response_type=code&
redirect_uri=
h"ps://test.com/bitrix/oauth/oauth_test.php
2.
h€ps://test.com/bitrix/oauth/oauth_test.php?
code=xxxxxxxxxxxxxxxxxxxxxxxxxxx
3.
h€ps://my.bitrix24.ru/oauth/token/?
client_id=First_APP&
grant_type=authorizaqon_code&
client_secret=#secret_key#&
redirect_uri=
h"ps://test.com/bitrix/oauth/oauth_test.php
&
code=
xxxxxxxxxxxxxxxxxxxxxxxxxxx&
scope=user
4.
h€ps://test.com/bitrix/oauth/oauth_test.php?
access_token=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
5.
h€ps://my.bitrix24.ru/rest/methods.json?
auth=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy&full=true
{"result":["methods","batch","calendar.event.get",
…]}
Алгоритм
авторизации
-­‐
Authorizaqon
Code
Grant

13. h€ps://имя_портала.bitrix24.ru/oauth/token/?
grant_type=authorizaqon_code&
client_id=код_приложения&
client_secret=секретный_код_приложения&
code=код
авторизации
клиента&
scope=набор_разрешений_приложения&
redirect_uri=URL_приложения
{
"access_token":"код_авторизации","expires_in":3600,
"scope":"набор_разрешений","refresh_token":"код_обновления_авторизации",
"domain":"имя_портала","member_id":"идентификатор_портала“
}
h€ps://имя_портала.bitrix24.ru/oauth/token/?
grant_type=refresh_token&
client_id=код_приложения&
client_secret=секретный_код_приложения&
refresh_token=код_обновления_авторизации&
scope=набор_разрешений_приложения&
redirect_uri=URL_приложения
Обновление
Access
Token

14. https://домен_Б24.bitrix24.{ru|en|de}/rest/имя_метода.транспорт?
параметры_метода&
auth=ключ_авторизации
https://my.bitrix24.ru/rest/methods.xml?auth=d161f25928c3184678924ec127edd29a - получить список доступных
методов в формате xml.
https://my.bitrix24.ru/rest/entity.item.get.json?ENTITY=menu&auth=d161f25928c3184678924ec127edd29a -
получить в формате json список всех элементов сущности menu.
{
"result": результат выполнения метода,
"error": ошибка выполнения метода,
"total": общее количество записей в ответе списочного метода,
"next": число, которое нужно послать для получение следующей страницы
данных списочного метода
}
{
"result": массив результатов запросов пакета,
"result_error": массив ошибок запросов пакета,
"result_total": массив количеств записей в ответах списочных методов,
"result_next": массив чисел, возвращенных в полях next запросов.
}
Структура
запросов/ответов
REST
API

15. ü Прячет
детали
авторизации
ü «Постраничка»
ü Пакетные
запросы
с
макроязыком
подстановки
ü Полезные
callbacks
ü Доступ
к
АПИ
модулей
и
сущностей
<script src="//api.bitrix24.com/api/v1/">
</script>
JS
библиотека-­‐клиент
API
Битрикс24

16. • Вызов
методов
API:
BX24.callMethod('user.get', {ID: 10},
function(res){
if(res.data())
{
var user = res.data()[0];
if(user)
alert('Пользователя №' + user.ID +
' зовут ' + user.NAME);
}
});
JS
библиотека-­‐клиент
API
Битрикс24
• Batch:
BX24.callBatch({
get_user: ['user.current', {}],
get_department: {
method: 'department.get',
params: {
ID: '$result[get_user]
[UF_DEPARTMENT]'
}
}
}, function(result)
{
var l = result.get_department.data().length;
var str = 'Текущий пользователь ' +
result.get_user.data().NAME + ' ' + result.get_user.data().LAST_NAME
+ ' приписан к подразделени' + (l > 1 ? 'ям ' : 'ю ');
for(var i = 0; i < l; i++)
{
str += i == 0 ? '' : ', ';
str += result.get_department.data()[i].NAME;
}
alert(str);
});

17. • Загрузка
файлов
–
имя
и
содержимое
в
base64
<input type="file" id="testfile"><br />
<span onclick="sendInputFile()">send file from input</span><br />
<span onclick="sendStaticFile()">send static file</span><br />
<script type="text/javascript">
function sendInputFile()
{
BX24.callMethod('entity.item.add', {
'ENTITY': 'menu',
'NAME': Math.random(),
'DETAIL_PICTURE': document.getElementById('testfile')
}, function(){
alert('Finished!');
});
}
POST https://my.bitrix24.com/rest/entity.item.add.json HTTP/1.1
Host: my.bitrix24.com
Content-Length: 186
Content-Type: text/plain; charset=UTF-8
Origin: http://app.makssidorenko.bx
auth=6a8c365cb010ba42bd5b0f6ae803f47c&ENTITY=menu&NAME=0.2630483947652045&DETAIL_PICTURE[0]=1.gif&DETAIL_PICTURE[
1]=R0lGODlhAQABAIAAAP%2F%2F%2FwAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw%3D%3D
JS
библиотека-­‐клиент
API
Битрикс24

18. Полезные
плюшки
для
iframe:
void BX24.resizeWindow(Integer width, Integer height[, Function callback])
void BX24.fitWindow([Function callback])
void BX24.reloadWindow()
void BX24.setTitle(String title[, Function callback])
Системные
диалоги:
void BX24.selectUser(Function callback)
void BX24.selectAccess(Function callback)
Сохранение
настроек:
void BX24.userOption.set(String name, String value)
void BX24.userOption.get(String name)
void BX24.appOption.set(String name, String value[, Function callback])
void BX24.appOption.get(String name)
JS
библиотека-­‐клиент
API
Битрикс24

19. Дерево
Сортировка,
фильтрация
Разные
типы
свойств
BX24.callMethod('entity.add', {'ENTITY': 'dish', 'NAME': 'Dishes', 'ACCESS': {U1:'W',AU:'R'}});
BX24.callMethod('entity.get');
{"result":[{"ENTITY":"dish","NAME":"Dishes"},{"ENTITY":"menu","NAME":"Menu"}]}
BX24.callMethod('entity.update', {'ENTITY': 'dish', 'ACCESS': {U1:'W',AU:'R'}});
BX24.callMethod('entity.delete', {'ENTITY': ‘dish'}});
'ENTITY': 'dish‘ – созданный клиентом и уникальный в рамках приложения ID хранилища. Для обеспечения
идемпотентности. Планируем добавить в другие методы.
Хранилище
данных

20. Строим
дерево
из
разделов,
добавляем
элементы
BX24.callMethod('entity.section.add', {ENTITY: 'menu_new', 'NAME': 'Тестовый
раздел', 'SECTION': 34});
BX24.callMethod('entity.item.add', {
ENTITY: 'menu_new',
DATE_ACTIVE_FROM: new Date(),
DETAIL_PICTURE: '',
NAME: 'Hello, world!,
PROPERTY_VALUES: {
test: 11,
test1: 22,
test_file: ''
},
SECTION: 219
});
Хранилище
данных

21. Строим
дерево
из
разделов,
добавляем
элементы,
выборка
BX24.callMethod('entity.item.property.add', {ENTITY: 'menu_new', PROPERTY:
'new_prop', NAME: 'Новое свойство', TYPE: 'S'});
BX24.callMethod('entity.item.get', {
ENTITY: 'menu',
SORT: {DATE_ACTIVE_FROM: 'ASC', ID: 'ASC'},
FILTER: {
'>=DATE_ACTIVE_FROM': dateStart,
'<DATE_ACTIVE_FROM': dateFinish
}
}, $.proxy(this.buildData, this));
Хранилище
данных

22. Нотификация
на
email
и
push-­‐уведомления
пользователям
на
устройства
Android,
iOS.
Инфраструктура
Bitrix
Cloud
Messaging
(BCM):
BX24.selectUser(function(user){
if(user)
{
BX24.callMethod('im.notify', {to: user.id, message: 'Привет, '+user.name+'!'});
}
});
Нотификация
пользователей

23. Календари,
встречи

24. Архитектура
Битрикс24
Elas7c
Load
Balancing
Web
1
Elas7c
Load
Balancing
Dynamic
Web
N
…
CloudWatch
+
AutoScaling
Web
1
Web
2
Web
N
…
CloudWatch
+
AutoScaling
S3
management,
monitoring,
backup
Staqc
CDN
js,
css
Dynamic
Staqc
CDN
js,
css
images
(clients)
images
(clients)
local
cache
local
cache
local
cache
local
cache
local
cache
control
cache:
memcached
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
master-­‐master
replicaqon
master-­‐master
replicaqon
master-­‐master
replicaqon
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
mysqld
control
cache:
memcached
control
cache:
memcached
control
cache:
memcached
control
cache:
memcached
control
cache:
memcached
Web
2
local
cache

25. Спасибо
за
внимание!
Вопросы?
Александр
Сербул
serbul@1c-­‐bitrix.ru
AlexSerbul