Бипуим: Документация
8-800-505-24-05Сайт Бипиум
  • 😎Отвечаем на ваши вопросы
  • 🎂Версии и обновления
  • ❗Обновление до версии 2.0
  • Документация
    • 🆕С чего начать
      • Регистрация и вход
      • Создаем каталоги и записи
      • Формируем отчёты
      • Настраиваем правовую политику
      • Применяем автоматизации
    • ⚙️Конструктор данных
      • Отделы
      • Каталоги
        • Редактирование структуры
        • Настройка отображения
        • Поиск и фильтрация
        • Импорт записей
          • 📗Импорт из Excel
        • Экспорт записей
        • Активность
      • Системные каталоги
        • Сотрудники
        • События
        • Внешние запросы
        • Сценарии
        • Процессы
        • Доступ к сервисам
        • Вебхуки
      • Виды
      • Записи
    • 📊Отчеты
      • Графики
    • 🔑Права
      • Правила
      • Привилегии
      • Правовые группы
      • Правовые виды
      • Права на поля
      • Комбинация прав
    • 🤖Автоматизации
      • События
        • Изменение данных
        • Внешние запросы
      • Сценарии
        • Компоненты
          • Начало процесса
          • Конец процесса
          • Таймер
          • Ошибка
          • Шлюз «ИЛИ» (условное ветвление)
          • Шлюз «И» (распараллеливание)
          • Получить запись
          • Найти записи
          • Изменить запись
          • Создать запись
          • Удалить запись
          • Структура каталога
          • Загрузить файл
          • Сгенерировать документ
          • Назначение переменных
          • Код (Javascript)
          • Веб-запрос
          • SQL-запрос
          • Конвертер
          • Парсер
          • Запуск процесса
          • Получение почты
          • Отправка почты
          • Соединяющая линия
          • Отправить сообщение
        • Переменные
        • Выражения
        • Входные и выходные параметры компонентов
        • Примеры настройки
          • Условие
          • Цикл
      • Ограничения
  • Лицензии
    • 🌐Тип лицензирования
  • Примеры
    • 🔑Права доступа к данным
    • 🤖Автоматизации
      • Выгрузка файлов на Яндекс Диск
      • Отправка на больничный
      • Автоматизация оплаты счетов
      • Создание наименований записей
      • Расчет скидок для клиентов
      • Запрет на создание дубликатов в каталоге
      • Автозаполнение данных по ИНН
      • Переброс данных между связанными каталогами
      • Очередь сценариев
      • Отслеживание заявок с сайта помощью UTM-меток
      • Просрочка задач по дедлайну
      • Реализация механизма согласования записей
      • Массовое изменение записей
      • Создание каталога для рассылки почты
      • Перенос данных между системами Бипиума
      • Импорт данных из Excel
      • Генерация счет-фактуры
      • Генерация excel-отчетов
      • Планировщик задач
      • Импорт банковских выписок
      • Производственный календарь
      • Складской учет
  • Интеграции
    • 🥂Методы интеграции
      • Интеграция данных
        • API
        • Вебхуки (webhooks)
      • Интеграция интерфейса
        • Веб-формы
        • Веб-расширения
      • Примеры интеграций
        • Тильда
          • Прием данных с формы Tilda
          • Интеграция веб-интерфейса в Tilda
        • Интеграция с сервисом «DaData»
        • Интеграция c «Единой информационной системой в сфере закупок»
        • Мессенджеры
          • Интеграция с Telegram-ботом
        • Почтовые сервисы
          • UniSender
          • MailChimp
        • Сервисы Google
          • Google Calendar
        • Телефония
          • Oktell
            • Панель телефонии Oktell
            • Компонент Bpium в Oktell
        • 1C
    • 🔌API
      • Данные
        • Каталоги (Catalogs)
        • Записи (Records)
        • Связи (Relations)
        • Истории (Histories)
        • Файлы (Files)
        • Отделы (Sections)
        • Виды (Views)
        • Сообщения (Messages)
      • Агрегация
        • Разложения (Values)
        • Сводка (Totals)
      • Отчеты
        • Дашборды (Boards)
        • Графики (Widgets)
      • Поисковые выборки
        • Доступные связи (AvailableRecords)
        • Доступные условия фильтра (AvailableFilterRecords)
        • Сотрудники (Users)
        • Контакты (Contacts)
      • Права (Rights)
      • Профиль (Profile/me)
  • Установка на сервер
    • 🧱Архитектура
      • Варианты разворачивания
    • 🖥️Требования
    • 📂Установка как служба
    • 🛳️Установка через Docker
    • 🎛️Мультидоменная среда
    • 🆘Материалы
      • TLS/SSL Сертификат
      • Параметры config.env
        • Для Bpium
        • Для Bpium S3
        • Для Bpium BPM
      • Запуск
      • Обсуживание
        • Активация
        • Обновление
        • Бэкап и восстановление базы
        • Брендирование (Whitelabel)
        • Удаление
      • Перенос базы из облака
      • Возможные проблемы в ходе установки и работы
  • Обучение
    • Базовый курс
      • Урок 1. Отделы
      • Урок 2. Каталоги с данными
      • Урок 3. Карточки записей
      • Урок 4. Связи между данными
      • Урок 5. Фильтры и виды
      • Урок 6. Приглашение сотрудников
      • Урок 7. Права доступа к данным
      • Урок 8. Графические отчеты
      • Урок 9. Бизнес-процессы
      • Урок 10. Интеграции
    • Технический курс
      • Урок 1. Принцип работы автоматизаций
      • Урок 2. Первая автоматизация изнутри
      • Урок 3. Валидация данных
      • Урок 4. Простые вычисления
      • Урок 5. Расчет суммы заказа
      • Урок 6. Генерация счетов/документов
      • Урок 7. Рассылка почтовых сообщений
      • Урок 8. Прием внешних данных
      • Урок 9. Отправка данных на сторонние сервисы
    • Паттерны проектирования ИС
      • Унификация
      • Упорядоченность
      • Разделение
      • Актуализация
      • Вынос параметров
      • Выделение позиций
      • Слияние
      • Дублирование
      • Типизация
      • Информирование
Powered by GitBook
On this page
  • Ресурсы
  • Методы
  • Для каждого метода используется свой тип HTTP-запрос:
  • Формат запросов
  • Доступ к API
  • Авторизация
  • Базовая авторизация
  • Авторизация через POST
  • Авторизация через сессионную Cookie
  • Часовой пояс
  • Коды HTTP-ответов ошибок
  • Лимиты
  • Примеры использования
  • JavaScript (Node.js и во фронте)
  • PHP
  1. Интеграции

API

Previous1CNextДанные

Last updated 11 months ago

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

Ресурсы

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

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

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

  • — список записей каталога с значением полей

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

  • — список операций по изменению записи

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

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

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

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

  • — разложение записей каталога по какому-либо полю с подсчетом сводных значений по другому полю

  • — подсчет сводного значения в каталоге по какому-либо полю

Отчеты:

  • — список экранов с графиками с описанием параметров графиков

  • — значения графика

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

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

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

Системные:

  • Компания (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. Логин и пароль склеиваются через двоеточие и кодируются через функцию Base64. Пример:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Некоторые веб-клиенты позволяют автоматически формировать заголовок базовой авторизации, если логин и пароль передан через URL (пример: https://login:pass@xxx.bpium.ru/...). Браузер Chrome, например, будет так делать, только если сервер пошлет специальный заголовок. Однако, сервер Bpium не отправляет такой заголовок, так как придерживается методологии REST.

В ответ на запрос с базовой авторизацией сервер вернет сессионную cookie sid, или переменную с другим именем (задается в конфигурационном файле сервера). Для компаний в облаке bpium.ru сессионная cookie имеет название connect.sid.

Настоятельно рекомендуется использовать эту сессионную cookie в последующих запросах к серверу, это ускорит работу с API. Базовая авторизация намеренно использует медленный (и длительный) процесс шифрования данных для предотвращения перебора паролей.

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

Авторизоваться в Bpium можно отправив POST-запрос на страницу авторизации:

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

Post-параметры: email и password.

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

Авторизация через сессионную Cookie

Для использования установленной авторизации подписывайте запросы сессионной cookie sid (или переменную с другим именем, которая задается в конфигурационном файле сервера). Для компаний в облаке bpium.ru сессионная cookie имеет название connect.sid.

Формат передачи http-заголовка с сессионной cookie в hhtp-запросе к серверу:

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

Часовой пояс

Сервер Bpium хранит даты в нулевом часовом поясе (UTC). Задача преобразования дат и времени в нужный часовой пояс лежит на стороне получателя (клиента). Однако, некоторые запросы сервера требуют учета часового пояса клиента для выбора данных. Например, поиск записей по датам или построение графиков по датам. Если не передать часовой пояс клиента, то сервер найдет данные, которые не соответствуют ожиданиям клиента.

Для этого инициатор API-запросов указывает часовой пояс через GET-параметр timezoneOffset. Значение параметра следует указывать в минутах. Например, для +3 часового пояса:

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

Коды HTTP-ответов ошибок

  • 400 — некорректный запрос (не верные параметры, не прошла валидация)

  • 401 — ошибка авторизации

  • 402 — необходима оплата лицензии (не действует базовая лицензия)

  • 403 — доступ запрещён по правам

  • 404 — ресурс/объект не найден

  • 405 — метод не разрешён для использования

  • 426 — необходима докупка лицензий (доступ к модулям не входящим в лицензию)

  • 429 — превышено число допустимых запросов (лимит частоты запросов)

  • 500 — неизвестная ошибка сервера (не обработанное исключение в коде сервера)

  • 501 — метод ресурса не существует или не реализован

Лимиты

Бипиум лимитирует число запросов к API. Параметры лимитирования запросов задаются в конфигурационном файле сервера, а так же могут быть изменены для каждой учетной записи (пользователя) индивидуально.

Для облака bpium.ru заданы следующие лимиты числа запросов:

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

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

Если число запросов превышено, Бипиум вернет ошибку с HTTP-кодом 429 (Too Many Requests).

В коробочной версии Bpium Enterprise эти параметры задаются в конфигурационном файле:

  • LIMIT_USER_MAX_REQUESTS (int) — максимальное число запросов от одного аккаунта за интервал. По умолчанию: 100

  • LIMIT_USER_REQUEST_DURATION (int) — интервал оценки числа запросов от одного аккаунта. В миллисекундах. По умолчанию: 30000

  • LIMIT_IP_MAX_REQUESTS (int) — максимальное число запросов с одного IP-адреса за интервал. По умолчанию: 1000

  • LIMIT_IP_REQUEST_DURATION (int) — интервал оценки числа запросов с одного IP-адреса. В миллисекундах. По умолчанию: 30000

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

JavaScript (Node.js и во фронте)

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

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);

— список записей, доступных для связывания в поле типа «связанный объект» (используется в выпадающем списке поля «связанный объект»)

— список сотрудников, доступных в системе (используется в выпадающем списке поля типа Сотрудник)

— список записей, которые можно выбрать как условие фильтра записей в поле типа «связанный объект»

— список записей всей системе с поиском по полю контакт

— список правил на доступ к объекту (отделу, каталогу, виду, записи)

Лайв-события (Changes) — запрос на вызов события «» для запуска сценария обработки значения полей, которые вводит сотрудник в анкете записи

— информация о текущем авторизованном пользователе

Подробнее о стандарте: .

🔌
REST
Каталоги (Catalog)
Записи (Records)
Связи (Relations)
История (Histories)
Файл (Files)
Отделы (Sections)
Виды (Views)
Разложение (Values)
Сводка (Totals)
Дашборды (Boards)
График (Widgets)
Доступные связи (AvailableRecords)
Сотрудники (Users)
Доступные условия фильтра (AvailableFilterRecords)
Контакты (Contacts)
Права (Rights)
Профиль (Profile/me)
Basic authentication
https://www.npmjs.com/package/bp-api
изменено поле время редактирования