Задачи

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

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

Задача является самостоятельной сущностью, но может быть прикреплена к сделке, контакту, компании, покупателю
Задача обязательно должна иметь ответственного и дату выполнения (число и время)
У задач доступны 2 стандартных типа с предопределенными ID: : 1 – Звонок, 2 – Встреча

Список задач

Метод

GET /api/v4/tasks

Описание

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

Ограничения

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

GET параметры

Параметр	Тип данных	Описание
page	int	Страница выборки
limit	int	Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter	object	Фильтр
filter[responsible_user_id]	int\|array	Фильтр по ID ответственного за задачу пользователя. Можно передать как один ID, так и массив из нескольких ID
filter[is_completed]	bool	Фильтр по статусу задачи. 1 – завершенные, 0 – к выполнению
filter[task_type]	int\|array	Фильтр по ID типа задачи. Можно передать как один ID, так и массив из нескольких ID
filter[entity_type]	string	Фильтр по типу привязанной к задаче сущности. Возможные значения: leads, contacts, companies, customers
filter[entity_id]	int\|array	Фильтр по ID, привязанной к задаче, сущности. Для его использования необходимо передать значение в filter[entity_type]. Можно передать как один ID, так и массив из нескольких ID
filter[id]	int\|array	Фильтр по ID задачи. Можно передать как один ID, так и массив из нескольких ID
filter[updated_at]	int\|object	Фильтр по дате последнего изменения задачи. Можно передать timestamp, в таком случае будут возвращены задачи, которые были изменены после переданного значения. Также можно передать массив вида filter[updated_at][from]=… и filter[updated_at][to]=…, для фильтрации по значениям ОТ и ДО.
order	object	Сортировка результатов списка. Доступные поля для сортировки: created_at, complete_till, id. Доступные значения для сортировки: asc, desc. Пример: /api/v4/tasks?order[complete_till]=asc

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

В следующем примере мы получим все завершенные задачи с типом 2 (Встреча) с ограничением выборки в 2 строки.

        
https://example.amocrm.ru/api/v4/tasks?filter[task_type][]=2&filter[is_completed][]=1&limit=2

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	int	ID задачи
created_by	int	ID пользователя, создавшего задачу
updated_by	int	ID пользователя, изменившего задачу
created_at	int	Дата создания задачи, передается в Unix Timestamp
updated_at	int	Дата изменения задачи, передается в Unix Timestamp
responsible_user_id	int	ID пользователя, ответственного за задачу
group_id	int	ID группы, в которой состоит ответственны пользователь за задачу
entity_id	int	ID сущности, к которой привязана задача
entity_type	string	Тип сущности, к которой привязана задача
is_completed	bool	Выполнена ли задача
task_type_id	int	Тип задачи
text	string	Описание задачи
duration	int	Длительность задачи в секундах
complete_till	int	Дата, когда задача должна быть завершена, передается в Unix Timestamp
result	object	Результат выполнения задачи
result[text]	string	Текст результата выполнения задачи
account_id	int	ID аккаунта, в котором находится задача

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

        
{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/tasks?filter[task_type][]=2&filter[is_completed][]=1&limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/tasks?filter[task_type][]=2&filter[is_completed][]=1&limit=2&page=2"
        }
    },
    "_embedded": {
        "tasks": [
            {
                "id": 7087,
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1575364000,
                "updated_at": 1575364851,
                "responsible_user_id": 123123,
                "group_id": 0,
                "entity_id": 167353,
                "entity_type": "leads",
                "duration": 0,
                "is_completed": true,
                "task_type_id": 2,
                "text": "Пригласить на бесплатную тренировку",
                "result": [],
                "complete_till": 1575665940,
                "account_id": 321321,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/tasks/7087"
                    }
                }
            },
            {
                "id": 215089,
                "created_by": 0,
                "updated_by": 3987910,
                "created_at": 1576767879,
                "updated_at": 1576767914,
                "responsible_user_id": 123123,
                "group_id": 0,
                "entity_id": 1035487,
                "entity_type": "leads",
                "duration": 0,
                "is_completed": true,
                "task_type_id": 2,
                "text": "Назначить встречу с клиентом",
                "result": [],
                "complete_till": 1576768179,
                "account_id": 321312,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/tasks/215089"
                    }
                }
            }
        ]
    }
}

Получение задачи по ID

Метод

GET /api/v4/tasks/{id}

Описание

Метод позволяет получить данные конкретной задачи по ID.

Ограничения

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает модель задачи, рассмотрим ниже свойства задачи.

Параметр	Тип данных	Описание
id	int	ID задачи
created_by	int	ID пользователя, создавшего задачу
updated_by	int	ID пользователя, изменившего задачу
created_at	int	Дата создания задачи, передается в Unix Timestamp
updated_at	int	Дата изменения задачи, передается в Unix Timestamp
responsible_user_id	int	ID пользователя, ответственного за задачу
group_id	int	ID группы, в которой состоит ответственны пользователь за задачу
entity_id	int	ID сущности, к которой привязана задача
entity_type	string	Тип сущности, к которой привязана задача
is_completed	bool	Выполнена ли задача
task_type_id	int	Тип задачи
text	string	Описание задачи
duration	int	Длительность задачи в секундах
complete_till	int	Дата, когда задача должна быть завершена, передается в Unix Timestamp
result	object	Результат выполнения задачи
result[text]	string	Текст результата выполнения задачи
account_id	int	ID аккаунта, в котором находится задача

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

        
{
    "id": 56981,
    "created_by": 54224,
    "updated_by": 3987910,
    "created_at": 1575910123,
    "updated_at": 1576767989,
    "responsible_user_id": 123123,
    "group_id": 0,
    "entity_id": 180765,
    "entity_type": "leads",
    "duration": 0,
    "is_completed": true,
    "task_type_id": 2,
    "text": "Назначить встречу с клиентом",
    "result": {
        "text": "Результат есть"
    },
    "complete_till": 1575910423,
    "account_id": 321312,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/tasks/56981"
        }
    }
}

Добавление задач

Метод

POST /api/v4/tasks

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Для создания задачи нужно передать 2 обязательных параметра: text и complete_till. Ниже описаны все параметры, которые могут быть переданы при создании задачи.

Параметр	Тип данных	Описание
responsible_user_id	int	ID пользователя, ответственного за задачу. Не обязательный параметр, по-умолчанию ID текущего пользователя
entity_id	int	ID сущности, к которой привязана задача. Не обязательный параметр
entity_type	string	Тип сущности, к которой привязана задача. Не обязательный параметр
is_completed	bool	Выполнена ли задача. Не обязательный параметр
task_type_id	int	Тип задачи. Не обязательный параметр
text	string	Описание задачи. Обязательный параметр
duration	int	Длительность задачи в секундах. Не обязательный параметр
complete_till	int	Дата, когда задача должна быть завершена, передается в Unix Timestamp. Обязательный параметр.
result	object	Результат выполнения задачи
result[text]	string	Текст результата выполнения задачи
created_by	int	ID пользователя, создающий задачу. Не обязательный параметр
updated_by	int	ID пользователя, изменяющий задачу. Не обязательный параметр
created_at	int	Дата создания задачи, передается в Unix Timestamp. Не обязательный параметр
updated_at	int	Дата изменения задачи, передается в Unix Timestamp. Не обязательный параметр
request_id	string	Поле, которое вернется вам в ответе без изменений и не будет сохранено. Параметр не является обязательным

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

        
[
    {
        "task_type_id": 1,
        "text": "Встретиться с клиентом Иван Иванов",
        "complete_till": 1588885140,
        "entity_id": 9785993,
        "entity_type": "leads",
        "request_id": "example"
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

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

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

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/tasks"
        }
    },
    "_embedded": {
        "tasks": [
            {
                "id": 4745251,
                "request_id": "example",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/tasks/4745251"
                    }
                }
            }
        ]
    }
}

Редактирование задач

Метод

PATCH /api/v4/tasks

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Параметр	Тип данных	Описание
responsible_user_id	int	ID пользователя, ответственного за задачу. Не обязательный параметр, по-умолчанию ID текущего пользователя
entity_id	int	ID сущности, к которой привязана задача. Не обязательный параметр
entity_type	string	Тип сущности, к которой привязана задача. Не обязательный параметр
is_completed	bool	Выполнена ли задача. Не обязательный параметр
task_type_id	int	Тип задачи. Не обязательный параметр
text	string	Описание задачи. Обязательный параметр
duration	int	Длительность задачи в секундах. Не обязательный параметр
complete_till	int	Дата, когда задача должна быть завершена, передается в Unix Timestamp. Обязательный параметр.
result	object	Результат выполнения задачи
result[text]	string	Текст результата выполнения задачи
created_by	int	ID пользователя, создающий задачу. Не обязательный параметр
updated_by	int	ID пользователя, изменяющий задачу. Не обязательный параметр
created_at	int	Дата создания задачи, передается в Unix Timestamp. Не обязательный параметр
updated_at	int	Дата изменения задачи, передается в Unix Timestamp. Не обязательный параметр
request_id	string	Поле, которое вернется вам в ответе без изменений и не будет сохранено. Параметр не является обязательным

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

        
[
    {
        "id": 4745251,
        "task_type_id": 2,
        "text": "Новое название для задачи",
        "complete_till": 1588885140
    },
    {
        "id": 4747929,
        "task_type_id": 1,
        "text": "Новое название для задачи 2",
        "complete_till": 1588885140
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию или модель задачи, которые были изменены. Возвращаются только свойства id и updated_at.

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

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/tasks"
        }
    },
    "_embedded": {
        "tasks": [
            {
                "id": 4745251,
                "updated_at": 1588760725,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/tasks/4745251"
                    }
                }
            },
            {
                "id": 4747929,
                "updated_at": 1588760725,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/tasks/4747929"
                    }
                }
            }
        ]
    }
}

Выполнение задачи

Метод

PATCH /api/v4/tasks

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Для завершения задачи необходимо передать свойство result и is_completed

Параметр	Тип данных	Описание
is_completed	bool	Выполнена ли задача. Не обязательный параметр
result	object	Результат выполнения задачи
result[text]	string	Текст результата выполнения задачи

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

В примере ниже выполним одну задачу запросом на метод /api/v4/tasks/4747929

        
{
    "is_completed": true,
    "result": {
        "text": "Удалось связаться с клиентом"
    }
}

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию или модель задачи, которые были изменены. Возвращаются только свойства id и updated_at.

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

        
{
    "id": 4747929,
    "updated_at": 1588770600,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/tasks/4747929"
        }
    }
}

Оглавление

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

Список задач

Метод

Описание

Ограничения

GET параметры

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

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

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

HTTP коды ответа

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

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

Получение задачи по ID

Метод

Описание

Ограничения

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

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

HTTP коды ответа

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

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

Добавление задач

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Редактирование задач

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Выполнение задачи

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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