Задачи

Задача должна обязательно иметь ответственного и дату (число и время). Также задача может быть связана со сделкой или контактом, но не обязательно, она может быть не связана ни с каким объектом. Основной сущностью системы являются задачи. Установить результат для закрытой задачи можно, используя метод notes.

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

Данный метод позволяет добавить новую или изменить существующую задачу. Для установки результата по задаче, воспользуйтесь методом notes, установив соответствующий тип примечания.

URL метода

POST /api/v2/tasks

Параметры

Параметр Тип Описание
add array Список добавляемых задач
update array Изменение существующих задач. Все параметры, которые описаны в add действуют также и в update
add/element_id int Уникальный идентификатор контакта или сделки (сделка или контакт указывается в element_type)
add/element_type int Тип привязываемого элемента (1 – контакт, 2- сделка, 3 – компания, 12 – покупатель)
add/complete_till timestamp Дата, до которой необходимо завершить задачу. Если указано время 23:59, то в интерфейсах системы вместо времени будет отображаться “Весь день”.
add/task_type int Тип задачи (типы задач см. здесь)
add/text string Текст задачи
add/created_at timestamp Дата создания данной задачи (необязательный параметр)
add/updated_at timestamp Дата последнего изменения данной задачи (необязательный параметр)
add/responsible_user_id int Уникальный идентификатор ответственного пользователя
add/is_completed bool Задача завершена или нет
add/created_by int Уникальный идентификатор создателя задачи
update/id
require
int Уникальный идентификатор обновляемой задачи
update/updated_at
require
timestamp Дата последнего изменения данной сущности, если параметр не указан, или он меньше чем имеющийся в БД, то обновление не произойдет
update/text
require
string Текст задачи

Типы задач

Код Описание
1 Звонок
2 Встреча
3 Написать письмо

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

Параметр Описание
id Уникальный идентификатор новой сущности
request_id Уникальный идентификатор сущности в клиентской программе, если request_id не передан в запросе, то он генерируется автоматически
_links Массив, содержащий информацию о запросе
_links/self Массив, содержащий информацию о текущем запросе
_links/self/href Относительный URL текущего запроса
_links/self/method Метод текущего запроса
_embedded Массив, содержащий информацию прилегающую к запросу
_embedded/items Массив, содержащий информацию по каждому отдельному элементу

Response Headeres содержит следующие заголовки:

  • Content-Type:application/hal+json
  • Runtime-Timestamp:1508320306

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


{
	add: [{
		element_id: "496537",
		element_type: "1",
		complete_till_at: "1508706000",
		task_type: "1",
		text: "Не забыть перезвонить",
		created_at: "1508706000",
		updated_at: "1508706000",
		responsible_user_id: "504141",
		created_by: "504141"
	}]
}

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


{
	_links: {
		self: {
			href: "/api/v2/tasks",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 930790,
			_links: {
				self: {
					href: "/api/v2/tasks?id=930790",
					method: "get"
				}
			}
		}]
	}
}

Пример интеграции, работающей с задачами

Для добавления задачи необходимо описать массив, содержащий информацию о задаче и поместить его в массив следующего вида:

Пример интеграции


$tasks['add'] = array(
    #Привязываем к сделке
    array(
        'element_id' => 3698754, #ID сделки
        'element_type' => 2, #Показываем, что это - сделка, а не контакт
        'task_type' => 1, #Звонок
        'text' => 'My First Task',
        'responsible_user_id' => 109999,
        'complete_till_at' => 1375285346,
    ),
    #Привязываем к сделке
    array(
        'element_id' => 3698752,
        'element_type' => 2,
        'task_type' => 3, #Письмо
        'text' => 'My Second Task',
        'responsible_user_id' => 109999,
        'complete_till_at' => 1375198975,
    ),
    #Привязываем к контакту
    array(
        'element_id' => 10773004,
        'element_type' => 1,
        'task_type' => 2, #Встреча
        'text' => 'My Third Task',
        'responsible_user_id' => 109999,
        'complete_till_at' => 1375285442,
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($tasks));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_COOKIEFILE, dirname(__FILE__) . '/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl, CURLOPT_COOKIEJAR, dirname(__FILE__) . '/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int) $code;
$errors = array(
    301 => 'Moved permanently',
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable',
);
try
{
    #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
    if ($code != 200 && $code != 204) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error', $code);
    }

} catch (Exception $E) {
    die('Ошибка: ' . $E->getMessage() . PHP_EOL . 'Код ошибки: ' . $E->getCode());
}

Список задач

Метод для получения списка задач с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице (offset) данным – 500 задач. Просроченные задачи – те задачи, где complete_till_at меньше, чем текущее время.

URL метода

GET /api/v2/tasks

GET параметры

Параметр Описание
id Выбрать элемент с заданным id
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Оффсет выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан
element_id Дополнительный фильтр поиска, по id элементам сущности
responsible_user_id Дополнительный фильтр поиска, по ответственному пользователю
type Получение данных по типу указанной сущности (lead/contact/company/customer)
filter/date_create/ Выбрать задачи по дате создания (нужно передавать массив с параметрами from, to)
filter/date_modify/ Выбрать задачи по дате изменения (нужно передавать массив с параметрами from, to)
filter/pipe/ Выбрать задачи по этапам сделок (нужно передавать массив, ключами элементов которого являются id воронок, а значениями – массивы id этапов этих воронок)
filter/status/ Выбрать задачи по статусу (в параметр status необходимо передать массив со значением 1(завершенные) или 0(не завершенные))
filter/created_by/ Выбрать задачи по автору (в параметр created_by необходимо передать массив id пользователей)
filter/task_type/ Выбрать задачи по типу (в параметр task_type необходимо передать массив типов задачи. (типы задач см. здесь))

Примеры запросов для работы с фильтрами


$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[date_create][from]=1514754000&filter[date_create][to]=1514836800';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[date_modify][from]=1514754000&filter[date_modify][to]=1514836800';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[pipe][14711][]=17089695&filter[pipe][14711][]=17089694&filter[pipe][14718][]=17089756';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[status][]=0';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[created_by][]=962470&filter[created_by][]=958030';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[task_type][]=2';

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

Параметр Тип Описание
id int Уникальный идентификатор задачи
element_id int Уникальный идентификатор контакта или сделки (сделка или контакт указывается в element_type)
element_type int Тип привязываемого элемента (1 – контакт, 2- сделка, 3 – компания, 12 – покупатель)
complete_till_at timestamp Дата до которой необходимо завершить задачу. Если указано время 23:59, то в интерфейсах системы вместо времени будет отображаться “Весь день”.
task_type int Тип задачи (типы задач см. здесь)
text string Текст задачи
created_at timestamp Дата создания данной задачи (необязательный параметр)
updated_at timestamp Дата последнего изменения данной задачи (необязательный параметр)
responsible_user_id int Уникальный идентификатор ответственного пользователя
is_completed bool Задача завершена или нет
created_by int Уникальный идентификатор создателя задачи
account_id int Уникальный идентификатор аккаунта
group_id int id группы в которой состоит пользователь имеющей отношение к задаче
result array  
_links array Массив, содержащий информацию о запросе
_links/self array Массив, содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив, содержащий информацию прилегающую к запросу
_embedded/items array Массив, содержащий информацию по каждому отдельному элементу

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

https://example.amocrm.ru/api/v2/tasks

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


{
	_links: {
		self: {
			href: "/api/v2/tasks",
			method: "get"
		}
	},
	_embedded: {
		items: [{
				id: 930789,
				responsible_user_id: 504141,
				created_by: 504141,
				created_at: 1508619600,
				updated_at: 1508619600,
				account_id: 13667499,
				group_id: 0,
				element_type: 3,
				element_id: 1099180,
				is_completed: false,
				task_type: 1,
				complete_till_at: 1508878800,
				text: "Не забыть позвонить",
				result: [],
				_links: {
					self: {
						href: "/api/v2/tasks?id=930789",
						method: "get"
					}
				}
			},
			{
				id: 930776,
				responsible_user_id: 504141,
				created_by: 504141,
				created_at: 1508659120,
				updated_at: 1508659120,
				account_id: 13667499,
				group_id: 0,
				element_type: 12,
				element_id: 466791,
				is_completed: false,
				task_type: 1,
				complete_till_at: 1508705940,
				text: "Перезвонить",
				result: [],
				_links: {
					self: {
						href: "/api/v2/tasks?id=930776",
						method: "get"
					}
				}
			}
		]
	}
}