# ItemGroup. Номенклатурные группы > Источник: https://wiki.virtualpos.ru/hc/api/itemgroup > Обновлено: 2026-10-08 Методы для работы с иерархией товарных групп: получение списка групп со структурой вложенности, создание, изменение и удаление групп. > **Примечание:** > Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности методов раздела `itemGroup`. ## Методы | Метод | Адрес | Что делает | | --- | --- | --- | | Получить группы | `/api/itemGroup` | Возвращает одну группу или все группы | | Создать или изменить | `/api/itemGroup/update` | Обновляет группу или создаёт новую | | Удалить | `/api/itemGroup/delete` | Удаляет группу вместе с вложенными | > **Важно:** > **Где передавать параметры.** Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Параметры поиска `id` и `external_id` в методах получения и удаления читаются **только из адресной строки (GET)**. В методе `update` все параметры можно передавать и в адресной строке, и в теле POST. Значения с кириллицей и пробелами кодируйте. ## Получение групп ``` GET https://[компания].myvirtualpos.ru/api/itemGroup?apikey=MySecret ``` ### Параметры запроса - **id** — Число. Ид группы. Если указан, возвращается только она. Только GET - **external_id** — Строка. Код группы во внешней системе (например, в 1С). Только GET - **format** — `json` (по умолчанию) или `xml` Если указаны оба параметра, группа должна подходить под оба условия. Без параметров возвращаются все группы одним ответом; постраничной выдачи нет. ### Структура ответа - **success** — `1` — данные получены - **type** — Тип данных, всегда `item_group` - **count** — Количество групп в ответе - **item_groups** — Список групп. Каждая обёрнута в объект `item_group` ### Поля группы Пустые значения в JSON приходят как `null`, в XML — как пустой элемент. - **id** — Число. Ид группы - **external_id** — Строка. Код группы во внешней системе - **name** — Строка. Название группы - **parent_id** — Число. Ид родительской группы. Пусто у групп верхнего уровня - **parent_ext_id** — Строка. Код родительской группы во внешней системе - **not_show_in_shop** — Число. `1` — не показывать группу в интернет-витрине и мобильном приложении - **index_tree** — Строка. Путь группы в иерархии: ид всех предков и самой группы через двоеточие, например `1274:1275:`. Формируется автоматически - **created_date**, **last_update_date** — Строка. Дата и время создания и последнего изменения, формат `гггг-мм-дд чч:мм:сс` ### Пример ответа ```json { "success": 1, "type": "item_group", "count": 2, "item_groups": [ { "item_group": { "id": 1274, "external_id": "GRP-1", "name": "Косметика", "parent_id": null, "parent_ext_id": null, "not_show_in_shop": 0, "index_tree": "1274:", "created_date": "2026-09-26 10:27:21", "last_update_date": "2026-09-26 10:27:21" } }, { "item_group": { "id": 1275, "external_id": "GRP-2", "name": "Шампуни", "parent_id": 1274, "parent_ext_id": "GRP-1", "not_show_in_shop": 1, "index_tree": "1274:1275:", "created_date": "2026-09-26 10:27:21", "last_update_date": "2026-09-26 10:27:21" } } ] } ``` Тот же ответ при `format=xml` (сокращённо): ```xml 1 item_group 2 1274 GRP-1 Косметика ``` ## Создание и изменение группы ``` POST https://[компания].myvirtualpos.ru/api/itemGroup/update?apikey=MySecret&external_id=GRP-2&create_if_not_exist=1 name=Шампуни&parent_ext_id=GRP-1 ``` Группа ищется по `id`, а если он не указан — по `external_id`. Если группа не найдена, а передан `create_if_not_exist=1`, создаётся новая. Изменяются только переданные параметры. ### Параметры - **id** — Число. Ид изменяемой группы - **external_id** — Строка. Код группы во внешней системе. Если `id` не указан, по нему ищется группа; одновременно это поле группы: при создании код сохраняется - **create_if_not_exist** — `1` — создать группу, если она не найдена - **name** — Строка, до 255 символов. Название. Обязательно при создании - **parent_id** — Число. Ид родительской группы; группа должна существовать - **parent_ext_id** — Строка. Код родительской группы во внешней системе. Используется, если не указан `parent_id`; если родитель не найден, вернётся ошибка - **not_show_in_shop** — `1` — не показывать в интернет-витрине и мобильном приложении, `0` — показывать > **Важно:** > **Родителя нельзя убрать.** Пустые `parent_id` и `parent_ext_id` игнорируются, поэтому перенести группу на верхний уровень через API нельзя: меняйте иерархию в панели управления. Значение `not_show_in_shop` проверяется только на число: используйте `0` и `1`. ### Ответ ```json {"success":1,"id":"1275","isnew":"1"} ``` - **success** — `1` — группа сохранена - **id** — Ид группы. При создании приходит строкой, при изменении — числом - **isnew** — `"1"` — группа создана, `"0"` — изменена существующая ## Удаление группы ``` GET https://[компания].myvirtualpos.ru/api/itemGroup/delete?apikey=MySecret&external_id=GRP-2 ``` - **id** — Число. Ид удаляемой группы. Только GET - **external_id** — Строка. Код группы во внешней системе. Только GET Ответ: `{"success":1,"id":1275}`. > **Важно:** > **Вместе с группой удаляются все вложенные группы.** Товары при этом не удаляются. ## Примеры запросов | Задача | Запрос | | --- | --- | | Все группы | `/api/itemGroup?apikey=MySecret` | | Группа по коду из 1С | `/api/itemGroup?apikey=MySecret&external_id=GRP-1` | | Создать группу верхнего уровня | `/api/itemGroup/update?apikey=MySecret&create_if_not_exist=1&external_id=GRP-1&name=%D0%9A%D0%BE%D1%81%D0%BC%D0%B5%D1%82%D0%B8%D0%BA%D0%B0` | | Создать вложенную группу | `/api/itemGroup/update?apikey=MySecret&create_if_not_exist=1&external_id=GRP-2&parent_ext_id=GRP-1&name=Shampoo` | | Скрыть группу в интернет-витрине | `/api/itemGroup/update?apikey=MySecret&external_id=GRP-2¬_show_in_shop=1` | | Удалить группу | `/api/itemGroup/delete?apikey=MySecret&external_id=GRP-2` | ## Ошибки Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Ошибки приходят с кодом HTTP 200 и `success` равным `0`: | Сообщение | Метод | Причина | Что делать | | --- | --- | --- | --- | | You have to specify [id] or [external_id] to update record. Or set [create_if_not_exist] to true to add new record | update | Нет `id`, `external_id` и `create_if_not_exist` | Передайте идентификатор группы или `create_if_not_exist=1` | | Record not found | update, delete | Группа не найдена | Проверьте ид или код | | Parent record with external_id = […] not found | update | Родитель по `parent_ext_id` не найден | Проверьте код родителя | | Data validation failed. … | update | Не заполнено название или значение не прошло проверку | Исправьте указанные поля | | Cannot save data. … | update | Ошибка сохранения; например, `parent_id` указывает на несуществующую группу | Проверьте ссылки на другие записи | | You have to specify [id] to delete record | delete | Нет `id` и `external_id` | Передайте один из них | | Cannot delete data. … | delete | Ошибка удаления | Текст после точки поясняет причину | Если по условиям ничего не найдено, метод получения возвращает успешный ответ с `count` равным `0` и пустым списком `item_groups`. ## Связанные разделы - [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки - [Item. Номенклатура](https://wiki.virtualpos.ru/hc/api/item) — Товары и их принадлежность группам