Услуги

Услуги — это сущности каталога, которые нефизически предоставляются клиентам.

Базовый URL: https://api.planado.ru/v2/catalog/services

Список услуг

$ curl -H "Authorization: Bearer api-key" https://api.planado.ru/v2/catalog/services | jq
{
  "services": [
    {
      "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
      "name": "Доставка",
      "description": "С подъемом на этаж",
      "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
      "currency": "rub",
      "external_id": "delivery",
      "price_default": "1599.99",
      "archived": false
    },
    {
      "uuid": "ee507ae1-5d12-4511-a123-327a4ba0c70f",
      "name": "Установка розетки",
      "description": null,
      "category_uuid": null,
      "currency": "rub",
      "external_id": null,
      "price_default": "1000.0",
      "archived": false
    },
    ...
  ]
}

Table 1. Поля элементов `services`
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Уникальный идентификатор
`name`	Строка	Строка	Нет	Название услуги
`description`	Строка	Строка	Да	Описание услуги
`category_uuid`	UUID	Строка	Да	UUID категории
`currency`	Строка	Строка	Нет	Код по ISO 4217
`external_id`	Строка	Строка	Да	Внешний идентификатор
`price_default`	Число	Число	Да	Стоимость услуги
`archived`	Булев	Булев	Нет	Архивирована ли услуга

Добавление услуги

Для добавления услуга отправьте POST-запрос на адрес https://api.planado.ru/v2/catalog/services.

$ curl -H "Authorization: Bearer api-key" \
       https://api.planado.ru/v2/catalog/services \
       --data @- <<EOF | jq
{
  "name": "Страхование",
  "category": {
    "name": "Отдел обслуживания клиентов"
  },
  "price_default": "4000.0"
}
EOF
{
  "service_uuid": "abbfae98-705a-4b75-af2e-9435a21b39b1"
}

Валюта currency услуги берется из настроек вашего аккаунта.

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

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

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

Поле	Тип	JSON-тип	Обязательно	Может быть `null`	Описание
`name`	Строка	Строка	Да	Нет	Название услуги. Ограничено 250 символами
`category`	Категория	Объект	Нет	Да	Категория услуги
`external_id`	Строка	Строка	Нет	Да	Внешний идентификатор
`description`	Строка	Строка	Нет	Да	Описание услуги. Ограничено 500 символами
`price_default`	Число	Число	Нет	Да	Стоимость услуги

name

Строка

Да

Нет

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

category

Категория

Объект

Нет

Да

Категория услуги

external_id

Строка

Нет

Да

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

description

Строка

Нет

Да

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

price_default

Число

Нет

Да

Стоимость услуги

Получение услуги

Услуги могут быть получены по uuid или external_id.

С помощью uuid

$ curl -H "Authorization: Bearer api-key" \
  https://api.planado.ru/v2/catalog/services/68fb7a80-43e6-4658-83f4-be8ac7cc70d2 | jq
{
  "service": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Доставка",
    "description": "С подъемом на этаж",
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "currency": "rub",
    "external_id": "delivery",
    "price_default": "1599.99",
    "archived": false
  }
}

С помощью external_id

$ curl -H "Authorization: Bearer api-key" https://api.planado.ru/v2/catalog/services/delivery | jq
{
  "service": {
    "uuid": "68fb7a80-43e6-4658-83f4-be8ac7cc70d2",
    "name": "Доставка",
    "description": "С подъемом на этаж",
    "category_uuid": "cd47b580-aa63-4de1-8d97-4d170b8a8f6f",
    "currency": "rub",
    "external_id": "delivery",
    "price_default": "1599.99",
    "archived": false
  }
}

Обновление услуги

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

Обновление описания существующей услуги

$ curl --data "{\"description\":null}" \
       -X PATCH \
       -H "Authorization: Bearer api-key" \
       https://api.planado.ru/v2/catalog/services/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "service_uuid": "0a7b6f74-9bd3-434f-8588-c677bac93d4c"
}

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

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

Поле	Тип	JSON-тип	Обязательно	Может быть `null`	Описание
`name`	Строка	Строка	Нет	Нет	Название услуги. Ограничено 250 символами
`category`	Категория	Объект	Нет	Да	Категория услуги
`description`	Строка	Строка	Нет	Да	Описание услуги. Ограничено 500 символами
`price_default`	Число	Число	Нет	Да	Стоимость услуги

name

Строка

Нет

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

category

Категория

Объект

Нет

Да

Категория услуги

description

Строка

Нет

Да

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

price_default

Число

Нет

Да

Стоимость услуги

Удаление услуги

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

Удаление с помощью uuid

$ curl -H "Authorization: Bearer api-key" -X DELETE https://api.planado.ru/v2/catalog/services/0a7b6f74-9bd3-434f-8588-c677bac93d4c | jq
{
  "message": "Performed"
}

Архивация услуги

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

Архивация по uuid

$ curl -H "Authorization: Bearer api-key" -X POST "https://api.planado.ru/v2/catalog/services/b8994bf9-e46a-4f4f-9747-6a9f19b5157e/archive" | jq
{
  "service_uuid": "b8994bf9-e46a-4f4f-9747-6a9f19b5157e"
}