Товары

Товары — это сущности каталога, которые физически предоставляются клиентам. Для точного контроля использования у каждого товара должна быть установлена единица измерения.

Базовый URL: https://api.planadoapp.com/v2/catalog/products

Список товаров

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/products | jq
{
  "products": [
    {
      "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
      "name": "Кабель (витая пара)",
      "description": "FFTP"
      "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
      "unit_uuid": "58e7de16-693d-4cde-b67b-f318d9e627cd",
      "currency": "rub",
      "external_id": "cable-tp",
      "gtin": null,
      "price_default": "100.0",
      "archived": false
    },
    {
      "uuid": "ee507ae1-5d12-4511-a123-327a4ba0c70f",
      "name": "Пластиковая заглушка",
      "description": null,
      "category_uuid": null,
      "unit_uuid": "8204378f-b7ad-410c-b5af-c747bddb5905",
      "currency": "rub",
      "external_id": "cap",
      "gtin": "96788301",
      "price_default": "15.5",
      "archived": false
    },
    ...
  ]
}
Table 1. Поля элементов products
Поле Тип JSON-тип Может быть null Описание

uuid

UUID

Строка

Нет

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

name

Строка

Строка

Нет

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

description

Строка

Строка

Да

Описание товара

category_uuid

UUID

Строка

Да

UUID категории

unit_uuid

UUID

Строка

Нет

UUID единицы измерения

currency

Строка

Строка

Нет

Код по ISO 4217

external_id

Строка

Строка

Да

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

gtin

Строка

Строка

Да

Global Trade Item Number

price_default

Число

Число

Да

Стоимость товара

archived

Булев

Булев

Нет

Архивирован ли товар

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

Для добавления товара отправьте POST-запрос на адрес https://api.planadoapp.com/v2/catalog/products.

$ curl -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products \
       --data @- <<EOF | jq
{
  "name": "Кабель",
  "unit": {
    "name": "Метр"
  },
  "price_default": "120.5"
}
EOF
{
  "product_uuid": "abbfae98-705a-4b75-af2e-9435a21b39b1"
}
Валюта currency товара берется из настроек вашего аккаунта.

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

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

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

name

Строка

Строка

Да

Нет

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

unit

Единица измерения

Объект

Да

Нет

Единица измерения товара

category

Категория

Объект

Нет

Да

Категория товара

external_id

Строка

Строка

Нет

Да

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

description

Строка

Строка

Нет

Да

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

price_default

Число

Число

Нет

Да

Стоимость товара

gtin

Строка

Строка

Нет

Да

Global Trade Item Number

Получение товара

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

С помощью uuid
$ curl -H "Authorization: Bearer api-key" \
  https://api.planadoapp.com/v2/catalog/products/68fb7a80-43e6-4658-83f4-be8ac7cc70d2 | jq
{
  "product": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Кабель (витая пара)",
    "description": "FFTP"
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "unit_uuid": "58e7de16-693d-4cde-b67b-f318d9e627cd",
    "currency": "rub",
    "external_id": "cable-tp",
    "gtin": null,
    "price_default": "100.0",
    "archived": false
  }
}
С помощью external_id
$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/catalog/products/cable-tp | jq
{
  "product": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Кабель (витая пара)",
     "description": "FFTP"
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "unit_uuid": "58e7de16-693d-4cde-b67b-f318d9e627cd",
    "currency": "rub",
    "external_id": "cable-tp",
    "gtin": null,
    "price_default": "100.0",
    "archived": false
  }
}

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

Для обновления товара отправьте PATCH-запрос на https://api.planadoapp.com/v2/catalog/products/:product_id. Здесь :product_id - это значение uuid или external_id товара.

Обновление gtin существующего товара
$ curl --data "{\"gtin\":\"96788301\"}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planadoapp.com/v2/catalog/products/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "product_uuid": "0a7b6f74-9bd3-434f-8588-c677bac93d4c"
}

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

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

name

Строка

Строка

Нет

Нет

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

unit

Единица измерения

Объект

Нет

Нет

Единица измерения товара

category

Категория

Объект

Нет

Да

Категория товара

description

Строка

Строка

Нет

Да

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

price_default

Число

Число

Нет

Да

Стоимость товара

gtin

Строка

Строка

Нет

Да

Global Trade Item Number

Удаление товара

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

Удаление с помощью uuid
$ curl -H "Authorization: Bearer api-key" -X DELETE https://api.planadoapp.com/v2/catalog/products/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "message": "Performed"
}

Архивация товара

Товары могут быть архивированы и разархивированы. Архивные товары скрываются в интерфейсе. Для переключения отправьте соответствующий POST-запрос на https://api.planadoapp.com/v2/catalog/products/:product_id/archive или https://api.planadoapp.com/v2/catalog/products/:product_id/unarchive.

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