# Category. Товарные категории

> Источник: https://wiki.virtualpos.ru/hc/api/category  
> Обновлено: 2026-09-26

Методы для работы с товарными категориями: получение списка категорий вместе с их характеристиками, создание и изменение категорий по одной и пачкой, удаление. Категория определяет набор характеристик (атрибутов), которыми описываются товарные остатки, например размер или объём. О самих характеристиках — в статье [Attribute. Характеристики](https://wiki.virtualpos.ru/hc/api/attribute).

> **Примечание:**
> Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности методов раздела `category`.

## Методы

| Метод | Адрес | Что делает |
| --- | --- | --- |
| Получить категории | `/api/category` | Возвращает все категории с их характеристиками |
| Создать или изменить | `/api/category/update` | Обновляет категорию или создаёт новую |
| Массовое обновление | `/api/category/batchUpdate` | Создаёт и обновляет категории из XML |
| Удалить | `/api/category/delete` | Удаляет категорию |

> **Важно:**
> **Где передавать параметры.** Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Остальные параметры можно передавать и в адресной строке, и в теле POST. Данные категории передаются массивом `category[…]`: используйте POST. Значения с кириллицей и пробелами кодируйте.
>
> **Формат ответа отличается от других методов.** Метод получения возвращает сразу список категорий, без обёртки `success`, `type` и `count`.

## Получение категорий

```
GET https://[компания].myvirtualpos.ru/api/category?apikey=MySecret
```

Параметров, кроме `format`, нет: всегда возвращаются все категории одним ответом.

### Поля категории

Ответ — список объектов `category`:

- **name** — Строка. Название категории
- **system** — Логическое. `true` — системная категория, например «Алкоголь» или «Товар 18+»
- **external_id** — Строка. Код категории во внешней системе
- **attributes** — Список характеристик категории. Каждая обёрнута в объект `attribute` с полем `name` — названием характеристики

> **Важно:**
> В ответе нет ид категории. Чтобы изменить или удалить категорию по ид, узнайте его в панели управления. Для интеграций надёжнее задавать категориям код `external_id` через `batchUpdate` и обращаться по коду.

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

```json
[
  {
    "category": {
      "name": "Одежда",
      "system": false,
      "external_id": "CAT-CLOTHES",
      "attributes": [
        { "attribute": { "name": "Размер" } },
        { "attribute": { "name": "Цвет" } }
      ]
    }
  },
  {
    "category": {
      "name": "Алкоголь",
      "system": true,
      "external_id": null,
      "attributes": []
    }
  }
]
```

Тот же ответ при `format=xml` (без общего корня-обёртки, категории идут друг за другом). Логические значения в XML: `1` для `true` и пустой элемент для `false`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <category>
    <name>Одежда</name>
    <system/>
    <external_id>CAT-CLOTHES</external_id>
    <attributes>
      <attribute><name>Размер</name></attribute>
    </attributes>
  </category>
</root>
```

## Создание и изменение

```
POST https://[компания].myvirtualpos.ru/api/category/update?apikey=MySecret
category[name]=Одежда&category[system]=0
```

Без `id` и `external_id` создаётся новая категория. С `id` или `external_id` изменяется существующая.

### Параметры

- **id** — Число. Ид изменяемой категории. Приоритетнее `external_id`
- **external_id** — Строка. Код категории во внешней системе, по которому ищется изменяемая категория
- **category[name]** — Строка, до 255 символов. Название. Обязательно, должно быть уникальным
- **category[system]** — `0` или `1`. Признак системной категории

Ответ: `{"success":1,"id":11}`. `id` — ид категории.

> **Важно:**
> **Код `external_id` через `update` задать нельзя.** Метод его не записывает: при создании категории код остаётся пустым, а поиск по `external_id` находит только категории, у которых код уже задан. Чтобы создавать категории с кодом во внешней системе, используйте `batchUpdate`.
>
> **Подробности ошибок не выдаются.** При любой ошибке (в том числе при повторяющемся названии) придёт общее сообщение `Could not create category. See error log.`.

## Массовое обновление

```
POST https://[компания].myvirtualpos.ru/api/category/batchUpdate?apikey=MySecret&create_if_not_exists=1
batch=<root><category>…</category></root>
```

Параметр `batch` — XML с категориями. Категория ищется по `id`, а если его нет — по `external_id`.

```xml
<root>
  <category>
    <external_id>CAT-CLOTHES</external_id>
    <name>Одежда</name>
  </category>
  <category>
    <external_id>CAT-SHOES</external_id>
    <name>Обувь</name>
  </category>
</root>
```

- **create_if_not_exists** — `1` — создавать категории, которые не найдены. Без него будут только обновляться существующие. Внимание: в названии параметра `exists`
- **category/id** — Ид категории
- **category/external_id** — Код категории во внешней системе. Записывается только при создании категории
- **category/name** — Название категории. Обновляется у существующих категорий

Ответ: `{"success":1,"errors":"…"}`. В поле `errors` — тексты ошибок по категориям, которые обработать не удалось, разделённые переводом строки; пустая строка означает, что ошибок нет. Успешные категории сохраняются, ошибочные пропускаются.

## Удаление

```
GET https://[компания].myvirtualpos.ru/api/category/delete?apikey=MySecret&id=11
```

- **id** — Число. Ид удаляемой категории

Ответ: `{"success":1}`.

> **Важно:**
> **Вместе с категорией удаляются все её характеристики.** Метод отвечает успехом, даже если категории с таким ид нет. Перед удалением убедитесь, что категория не используется.

## Примеры запросов

| Задача | Запрос |
| --- | --- |
| Все категории | `/api/category?apikey=MySecret` |
| Создать категорию | `POST /api/category/update?apikey=MySecret`, тело: `category%5Bname%5D=Odezhda&category%5Bsystem%5D=0` |
| Переименовать категорию по ид | `POST /api/category/update?apikey=MySecret&id=11`, тело: `category%5Bname%5D=Odezhda2` |
| Создать категории с кодами из 1С | `POST /api/category/batchUpdate?apikey=MySecret&create_if_not_exists=1`, тело: `batch=…` |
| Удалить категорию | `/api/category/delete?apikey=MySecret&id=11` |

## Ошибки

Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Ошибки приходят с кодом HTTP 200 и `success` равным `0`:

| Сообщение | Метод | Причина | Что делать |
| --- | --- | --- | --- |
| Invalid format | update | Не передан массив `category[…]` | Передайте данные как `category[name]=…` |
| category not found | update | Категория с таким `id` или `external_id` не найдена | Проверьте идентификатор |
| Could not create category. See error log. | update | Не заполнено название, название не уникально или другая ошибка сохранения | Проверьте данные; подробности в журнале сервера |
| Please specify id of record | delete | Не указан `id` | Передайте `id` |
| Batch does not exists | batchUpdate | Не передан `batch` | Передайте XML в `batch` |
| Invalid batch format | batchUpdate | `batch` не является корректным XML | Проверьте XML |

Ошибки по отдельным категориям в `batchUpdate` приходят в поле `errors` успешного ответа: `Could not find or create category …` (категория не найдена, а `create_if_not_exists` не указан) и `Could not save category …` (не удалось сохранить).

## Связанные разделы

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Attribute. Характеристики](https://wiki.virtualpos.ru/hc/api/attribute) — Характеристики категорий
- [Item. Номенклатура](https://wiki.virtualpos.ru/hc/api/item) — Товары, у которых можно указать категорию