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

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

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

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

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

[
  {
    "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 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 изменяется существующая.

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

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

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

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

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

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

Ответ: {«success»:1}.

Ошибка авторизации и общие ошибки описаны в статье Общие сведения. Ошибки приходят с кодом HTTP 200 и success равным 0:

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