Работа со справочниками

Получение справочников

Общее описание

Функция GET /v6/api/catalogManagement/catalogs позволяет получить список справочников.

Параметры вызова

Функция не имеет дополнительных параметров.

Результат выполнения

Функция возвращает массив структур с параметрами справочников:

Параметр	Описание
catalogExternalID	Внешний ИД справочника
templateID	ИД шаблона справочника
version	Версия справочника
creationDate	Дата создания справочника (подробнее о формате времени).
lastModificationDate	Дата последнего изменения справочника (подробнее о формате времени).
title	Название справочника
description	Описание справочника
hasItems	Есть ли записи в справочнике. Существуют следующие значения: true — в справочнике есть записи; false —— в справочнике нет записей.

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

GET /v6/api/catalogManagement/catalogs HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса

GET /v6/api/catalogManagement/catalogs HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Формат ответа

\{
    "catalogs": [
        \{
            "catalogExternalID": "string",
            "templateID": integer,
            "version": integer,
            "creationDate": "string",
            "lastModificationDate": "string",
            "title": "string",
            "description": "string",
            "hasItems": boolean
        },
        \{
            "catalogExternalID": "string",
            "templateID": integer,
            "version": integer,
            "creationDate": "string",
            "lastModificationDate": "string",
            "title": "string",
            "description": "string",
            "hasItems": boolean
        }
    ]
}

Пример ответа

\{
    "catalogs": [
        \{
            "catalogExternalID": "c9a8bf1e-9327-464b-a0a7-5522044d1367",
            "templateID": 2,
            "version": 0,
            "creationDate": "2024-03-22T12:11:46.697+03:00",
            "lastModificationDate": "2024-03-22T12:11:46.877+03:00",
            "title": "Расходные материалы",
            "description": "Расходные материалы",
            "hasItems": true
        },
        \{
            "catalogExternalID": "ae029ba7-3668-4a07-80b8-9876e195bf62",
            "templateID": 3,
            "version": 2,
            "creationDate": "2023-08-01T06:38:22.79+03:00",
            "lastModificationDate": "2023-08-01T06:57:53.383+03:00",
            "title": "Автоматика и диспетчеризация",
            "description": "Автоматика и диспетчеризация",
            "hasItems": true
        }
    ]
}

Получение справочника

Общее описание

Функция GET /v6/api/catalogManagement/catalogs/{catalogID} позволяет получить список справочников.

Параметры вызова

В запросе используется обязательный параметр catalogID — идентификатор справочника.

Результат выполнения

Функция возвращает структуру с параметрами справочника:

Параметр	Описание
catalogExternalID	Внешний ИД справочника
templateID	ИД шаблона справочника
version	Версия справочника
creationDate	Дата создания справочника (подробнее о формате времени).
lastModificationDate	Дата последнего изменения справочника (подробнее о формате времени).
title	Название справочника
description	Описание справочника
hasItems	Есть ли записи в справочнике. Существуют следующие значения: true — в справочнике есть записи; false —— в справочнике нет записей.

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

GET /v6/api/catalogManagement/catalogs/\{catalogID} HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса

GET /v6/api/catalogManagement/catalogs/1 HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Формат ответа

\{
    "catalogExternalID": "string",
    "templateID": integer,
    "version": integer,
    "creationDate": "string",
    "lastModificationDate": "string",
    "title": "string",
    "description": "string",
    "hasItems": boolean
}

Пример ответа

\{
    "catalogExternalID": "ae029ba7-3668-4a07-80b8-9876e195bf62",
    "templateID": 3,
    "version": 2,
    "creationDate": "2023-08-01T06:38:22.79+03:00",
    "lastModificationDate": "2023-08-01T06:57:53.383+03:00",
    "title": "Автоматика и диспетчеризация",
    "description": "Автоматика и диспетчеризация",
    "hasItems": true
}

Создание справочника

Общее описание

Функция POST /v6/api/catalogManagement/catalogs позволяет создать справочник.

Создать справочник может только пользователь с ролью «Администратор».

Параметры вызова

Функция имеет следующие параметры:

Параметр	Описание
templateID	ИД шаблона справочника
title	Название справочника
description	Описание справочника

Результат выполнения

Функция возвращает структуру с параметрами справочника:

Параметр	Описание
catalogExternalID	Внешний ИД справочника
templateID	ИД шаблона справочника
version	Версия справочника
creationDate	Дата создания справочника (подробнее о формате времени).
lastModificationDate	Дата последнего изменения справочника (подробнее о формате времени).
title	Название справочника
description	Описание справочника
hasItems	Есть ли записи в справочнике. Существуют следующие значения: true — в справочнике есть записи; false —— в справочнике нет записей.

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

POST /v6/api/catalogManagement/catalogs HTTP/1.1
Host: host
Authorization: Bearer token

\{
    "templateID": integer,
    "title": "string",
    "description": "string"
}

Пример запроса

POST /v6/api/catalogManagement/catalogs HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

\{
    "templateID": 1,
    "title": "Справочник",
    "description": "Справочник клиентов"
}

Формат ответа

\{
    "catalogExternalID": "string",
    "templateID": integer,
    "version": integer,
    "creationDate": "string",
    "lastModificationDate": "string",
    "title": "string",
    "description": "string",
    "hasItems": boolean
}

Пример ответа

\{
    "catalogExternalID": "ae029ba7-3668-4a07-80b8-9876e195bf62",
    "templateID": 3,
    "version": 2,
    "creationDate": "2023-08-01T06:38:22.79+03:00",
    "lastModificationDate": "2023-08-01T06:57:53.383+03:00",
    "title": "Автоматика и диспетчеризация",
    "description": "Автоматика и диспетчеризация",
    "hasItems": true
}

Редактирование справочника

Общее описание

Функция PATCH /v6/api/catalogManagement/catalogs/{catalogID} позволяет изменить название и описание справочника.

Редактировать справочник может только пользователь с ролью «Администратор».

Параметры запроса

Функция имеет следующие параметры:

Параметр	Описание
catalogID	ИД справочника
templateID	ИД шаблона справочника
title	Название справочника
description	Описание справочника

Результат выполнения

Функция возвращает структуру с параметрами справочника:

Параметр	Описание
catalogExternalID	Внешний ИД справочника
creationDate	Дата создания справочника (подробнее о формате времени)
title	Название справочника
description	Описание справочника

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

PATCH /v6/api/catalogManagement/catalogs/\{catalogID} HTTP/1.1
Host: host
Authorization: Bearer token

\{
    "title": "string",
    "description": "string"
}

Пример запроса

PATCH /v6/api/catalogManagement/catalogs/1 HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

\{
    "title": "Справочник клиентов",
    "description": "Клиенты всех филиалов"
}

Формат ответа

\{
    "catalogExternalID": "string",
    "creationDate": "string",
    "title": "string",
    "description": "string"
}

Пример ответа

\{
    "catalogExternalID": "ae029ba7-3668-4a07-80b8-9876e195bf62",
    "creationDate": "2023-08-01T06:38:22.79+03:00",
    "title": "Справочник клиентов",
    "description": "Клиенты всех филиалов"
}

Удаление справочника

Общее описание

Функция DELETE /v6/api/catalogManagement/catalogs/{catalogID} позволяет удалить справочник по его идентификатору.

Удалить справочник может только пользователь с ролью «Администратор».

Параметры вызова

В запросе используется обязательный параметр catalogID — идентификатор справочника.

Результат выполнения

При успешном выполнении возвращается статус 204.

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

DELETE /v6/api/catalogManagement/catalogs/\{catalogID} HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса

DELETE /v6/api/catalogManagement/catalogs/1 HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Получение записей справочника

Общее описание

Функция GET /v6/api/catalogManagement/catalogs/{catalogID}/entries позволяет получить записи справочника по его идентификатору.

Параметры вызова

В запросе используется обязательный параметр catalogID — идентификатор справочника.

Результат выполнения

Функция возвращает массив структур с параметрами записей справочника:

Параметр	Описание
entryID	ИД записи справочника
templateItemExternalID	ИД поля шаблона справочника
name	Название поля справочника
value	Значение поля справочника
values	Значения поля справочника (в случае множественного выбора из списка)
type	Тип поля справочника. Существуют следующие значения: 0 — строка; 1 — текст; 2 — дата; 3 — время; 4 — целое число; 5 — вещественное число; 6 — галочка; 7 — список.
subType	Подтип поля «Строка». Существуют следующие значения: 0 — ввод текста. Подтип поля «Целое число». Существуют следующие значения: 0 — ввод целого числа. Подтип поля «Вещественное число». Существуют следующие значения: 0 — ввод числа с плавающей точкой.
fileName	Название вложенного файла
contentType	Тип вложенного файла
contentLength	Размер вложенного файла
version	Версия справочника
templateItemVersion	Версия поля шаблона

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

GET /v6/api/catalogManagement/catalogs/\{catalogID}/entries HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса

GET /v6/api/catalogManagement/catalogs/1/entries HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Формат ответа

\{
  "entries": [
    \{
      "entryID": "string",
      "items": [
        \{
          "templateItemExternalID": "string",
          "name": "string",
          "value": "string",
          "values": [
              "string"
           ],
          "type": integer,
          "subType": integer,
          "fileName": "string",
          "contentType": "string",
          "contentLength": integer,
          "version": integer,
          "templateItemVersion": integer
        },
        \{
          "templateItemExternalID": "string",
          "name": "string",
          "value": "string",
          "values": [
              "string"
           ],
          "type": integer,
          "subType": integer,
          "fileName": "string",
          "contentType": "string",
          "contentLength": integer,
          "version": integer,
          "templateItemVersion": integer
        }
      ]
    }
  ]
}

Пример ответа

\{
  "entries": [
    \{
      "entryID": "b089189d-1531-4c6b-bf0c-7faca5435856",
      "items": [
        \{
          "templateItemExternalID": "1100061",
          "name": "Наименование",
          "value": "Моторное масло",
          "values": null,
          "type": 0,
          "subType": null,
          "fileName": null,
          "contentType": null,
          "contentLength": null,
          "version": 0,
          "templateItemVersion": 1
        },
        \{
          "templateItemExternalID": "1100065",
          "name": "Стоимость (руб)",
          "value": "2000",
          "values": null,
          "type": 4,
          "subType": null,
          "fileName": null,
          "contentType": null,
          "contentLength": null,
          "version": 0,
          "templateItemVersion": 1
        },
        \{
          "templateItemExternalID": "1100066",
          "name": "Количество",
          "value": "10 литров",
          "values": null,
          "type": 0,
          "subType": null,
          "fileName": null,
          "contentType": null,
          "contentLength": null,
          "version": 0,
          "templateItemVersion": 1
        }
      ]
    }
  ]
}

Получение записи справочника по ее идентификатору

Общее описание

Функция GET /v6/api/catalogManagement/catalogs/{catalogID}/entries/{entryID} позволяет получить запись справочника по ее идентификатору.

Параметры вызова

В запросе используются обязательные параметры:

Параметр	Описание
catalogID	ИД справочника
entryID	ИД записи справочника

Результат выполнения

Функция возвращает структуру с параметрами записи справочника:

Параметр	Описание
entryID	ИД записи справочника
templateItemExternalID	ИД поля шаблона справочника
name	Название поля справочника
value	Значение поля справочника
values	Значения поля справочника (в случае множественного выбора из списка)
type	Тип поля справочника. Существуют следующие значения: 0 — строка; 1 — текст; 2 — дата; 3 — время; 4 — целое число; 5 — вещественное число; 6 — галочка; 7 — список.
subType	Подтип поля «Строка»: 0 — ввод текста. Подтип поля «Целое число»: 0 — ввод целого числа. Подтип поля «Вещественное число»: 0 — ввод числа с плавающей точкой.
fileName	Название вложенного файла
contentType	Тип вложенного файла
contentLength	Размер вложенного файла
version	Версия справочника
templateItemVersion	Версия поля шаблона

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

GET /v6/api/catalogManagement/catalogs/\{catalogID}/entries/\{entryID} HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса

GET /v6/api/catalogManagement/catalogs/1/entries/1 HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Формат ответа

\{
  "entryID": "string",
  "items": [
    \{
      "templateItemExternalID": "string",
      "name": "string",
      "value": "string",
      "values": [
          "string"
       ],
      "type": integer,
      "subType": integer,
      "fileName": "string",
      "contentType": "string",
      "contentLength": integer,
      "version": integer,
      "templateItemVersion": integer
    },
    \{
      "templateItemExternalID": "string",
      "name": "string",
      "value": "string",
      "values": [
          "string"
       ],
      "type": integer,
      "subType": integer,
      "fileName": "string",
      "contentType": "string",
      "contentLength": integer,
      "version": integer,
      "templateItemVersion": integer
    }
  ]
}

Пример ответа

\{
  "entryID": "b089189d-1531-4c6b-bf0c-7faca5435856",
  "items": [
    \{
      "templateItemExternalID": "1100061",
      "name": "Наименование",
      "value": "Моторное масло",
      "values": null,
      "type": 0,
      "subType": null,
      "fileName": null,
      "contentType": null,
      "contentLength": null,
      "version": 0,
      "templateItemVersion": 1
    },
    \{
      "templateItemExternalID": "1100065",
      "name": "Стоимость (руб)",
      "value": "2000",
      "values": null,
      "type": 4,
      "subType": null,
      "fileName": null,
      "contentType": null,
      "contentLength": null,
      "version": 0,
      "templateItemVersion": 1
    },
    \{
      "templateItemExternalID": "1100066",
      "name": "Количество",
      "value": "10 литров",
      "values": null,
      "type": 0,
      "subType": null,
      "fileName": null,
      "contentType": null,
      "contentLength": null,
      "version": 0,
      "templateItemVersion": 1
    }
  ]
}

Добавление записей в справочник

Общее описание

Функция POST /v6/api/catalogManagement/catalogs/{catalogID}/entries позволяет добавить записи в справочник.

Добавить запись в справочник могут только пользователи с ролью «Пользователь» (с разрешением «Разрешить редактирование записей справочников») или «Администратор».

Параметры вызова

Функция имеет следующие параметры:

Параметр	Описание
catalogID	ИД справочника
templateItemExternalID	ИД поля шаблона справочника
value	Значение поля справочника
values	Значения поля справочника (в случае множественного выбора из списка)
fileName	Название вложенного файла
contentType	Тип вложенного файла
contentLength	Размер вложенного файла

Результаты выполнения

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

Параметр	Описание
Параметры добавленных записей (addedEntries)
entryID	ИД записи справочника
templateItemExternalID	ИД поля шаблона справочника
name	Название поля справочника
value	Значение поля справочника
values	Значения поля справочника (для множественного выбора)
type	0 — строка; 1 — текст; 2 — дата; 3 — время; 4 — целое число; 5 — вещественное число; 6 — галочка; 7 — список.
subType	Подтип поля «Строка»: 0 — ввод текста. Подтип поля «Целое число»: 0 — ввод целого числа. Подтип поля «Вещественное число»: 0 — ввод числа с плавающей точкой.
fileName	Название вложенного файла
contentType	Тип вложенного файла
contentLength	Размер вложенного файла
version	Версия справочника
templateItemVersion	Версия поля шаблона
Параметры недобавленных записей (notAddedEntries)
entryIndex	Номер записи в запросе, которая не была добавлена (начиная с 0)
errors	Описание ошибки

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

POST /v6/api/catalogManagement/catalogs/\{catalogID}/entries HTTP/1.1
Host: host
Authorization: Bearer token

\{
    "entries": [
        \{
            "items": [
                \{
                    "templateItemExternalID": "string",
                    "value": "string",
                    "values": [
                        "string"
                    ],
                    "fileName": "string",
                    "contentType": "string",
                    "contentLength": integer
                }
            ]
        }
    ]
}

Пример запроса

POST /v6/api/catalogManagement/catalogs/1/entries HTTP/1.1
Host: host
Authorization: Bearer token

\{
    "entries": [
        \{
            "items": [
                \{
                    "templateItemExternalID": "1100061",
                    "value": "Охлаждающая жидкость"
                },
                \{
                    "templateItemExternalID": "1100065",
                    "value": "10000"
                },
                \{
                    "templateItemExternalID": "1100066",
                    "value": "30 литров"
                }
            ]
        }
    ]
}

Формат ответа

\{
    "addedEntries": [
        \{
            "entryID": "string",
            "items": [
                \{
                    "templateItemExternalID": "string",
                    "name": "string",
                    "value": "string",
                    "values": integer,
                    "type": integer,
                    "subType": integer,
                    "fileName": integer,
                    "contentType": integer,
                    "contentLength": integer,
                    "version": integer,
                    "templateItemVersion": integer
                },
                \{
                    "templateItemExternalID": "string",
                    "name": "string",
                    "value": "string",
                    "values": integer,
                    "type": integer,
                    "subType": integer,
                    "fileName": integer,
                    "contentType": integer,
                    "contentLength": integer,
                    "version": integer,
                    "templateItemVersion": integer
                }
            ]
        }
    ],
    "notAddedEntries": [
        \{
            "entryIndex": integer,
            "errors": [
                "string"
            ]
        }
    ]
}

Пример ответа

\{
    "addedEntries": [
        \{
            "entryID": "104004",
            "items": [
                \{
                    "templateItemExternalID": "1100061",
                    "name": "Название",
                    "value": "Охлаждающая жидкость",
                    "values": null,
                    "type": 0,
                    "subType": null,
                    "fileName": null,
                    "contentType": null,
                    "contentLength": null,
                    "version": 2,
                    "templateItemVersion": 1
                },
                \{
                    "templateItemExternalID": "1100065",
                    "name": "Цена",
                    "value": "1000",
                    "values": null,
                    "type": 0,
                    "subType": null,
                    "fileName": null,
                    "contentType": null,
                    "contentLength": null,
                    "version": 2,
                    "templateItemVersion": 1
                }
            ]
        }
    ],
    "notAddedEntries": [
        \{
            "entryIndex": 2,
            "errors": [
                "Введенное в поле «Артикул» значение имеет неверный формат"
            ]
        }
    ]
}

Редактирование записи справочника

Общее описание

Функция PATCH /v6/api/catalogManagement/catalogs/{catalogID}/entries/{entryID} позволяет изменить запись в справочнике.

Изменить запись могут только пользователи с ролью «Пользователь» (с разрешением «Разрешить редактирование записей справочников») или «Администратор».

Параметры вызова

Параметр	Описание
catalogID	ИД справочника
entryID	ИД записи справочника
templateItemExternalID	ИД поля шаблона справочника
value	Значение поля справочника
values	Значения поля справочника (для множественного выбора)
fileName	Название вложенного файла
contentType	Тип вложенного файла
contentLength	Размер вложенного файла

Результат выполнения

Функция возвращает структуру с параметрами записи справочника:

Параметр	Описание
entryID	ИД записи справочника
templateItemExternalID	ИД поля шаблона справочника
name	Название поля справочника
value	Значение поля справочника
values	Значения поля справочника (для множественного выбора)
type	0 — строка; 1 — текст; 2 — дата; 3 — время; 4 — целое число; 5 — вещественное число; 6 — галочка; 7 — список.
subType	Подтип поля «Строка»: 0 — ввод текста. Подтип поля «Целое число»: 0 — ввод целого числа. Подтип поля «Вещественное число»: 0 — ввод числа с плавающей точкой.
fileName	Название вложенного файла
contentType	Тип вложенного файла
contentLength	Размер вложенного файла
version	Версия справочника
templateItemVersion	Версия поля шаблона

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

PATCH /v6/api/catalogManagement/catalogs/\{catalogID}/entries/\{entryID} HTTP/1.1
Host: host
Authorization: Bearer token

[
    \{
        "templateItemExternalID": "string",
        "value": "string",
        "values": [
            "string"
        ],
        "fileName": "string",
        "contentType": "string",
        "contentLength": integer
    }
]

Пример запроса

PATCH /v6/api/catalogManagement/catalogs/1/entries/1 HTTP/1.1
Host: host
Authorization: Bearer token

[
    \{
        "templateItemExternalID": "1100061",
        "value": "3000 руб."
    }
]

Формат ответа

\{
    "entryID": "string",
    "items": [
        \{
            "templateItemExternalID": "string",
            "name": "string",
            "value": "string",
            "values": [
                "string"
            ],
            "type": integer,
            "subType": integer,
            "fileName": "string",
            "contentType": "string",
            "contentLength": integer,
            "version": integer,
            "templateItemVersion": integer
        }
    ]
}

Пример ответа

\{
    "entryID": "1",
    "items": [
        \{
            "templateItemExternalID": "1100061",
            "name": "Цена",
            "value": "3000 руб.",
            "values": null,
            "type": 0,
            "subType": null,
            "fileName": null,
            "contentType": null,
            "contentLength": null,
            "version": 1,
            "templateItemVersion": 1
        }
    ]
}

Удаление записи справочника

Общее описание

Функция DELETE /v6/api/catalogManagement/catalogs/{catalogID}/entries/{entryID} позволяет удалить запись из справочника.

Удалить запись может только пользователь с ролью «Администратор».

Параметры вызова

Параметр	Описание
catalogID	ИД справочника
entryID	ИД записи справочника

Результат выполнения

При успешном выполнении возвращается статус 204.

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

DELETE /v6/api/catalogManagement/catalogs/\{catalogID}/entries/\{entryID} HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса

DELETE /v6/api/catalogManagement/catalogs/1/entries/1 HTTP/1.1
Host: host
Authorization: Bearer token

Работа со справочниками

Содержание