# Attribute. Характеристики

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

Методы для работы с характеристиками (атрибутами) товарных остатков: размер, объём, цвет и подобное. Характеристика принадлежит категории товаров и имеет тип значения. Методы позволяют получить список характеристик, создать, изменить и удалить их.

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

## Методы

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

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

## Типы значений

Тип задаётся полем `data_type`:

| Значение | Тип |
| --- | --- |
| `string` | Строка |
| `int` | Целое число |
| `decimal` | Число с десятичной точкой |

## Получение характеристик

```
GET https://[компания].myvirtualpos.ru/api/attribute?apikey=MySecret&filters%5Bcategory_id%5D=11
```

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

- **filters[…]** — Фильтры по полям характеристики: `filters[id]`, `filters[name]`, `filters[category_id]`, `filters[data_type]`, `filters[external_id]`. Условия объединяются по «и». Неизвестное поле в фильтре даёт ошибку
- **format** — `json` (по умолчанию) или `xml`

Без фильтров возвращаются все характеристики одним ответом.

### Поля характеристики

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

- **id** — Число. Ид характеристики
- **name** — Строка. Название
- **category_id** — Число. Ид категории, к которой относится характеристика
- **data_type** — Строка. Тип значения: `string`, `int` или `decimal`
- **external_id** — Строка. Код характеристики во внешней системе

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

```json
[
  { "attribute": { "id": 1, "name": "Размер", "category_id": 11, "data_type": "string", "external_id": "ATT-SIZE" } },
  { "attribute": { "id": 2, "name": "Объём", "category_id": 13, "data_type": "decimal", "external_id": null } }
]
```

Тот же ответ при `format=xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <attribute>
    <id>1</id>
    <name>Размер</name>
    <category_id>11</category_id>
    <data_type>string</data_type>
    <external_id>ATT-SIZE</external_id>
  </attribute>
</root>
```

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

```
POST https://[компания].myvirtualpos.ru/api/attribute/update?apikey=MySecret
attribute[name]=Размер&attribute[data_type]=string&attribute[category_id]=11
```

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

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

- **id** — Число. Ид изменяемой характеристики. Приоритетнее `external_id`
- **external_id** — Строка. Код характеристики во внешней системе, по которому ищется изменяемая характеристика
- **attribute[name]** — Строка, до 255 символов. Название. Обязательно. Должно быть уникальным в пределах категории
- **attribute[data_type]** — `string`, `int` или `decimal`. Обязательно
- **attribute[category_id]** — Число. Ид категории. Обязательно при создании
- **attribute[category_external_id]** — Строка. Код категории во внешней системе. Заменяет `category_id`, если категория с таким кодом найдена; если не найдена — ошибка

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

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

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

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

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

```xml
<root>
  <attribute>
    <external_id>ATT-SIZE</external_id>
    <name>Размер</name>
    <data_type>string</data_type>
    <category_external_id>CAT-CLOTHES</category_external_id>
  </attribute>
</root>
```

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

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

## Удаление

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

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

Ответ: `{"success":1}`. Метод отвечает успехом, даже если характеристики с таким ид нет.

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

| Задача | Запрос |
| --- | --- |
| Все характеристики | `/api/attribute?apikey=MySecret` |
| Характеристики категории | `/api/attribute?apikey=MySecret&filters%5Bcategory_id%5D=11` |
| Характеристика по названию | `/api/attribute?apikey=MySecret&filters%5Bname%5D=Size` |
| Создать характеристику | `POST /api/attribute/update?apikey=MySecret`, тело: `attribute%5Bname%5D=Size&attribute%5Bdata_type%5D=string&attribute%5Bcategory_id%5D=11` |
| Изменить название | `POST /api/attribute/update?apikey=MySecret&id=1`, тело: `attribute%5Bname%5D=Size2` |
| Удалить | `/api/attribute/delete?apikey=MySecret&id=1` |

## Ошибки

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

| Сообщение | Метод | Причина | Что делать |
| --- | --- | --- | --- |
| Invalid filters. Allowed: […] | получение | В `filters` указано неизвестное поле | Используйте поля из списка в сообщении |
| Invalid attribute data | update | Не передан массив `attribute[…]` | Передайте данные как `attribute[name]=…` |
| attribute not found | update | Характеристика с таким `id` или `external_id` не найдена | Проверьте идентификатор |
| Could not save attribute. See error log for details | update | Ошибка проверки или сохранения | Проверьте название, тип и категорию |
| Attribute does not exists | delete | Не указан `id` | Передайте `id` |
| No batch provided | batchUpdate | Не передан `batch` | Передайте XML в `batch` |
| Invalid batch format | batchUpdate | `batch` не является корректным XML | Проверьте XML |

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

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

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [Category. Товарные категории](https://wiki.virtualpos.ru/hc/api/category) — Категории, к которым относятся характеристики
- [Store. Остатки товара](https://wiki.virtualpos.ru/hc/api/store) — Значения характеристик в остатках