Задачи

В данном разделе описывается работа с задачами через 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 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

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

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