Теги

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

Оглавление

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

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

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

Метод

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

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter object Фильтр
filter[name] string Фильтр по точному названию тега. Можно передать только одно название
filter[id] int
array		 Фильтр по ID тега. Можно передать как один ID, так и массив из нескольких ID
query string Позволяет осуществить полнотекстовый поиск поиск по названию тега

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

В следующем примере мы получим теги сделок 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 коды ответа

Код ответа Условие
200 Запрос выполнен успешно
204 Данных не найдено
401 Пользователь не авторизован

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

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

Параметр Тип данных Описание
id int ID тега
name string Название тега

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

{
    "_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": "Заявка с сайта"
            },
            {
                "id": 2709,
                "name": "Техническая поддержка"
            }
        ]
    }
}

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

Метод

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

Описание

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

Ограничения

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

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

Content-Type: application/json

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

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

Параметр Тип данных Описание
name string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Параметр не является обязательным

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

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Теги были успешно созданы
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

Параметр Тип данных Описание
id int ID тега
name string Название тега
request_id string Строка переданная при запросе или порядковый указатель, если параметр не передан

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

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

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

Метод

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

Описание

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

Ограничения

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

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

Content-Type: application/json

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

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

Параметр Тип данных Описание
_embedded[tags] array
null		 Данные тегов, добавляемых к сделке
_embedded[tags][0] object Модель тега, добавляемого к сделке. Необходимо указать id или name
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега

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

В данном примере мы обновим 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 коды ответа

Код ответа Условие
200 Сделки были успешно изменены
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

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

{
    "_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.

Параметр Тип данных Описание
_embedded[tags] array
null		 Данные тегов, добавляемых к сделке

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

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

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Сделки были успешно изменены
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

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

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