Теги

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

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

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

Данный метод возвращает данные типа Content-Type: application/hal+json и Content-Type: application/problem+json.

Оглавление

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

Метод позволяет получить список тегов для следующих типов сущностей: сделки, контакты, компании и покупатели.

URL метода

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

Параметры

Параметр Тип Описание
entity_type string Тип сущности. Один из вариантов: leads, contacts, companies, customers

Возможные GET параметры

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

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

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


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

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


{
    "_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": "Техническая поддержка"
            }
        ]
    }
}

Создание тегов

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

URL метода

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

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности. Один из вариантов: leads, contacts, companies, customers

Параметры POST

Параметр Тип Описание
name string Название тега
request_id string Необязательное поле. Параметр вернется вместе с ответом. Может быть использован для маппинга ответа.

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

Для создания тегов необходимо передать JSON массив, содержащий в себе объекты тегов тегов:


POST https://example.amocrm.ru/api/v4/leads/tags
Content-Type: application/json

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

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


{
    "_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"
            }
        ]
    }
}

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

Метод позволяет добавить теги к сделке, контакту, компании или покупателю.
Важно: При прикреплении новых тегов, не передавая существующие, все не переданные теги будут откреплены от сущности.

URL метода

PATCH /api/v4/{entity_type:leads|contacts|companies|customers}/{id} – изменение конкретной сущности

PATCH /api/v4/{entity_type:leads|contacts|companies|customers} – изменение сущностей пакетно

Для прикрепления тегов по ID сущности необходимо передать массив, содержащий обязательное свойство _embedded[tags] с ID или названиями тегов.

Пример прикрепления тегов по ID сделки:


PATCH https://example.amocrm.ru/api/v4/leads/167353
Content-Type: application/json

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

Для прикрепления тегов при пакетном изменении сущностей необходимо передать массив, содержащий обязательное свойство – id (ID сущности) и _embedded[tags] с ID или названиями тегов.

Пример прикрепления тегов к нескольким сделкам:


PATCH https://example.amocrm.ru/api/v4/leads
Content-Type: application/json

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

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


{
    "_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"
                    }
                }
            }
        ]
    }
}

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

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

URL метода

PATCH /api/v4/{entity_type:leads|contacts|companies|customers}/{id} – изменение конкретной сущности

PATCH /api/v4/{entity_type:leads|contacts|companies|customers} – изменение сущностей пакетно

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

Пример открепления тегов по ID сделки:


PATCH https://example.amocrm.ru/api/v4/leads/167353
Content-Type: application/json

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

Для открепления тегов при пакетном изменении сущностей необходимо передать массив, содержащий обязательное свойство – id (ID сущности) и _embedded[tags] со значением null.

Смотрите также

Коды ошибок