Бипуим: Документация
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
  • Получить записи
  • Параметр filters — фильтр записей по полям
  • Параметр fields - набор возвращаемых полей записей
  • Параметр id - фильтр записей по id записи
  • Получить запись
  • Создать запись
  • Изменить запись
  • Удалить запись
  1. Интеграции
  2. API
  3. Данные

Записи (Records)

Ресурс Record — запись с данными в каталоге.

Получить записи

URL: /{api url}/catalogs/{catalogId}/records
      {?viewId}
      {?filters}
      {?fields}
      {?searchText}
      {?sortField}{?sortType}
      {?limit}{?offset}

Метод: GET

Параметры:

  • viewId (number) — идентификатор вида каталога для фильтра записей

  • catalogId (number) — идентификатор каталога

  • fields (json array, опционально) — набор возвращаемых полей записей, формат: ["2", "3"]

  • searchText (string, опционально) — быстрый поиск по вхождению

  • sortField (number, опционально) — идентификатор поля для сортировки

  • sortType (number, опционально) — тип сортировки

    • 1 — по возрастанию (по умолчанию)

    • -1 — по убыванию

  • limit (number, опционально) - количество возвращаемых записей (по умолчанию: 100)

  • offset (number, опционально) — смещение от начала списка (по умолчанию: 0)

  • filters (array | json-объект, опционально) — набор фильтров по полям, формат описан ниже

Ответ: 200 OK (application/json)

[{
    "id": "30991",
    "title": "Record title X",
    "values": {
        "2": "Record title X",
        "3": 333,
        "4": ["1"],
        "8": "2015-11-06T21:00:00.000Z",
        "9": ["1"],
        "10": null,
        "14": [{
            "id": "1",
            "title": "Victor Nikitin"
        }],
        "15": [{
            "sectionId": "2",
            "catalogId": "5",
            "catalogTitle": "Clients",
            "catalogIcon": "users-10",
            "recordId": "33",
            "recordTitle": "Companyname 33"
        }]
    }
}, {
    "id": "30990",
    "title": "Record title Y",
    "values": {
        "2": "Record title Y",
        "3": 333,
        "4": ["1"],
        "8": "2015-11-06T21:00:00.000Z",
        "9": ["1"],
        "10": null,
        "14": [{
            "id": "1",
            "title": "Victor Nikitin"
        }],
        "15": [{
            "sectionId": "2",
            "catalogId": "5",
            "catalogTitle": "Clients",
            "catalogIcon": "users-10",
            "recordId": "34",
            "recordTitle": "Companyname 34"
        }]
    }
}]

Параметр filters — фильтр записей по полям

Filters в формате массива (array)

Пример:

http://company.bpium.ru/api/v1/catalogs/21/records
           ?limit=50
           &filters[0][fieldId]=4
           &filters[0][value][at]=2015-10-27T00:00:00+03:00
           &filters[0][value][to]=2015-11-19T23:59:59+03:00
           &filters[1][fieldId]=15
           &filters[1][value][0][catalogId]=18
           &filters[1][value][0][recordId]=9
           &filters[1][value][1][catalogId]=18
           &filters[1][value][1][recordId]=10

filters — массив фильтров. Поэтому в GET-параметрах каждый добавленный к поисковому запросу фильтр имеет свой последовательный идентификатор: filters[№]. Каждый фильтр это объект, состоящий из параметра fieldId (указывает на ID поля для фильтрации данных) и объекта value (параметры поискового запроса). Value для разных типов полей имеет разную структуру.

  filters = [
    {
      fieldId : X,
      value : String, или {}, или [], или [ {}, ... ]
    },
    ...
  ]

Формат параметра value для разных типов полей

  • Для текстовых полей — поиск по вхождению: [value] = текст

  • Для чисел, прогресса — поиск по диапазону: [value][at] = Число1, [value][to] = Число2

  • Для дат — поиск по диапазону: [value][at] = Дата1, [value][to] = Дата2

  • Для категории, набора галочек, вопроса, звёзд — поиск по вхождению: [value][0] = 1, [value][1] = 2. Для категории и вопроса доступен также формат: [value]=[1,2,3,5]

  • Для контактов — поиск по вхождению: [value] = текст

  • Для связанных объектов: [value][0][catalogId]=18, [value][0][recordId]=9 Для связанных объектов также возможен фильтр по полям самих связанных записей, если эти поля выведены в карточке в виде расширенных: value[0][catalogId]=18, value[0][filters][0][fieldId]=5, value[0][filters][0][value]=5

  • Для сотрудников: [value][0]=21, [value][1]=22, [value][2]=CURRENT_USER

Filters в формате JSON-объекта

Это расширенный способ указания фильтров для поиска записей по полям. Он позволяет использовать конструкции И и ИЛИ и их комбинации. Filters в таком формате необходимо передавать GET-параметром со значением в формате сериализованного JSON-объекта.

В примерах ниже значения filters передано без сериализации и в многострочном формате (для наглядности).

  1. Пример указания фильтров по полям:

http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
  filedId1: value1,
  filedId2: value2,
  filedIdX: valueX
}

Где fieldIdX — идентификатор поля, а valueX — значения фильтра по полю (формат для разных полей описан выше).

2. Пример с вариантами значения поля:

http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
  filedId1: { "$or": [ value1_1, value1_2, value1_3 ] },
  filedId2: { "$and": [ value2_1, value2_2, value2_3 ] }
}

Где $or — задает условие, что значение поля у найденных записей должно иметь хотя бы одно из перечисленных значений, $and — задает условие, что значение поля у найденных записей должно содержать (то есть иметь как минимум их) все перечисленные значения.

3. Пример с вариантами условий фильтра по полям:

http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
  "$or" : [
    { fieldId1: value1 },
    { fieldId2: value2 }
  ],
  "$and" : [
    { fieldId3: value3 },
    { fieldId4: value4 }
  ],
}

Где $or — одно из условий фильтра по полям должно быть выполнено, $and — все условия фильтров должны быть выполнены. Условия $or и $and могут быть входить друг в друга.

4. Пример с комбинацией вариантов условий по полям и вариантами значений поля:

http://company.bpium.ru/api/v1/catalogs/21/records?filters=
{
  "$or" : [
    {
       "$and": [
          {filedId1: {"$or": [value1_2, value1_1]}},
          {filedId2: value2},
       ]
    },
    {
       "$and": [
          {filedId3: value3},
          {filedId4: value4},
       ]
    }
  ]
}

Параметр fields - набор возвращаемых полей записей

Параметр fields позволяет ограничить набор полей каталога в получаемых записях. Если параметр не указан, то будут получены значения всех полей. Ограничение списка получаемых полей позволяет уменьшать размер получаемых данных, и увеличивает скорость их получения. Также параметр позволяет получить вложенные поля у связанных записей. fields необходимо передавать в GET-запросе параметром со значением в формате массива приведенного к строковому формату( например, методом JSON.stringify() ). Массив состоит из идентификаторов (API ID) полей каталога, и/или JSON-объектов с описанием вложенных полей связанных записей.

Формат массива для получении обычных полей (без расширенных полей в связанных записях):

[ fieldId1, fieldId2, ... ]

Пример:

[4, 7, 12]

Данный пример получает значения 4, 7 и 12 полей в полученных записях.

Формат JSON-объекта для получения расширенных полей в связанных записях:

{
    fieldId: IDполя1,
    fields: {
      IDкаталога1: [ IDрасширенногоПоля1, IDрасширенногоПоля2, ... ],
      IDкаталога2: [ IDрасширенногоПоля3, IDрасширенногоПоля4, ... ],
      ...
    }
}
  • IDполя1 — поле каталога, из которого получаем записи

  • IDкаталогаХ — Идентификатор каталога связанного в поле IDполя1. Поле «связанный каталог» может иметь несколько источников. Для каждого каталога источника можно указать какие именно поля нужно получить.

  • IDрасширенногоПоляХ — идентификаторы полей связанного каталога, которые нужно получить.

Пример:

{
    fieldId: 5, 
    fields: { 
        27: [ 2, 6 ],
        31: [ 7, 12 ]
    } 
}

Данный пример получает связанные записи из 5-го поля. В связанных записях из 27го каталога получает поля 2 и 6, а в связанных записях из 31го каталога получает поля 7 и 12.

Пример массива с комбинацией получения обычных полей и вложенных полей для связанных записей:

[ {
    fieldId: 5, 
    fields: { 
        27: [2]
    } 
},
{
    fieldId: 9, 
    fields: { 
        19: [3,4]
    }
}, 4, 8 ]

Данный пример получает 4, 5, 8 и 9 поля. Для 5 поля дополнительно получает 2 поле у связанных записей из каталога 27, а для 9 поля — 3 и 4 поле у записей из каталога 19.

Обратите внимание, что массив должен быть приведен к строковому виду для передачи в параметр fields. Так, массив из последнего примера в итоговом виде должен выглядеть так:

[{"fieldId":5,"fields":{"27":[2]}},{"fieldId":9,"fields":{"19":[3,4]}},4,8]

Параметр id - фильтр записей по id записи

Параметр id позволяет получить записи с определенными id. id необходимо передавать в GET-запросе.

Пример:

http://company.bpium.ru/api/v1/catalogs/21/records
    ?id=1
    &id=2

Данный пример получает записи с id 1 и 2.

Получить запись

URL: {domain}/api/v1/catalogs/{catalogId}/records/{recordId}
    {?fields}

Метод: GET

Параметры:

  • catalogId (number) — идентификатор каталога

  • recordId (number) — идентификатор записи

  • fields (json array, опционально) — набор возвращаемых полей записей, формат: ["2", "3"]

Ответ: 200 OK (application/json)

{
    "id": "31007",
    "title": "Record Title",
    "privilegeCode": "access", // право на запись
    "values": {
        "2": "Record Title", // текстовое поле
        "3": 333, // число
        "4": ["1"], // категория, набор галочек, вопрос
        "8": "2015-11-06T21:00:00.000Z", // дата в 0-м часовом поясе
        "11": [{ // контакт
                "contact": "8-901-234-56-78",
                "comment":"основной"
            },{
                "contact":"8-987-654-32-10",
                "comment":""
        }]
        "14": [{ // сотрудник
            "id": "1",
            "title": "Victor Nikitin"
        }],
        "15": [{ // связанный объект
            "sectionId": "2",
            "catalogId": "5",
            "catalogTitle": "Clients",
            "catalogIcon": "users-10",
            "recordId": "33",
            "recordTitle": "Companyname"
        }],
        "16": [{ // файл
            "id": "5",
            "title": "bpium_logo.png",
            "url": "https://..."
            "size": "8513",
            "mimeType": "image/png",
            "metadata": { // уменьшенные копии для изображений
                 "preview" : "https://...",
                 "thumbnail" : "https://..."
            } 
        }]
    }
}
"recordValues": {
    "2": [
        {
            "sectionId": "2",
            "catalogId": "14",
            "catalogTitle": "Связанный каталог",
            "catalogIcon": "leisure-15",
            "recordId": "32",
            "recordTitle": "Наименование записи",
            "isRemoved": false
        }
    ],
    "4": 100
}

Создать запись

URL: {domain}/api/v1/catalogs/{catalogId}/records

Метод: POST

Параметры:

  • catalogId (number) — идентификатор каталога

Запрос: (application/json)

{
    "values": {
        "2": "Text", // текстовое поле
        "3": 333, // число
        "4": ["1","2"], // категория, набор галочек, вопрос
        "8": "2015-11-06T21:00:00.000Z", // дата в 0-м часовом поясе
        "11": [{ // контакт
                "contact": "8-901-234-56-78",
                "comment":"основной"
            },{
                "contact":"8-987-654-32-10",
                "comment":""
        }]
        "14": [{ // сотрудник
            "id": "1"
        }],
        "15": [{ // связанный объект
            "catalogId": "5",
            "recordId": "35"
        }],
        "16": [{ // файл
            "src": "https://link.com/voice.mp3",
            "title": "Awesome voice",
            "mimeType": "audio/mp3" // необязательный параметр
        }]
    }
}

Ответ: 200 OK (application/json)

{
    "id": "31015" // идентификатор созданной записи
}

Изменить запись

URL: {domain}/api/v1/catalogs/{catalogId}/records/{recordId}

Метод: PATCH

Параметры:

  • catalogId (number) — идентификатор каталога

  • recordId (number) — идентификатор записи

Запрос: (application/json)

{
    "values": {
        "2": "text field value",
        "4": ["2", "4"],
        "11": [{ // контакт
                "contact": "8-901-234-56-78",
                "comment":"основной"
            },{
                "contact":"8-987-654-32-10",
                "comment":""
        }]
        "14": [{ // сотрудник
                "id": "2"
            },{
                "id": "3"
            }],
        "15": [{ // связанный объект
                "catalogId": "5",
                "recordId": "33"
            },{
                "catalogId": "5",
                "recordId": "34"
            }],

        "16": [ // файл
            // 96, 97 файлы уже существовали и не были изменены
            {
                "id": "96"
            }, {
                "id": "97"
            }, 
            // прикрепить новый файл, хранящийся на стороннем сервере
            {
                "src": "https://link.com/image.jpg", 
                "title": "Логотип",
                "mimeType": "image/jpeg" // необязательный параметр
            }
        ]
    }
}

Ответ: 200 OK

Удалить запись

URL: {domain}/api/v1/catalogs/{catalogId}/records/{recordId}

Метод: DELETE

Параметры:

  • catalogId (number) — идентификатор каталога

  • recordId (number) — идентификатор записи

Ответ: 200 OK

PreviousКаталоги (Catalogs)NextСвязи (Relations)

Last updated 10 days ago

Для получения записи со значениями расширенных полей используется опция ?withFieldsAdditional=true. В ответ добавляется свойство recordValues, где перечислены каталоги выведенные в расширенной форме и их значения

🔌
"Связанный каталог"