API

API Bpium построено на идеологии REST, формат передачи данных — JSON.

Ресурсы

API состоит из ресурсов.

Работа с пользовательскими и системными данными

• Каталоги (Catalog) — список каталогов с описанием структуры полей

• Записи (Records) — список записей каталога со значениями полей

• Связи (Relations) — список записей, которые ссылаются на указанную запись

• История (Histories) — список операций по изменению записи

• Файл (Files) — информация о файле в файловом хранилище

• Отделы (Sections) — список отделов (групп каталогов)

• Виды (Views) — список видов каталога с условиями фильтрации записей

Агрегация / сводные данные

• Разложение (Values) — разложение записей каталога по полю с подсчётом сводных значений

• Сводка (Totals) — подсчёт сводного значения в каталоге по полю

Отчёты

• Дашборды (Boards) — список экранов с графиками и параметрами

• График (Widgets) — значения графика

Дополнительные поисковые выборки

• Доступные связи (AvailableRecords) — список записей, доступных для связывания в поле типа «связанный объект»

• Сотрудники (Users) — список сотрудников, доступных в системе

• Доступные условия фильтра (AvailableFilterRecords) — список записей для условий фильтрации

• Контакты (Contacts) — список записей с поиском по полям контактов

Правовая политика

• Права (Rights) — список правил доступа к объектам

Связанные с событиями и процессами

• Лайв-события (Changes) — вызов события «изменено поле во время редактирования» для обработки вводимых данных

Системные

• Профиль (Profile/me) — информация о текущем пользователе

• Компания (Company) — информация о текущей компании

• Компании (Companies) — список компаний пользователя

• Лицензия (License) — информация о лицензии

Методы

Ресурсы имеют CRUD-методы:

• Create — создание

• Read — получение

• Update — изменение

• Delete — удаление

HTTP-методы

• Получить коллекцию ресурсов — GET

• Получить ресурс — GET

• Создать ресурс — POST

• Изменить ресурс — PATCH

• Удалить ресурс — DELETE

Формат запросов

API Бипиума использует формат передачи данных JSON, кодировка utf-8.

HTTP-заголовок:

content-type: application/json

Доступ к API

Относительный адрес API

/api/v1/{ресурс}/{?ID-объекта}

Адрес API в облаке

https://{вашдомен}.bpium.ru/api/v1/{ресурс}/{?ID-объекта}

Авторизация

Запросы к API проходят проверку прав доступа. Все запросы выполняются от имени сотрудника, права которого используются при обработке запросов.

Базовая авторизация

Параметры передаются через HTTP-заголовок Authorization.

Пример:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Подробнее о стандарте: Basic authentication

Авторизация через POST

Можно отправить POST-запрос на адрес:

https://{вашдомен}.bpium.ru/auth/login

Параметры:

• email

• password

Авторизация через Cookie

Пример HTTP-заголовка:

cookie: connect.sid=значение; другиеКуки=...

Часовой пояс

Сервер Bpium хранит даты в UTC.

Для корректной обработки дат клиент должен передавать параметр timezoneOffset в минутах.

Пример для UTC+3:

https://{вашдомен}.bpium.ru/api/v1/catalogs/5?timezoneOffset=180

Коды HTTP-ответов

Лимиты / Ограничения

Бипиум ограничивает количество запросов к API.

Для облака bpium.ru действуют лимиты:

• 100 запросов за 30 секунд для одной учётной записи

• 500 запросов за 30 секунд для одного IP-адреса

При превышении лимита сервер возвращает ошибку:

429 Too Many Requests

Параметры лимитов в Enterprise

• LIMIT_USER_MAX_REQUESTS — лимит запросов пользователя

• LIMIT_USER_REQUEST_DURATION — интервал проверки пользователя

• LIMIT_IP_MAX_REQUESTS — лимит запросов IP

• LIMIT_IP_REQUEST_DURATION — интервал проверки IP

Примеры использования

JavaScript (Node.js и frontend)

Публичная библиотека:

https://www.npmjs.com/package/bp-api

PHP

Пример создания записи:

// домен и авторизация
$domen = 'ВАШДОМЕН.bpium.ru';
$user = 'abc@mail.ru';
$pass = 'mypass';

// номер каталога
$catalog_id = 13;

// значения полей
$values = array();
$values['2'] = '';
$values['3'] = array('1');
$values['4'] = 17;
$values['5'] = date('Y-m-d') . "T" . date('H:i:s') . "+04:00";

// тело запроса
$data = array();
$data['values'] = $values;
$data_json = json_encode($data);

// HTTP-запрос
$ch = curl_init("https://$domen/api/v1/catalogs/$catalog_id/records");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$user:$pass");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_json))
);

$result = curl_exec($ch);