В данном разделе описывается работа с тегами через API

Оглавление

• Общая информация
• Список тегов для сущности
• Добавление тегов для конкретного типа сущности
• Добавление тегов к сущности
• Удаление тегов у сущности
• Доступные цвета для тегов сделок

Общая информация

• Справочник тегов разделен по сущностям, то есть тег с одним названием будет иметь различные ID в разных типах сущностей
• Цвет тегов доступен только для тегов сделок
• Цвет тегов доступен только только с обновления Весна 2022
• Функционал тегов доступен для следующих сущностей: сделки, контакты, компании и покупатели

Список тегов для сущности

Метод

GET /api/v4/{entity_type:leads|contacts|companies|customers}/tags

Описание

Метод позволяет получить список тегов для сущности в аккаунте.

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

Пример запроса

В следующем примере мы получим теги сделок c фильтром по ID.

https://example.amocrm.ru/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

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

Метод возвращает коллекцию моделей тегов, рассмотрим ниже свойства тега.

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709&page=1&limit=50"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709&page=2&limit=50"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 2707,
                "name": "Заявка с сайта",
                "color": "EBEBEB"
            },
            {
                "id": 2709,
                "name": "Техническая поддержка",
                "color": null
            }
        ]
    }
}

Добавление тегов для конкретного типа сущности

Метод

POST /api/v4/{entity_type:leads|contacts|companies|customers}/tags

Описание

Метод позволяет добавлять теги для указанной в URL сущности пакетно.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Для создания теги необходимо передать 1 параметр – name. Также для тегов сделок вы можете передать цвет.
Если тег с переданным названием уже существует, то в ответе вернется его ID

Пример запроса

[
  {
    "name": "Tag 1",
    "color": "DDEBB5"
  },
  {
    "name": "Tag 2",
    "request_id": "my_request_id"
  },
  {
    "name": "Tag 3"
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

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

Метод возвращает коллекцию тегов, которые были созданы.

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

{
  "_total_items": 3,
  "_embedded": {
    "tags": [
      {
        "id": 263807,
        "name": "Tag 1",
        "color": "DDEBB5",
        "request_id": "0"
      },
      {
        "id": 263809,
        "name": "Tag 2",
        "color": null,
        "request_id": "my_request_id"
      },
      {
        "id": 263811,
        "name": "Tag 3",
        "color": null,
        "request_id": "2"
      }
    ]
  }
}

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

Метод

PATCH /api/v4/{entity_type:leads|contacts|companies|customers}

Описание

Метод позволяет редактировать сущности пакетно.
Также вы можете добавить ID сущности в метод для редактирования конкретной сущности (например /api/v4/leads/{id}).
При редактировании пакетно передается массив из объектов, при редактировании одной сущности, передается просто модель.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Важно отметить, что необходимо передать все теги сущности. Если у сущности уже есть теги и они не переданы – то они будут откреплены

Пример запроса

В данном примере мы обновим 2 сделки через метод /api/v4/leads.

[
    {
        "id": 167353,
        "_embedded": {
            "tags": [
                {
                    "id": 263807
                }
            ]
        }
    },
    {
        "id": 167355,
        "_embedded": {
            "tags": [
                {
                    "name": "Тег 2"
                }
            ]
        }
    }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

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

Метод возвращает коллекцию сущностей, которые были изменены.

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

{
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/leads"
    }
  },
  "_embedded": {
    "leads": [
      {
        "id": 167353,
        "updated_at": 1588928155,
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/167353"
          }
        }
      },
      {
        "id": 167355,
        "updated_at": 1588928155,
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/167355"
          }
        }
      }
    ]
  }
}

Удаление тегов у сущности

Метод

PATCH /api/v4/{entity_type:leads|contacts|companies|customers}

Описание

Метод позволяет редактировать сущности пакетно.
Также вы можете добавить ID сущности в метод для редактирования конкретной сущности (например /api/v4/leads/{id}).
При редактировании пакетно передается массив из объектов, при редактировании одной сущности, передается просто модель.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Для открепления тегов необходимо передать свойство _embedded[tags] со значением null.

Пример запроса

В данном примере мы обновим сделку через метод /api/v4/leads/{id}.

{
    "_embedded": {
        "tags": null
    }
}

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

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

Метод возвращает коллекцию сущностей, которые были изменены.

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

{
    "id": 167353,
    "updated_at": 1588928155,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/167353"
        }
    }
}

Доступные цвета для тегов сделок

Начиная с версии amoCRM весна 2022, вы можете задавать цвета для тегов сделок. Доступные цвета перечислены ниже: