Категории

Категории используются для группирования товаров и услуг.

Категории товаров и услуг не могут пересекаться. Для них используются разные URL.
Категории иерархичны, у них могут быть родительские категории. В дереве категорий может быть до 3 уровней.

Базовые URL: https://api.planado.ru/v2/catalog/products/categories and https://api.planado.ru/v2/catalog/services/categories

Список категорий

Получение категорий услуг
$ curl -H "Authorization: Bearer api-key" https://api.planado.ru/v2/catalog/services/categories | jq
{
  "categories": [
    {
      "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
      "name": "Доставки",
      "description": null,
      "external_id": "deliveries",
      "parent_uuid": "40ec893e-c928-41cb-8ce9-8c0ab0627f7c",
      "archived": false
    },
    {
      "uuid": "ee507ae1-5d12-4511-a123-327a4ba0c70f",
      "name": "Монтажи",
      "description": "Уличные",
      "external_id": null,
      "parent_uuid": null,
      "archived": false
    },
    ...
  ]
}
Table 1. Поля элементов categories
Поле Тип JSON-тип Может быть null Описание

uuid

UUID

Строка

Нет

Уникальный идентификатор

name

Строка

Строка

Нет

Название категории

description

Строка

Строка

Да

Описание категории

external_id

Строка

Строка

Да

Внешний идентификатор

parent_uuid

UUID

Строка

Да

UUID родительской категории

archived

Булев

Булев

Нет

Архивирована ли категория

Добавление категории

Для добавления категории отправьте POST-запрос.

Добавление категории товаров
$ curl -H "Authorization: Bearer api-key" \
       https://api.planado.ru/v2/catalog/products/categories \
       --data @- <<EOF | jq
{
  "name": "Кабели",
  "parent": {
    "name": "Материалы"
  }
}
EOF
{
  "category_uuid": "abbfae98-705a-4b75-af2e-9435a21b39b1"
}

В ответ API возвращает uuid созданной категории.

Схема запроса

Поле Тип JSON-тип Обязательно Может быть null Описание

name

Строка

Строка

Да

Нет

Название категории. Ограничено 250 символами

parent

Категория

Объект

Нет

Да

Родительская категория

external_id

Строка

Строка

Нет

Да

Внешний идентификатор

description

Строка

Строка

Нет

Да

Описание категории. Ограничено 500 символами

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

Категории могут быть получены по uuid или external_id.

С помощью uuid
$ curl -H "Authorization: Bearer api-key" \
  https://api.planado.ru/v2/catalog/services/categories/68fb7a80-43e6-4658-83f4-be8ac7cc70d2 | jq
{
  "category": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Доставки",
    "description": null,
    "external_id": "deliveries",
    "parent_uuid": "40ec893e-c928-41cb-8ce9-8c0ab0627f7c",
    "archived": false
  }
}
С помощью external_id
$ curl -H "Authorization: Bearer api-key" https://api.planado.ru/v2/catalog/services/categories/deliveries | jq
{
  "category": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Доставки",
    "description": null,
    "external_id": "deliveries",
    "parent_uuid": "40ec893e-c928-41cb-8ce9-8c0ab0627f7c",
    "archived": false
  }
}

Обновление категории

Для обновления категории отправьте PATCH-запрос на https://api.planado.ru/v2/catalog/services/categories/:category_id. Здесь :category_id - это uuid или external_id категории.

Обновление описания существующей категории
$ curl --data "{\"description\":\"Бесплатные\"}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planado.ru/v2/catalog/services/categories/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "category_uuid": "0a7b6f74-9bd3-434f-8588-c677bac93d4c"
}

Схема запроса

Поле Тип JSON-тип Обязательно Может быть null Описание

name

Строка

Строка

Нет

Нет

Название категории. Ограничено 250 символами

parent

Категория

Объект

Нет

Да

Родительская категория

description

Строка

Строка

Нет

Да

Описание категории. Ограничено 500 символами

Удаление категории

Отправьте DELETE-запрос с uuid или external_id для удаления категории.

С помощью uuid
$ curl -H "Authorization: Bearer api-key" -X DELETE https://api.planado.ru/v2/catalog/products/categories/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "message": "Performed"
}

Архивация категории

Категории могут быть архивированы и разархивированы. Архивные категории скрываются в интерфейсе. Для переключения отправьте соответствующий POST-запрос на https://api.planado.ru/v2/catalog/services/categories/:category_id/archive или https://api.planado.ru/v2/catalog/services/categories/:category_id/unarchive (замените services на products в случае необходимости).

Архивация по uuid
$ curl -H "Authorization: Bearer api-key" -X POST "https://api.planado.ru/v2/catalog/services/categories/b8994bf9-e46a-4f4f-9747-6a9f19b5157e/archive" | jq
{
  "category_uuid": "b8994bf9-e46a-4f4f-9747-6a9f19b5157e"
}