Записи (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://..."
            } 
        }]
    }
}

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

"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