Перейти к содержаниюСправка

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

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

Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье Общие сведения. Здесь описаны только особенности методов раздела attribute. Категории описаны в статье 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 Строка. Код характеристики во внешней системе

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

[
  { "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 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. 

<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

Ошибки

Ошибка авторизации и общие ошибки описаны в статье Общие сведения. Ошибки приходят с кодом 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 … с причиной (например, не указан тип данных).

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