Если у вас еще нет amoCRM
Создать прямо сейчасВ данном разделе описывается работа с тегами через API
GET /api/v4/{entity_type:leads|contacts|companies|customers}/tags
Метод позволяет получить список тегов для сущности в аккаунте.
Метод доступен в соответствии с правами пользователя.
| Параметр | Тип данных | Описание |
|---|---|---|
| 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
| Код ответа | Условие |
|---|---|
| 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
| Код ответа | Условие |
|---|---|
| 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
| Код ответа | Условие |
|---|---|
| 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
| Код ответа | Условие |
|---|---|
| 200 | Сделки были успешно изменены |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод возвращает коллекцию сущностей, которые были изменены.
{
"id": 167353,
"updated_at": 1588928155,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/leads/167353"
}
}
}