Задачи

Задача должна обязательно иметь ответственного и дату (число и время). Также задача может быть связана со сделкой или контактом, но не обязательно, она может быть не связана ни с каким объектом. Основной сущностью системы являются задачи. Установить результат для закрытой задачи можно, используя метод 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_at 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

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

  1. {
  2.    add: [
  3.       {
  4.          element_id: "496537",
  5.          element_type: "1",
  6.          complete_till_at: "1508706000",
  7.          task_type: "1",
  8.          text: "Не забыть перезвонить",
  9.          created_at: "1508706000",
  10.          updated_at: "1508706000",
  11.          responsible_user_id: "504141",
  12.          created_by: "504141"
  13.       }
  14.    ]
  15. }

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/tasks",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 930790,
  12.             _links: {
  13.                self: {
  14.                   href: "/api/v2/tasks?id=930790",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

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

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

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

  1. $tasks['add']=array(
  2.   #Привязываем к сделке
  3.  array(
  4.     'element_id'=>3698754, #ID сделки
  5.    'element_type'=>2, #Показываем, что это - сделка, а не контакт
  6.    'task_type'=>1, #Звонок
  7.    'text'=>'My First Task',
  8.     'responsible_user_id'=>109999,
  9.     'complete_till_at'=>1375285346
  10.   ),
  11.   #Привязываем к сделке
  12.  array(
  13.     'element_id'=>3698752,
  14.     'element_type'=>2,
  15.     'task_type'=>3, #Письмо
  16.    'text'=>'My Second Task',
  17.     'responsible_user_id'=>109999,
  18.     'complete_till_at'=>1375198975
  19.   ),
  20.   #Привязываем к контакту
  21.  array(
  22.     'element_id'=>10773004,
  23.     'element_type'=>1,
  24.     'task_type'=>2, #Встреча
  25.    'text'=>'My Third Task',
  26.     'responsible_user_id'=>109999,
  27.     'complete_till_at'=>1375285442
  28.   )
  29. );
  30. /* Теперь подготовим данные, необходимые для запроса к серверу */
  31. $subdomain='test'; #Наш аккаунт - поддомен
  32. #Формируем ссылку для запроса
  33. $link='https://'.$subdomain.'.amocrm.ru/api/v2/tasks';
  34. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  35. работе с этой
  36. библиотекой Вы можете прочитать в мануале. */
  37. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  38. #Устанавливаем необходимые опции для сеанса cURL
  39. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  40. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  41. curl_setopt($curl,CURLOPT_URL,$link);
  42. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  43. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($tasks));
  44. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  45. curl_setopt($curl,CURLOPT_HEADER,false);
  46. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  47. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  48. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  49. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  50. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  51. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  52. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  53. $code=(int)$code;
  54. $errors=array(
  55.   301=>'Moved permanently',
  56.   400=>'Bad request',
  57.   401=>'Unauthorized',
  58.   403=>'Forbidden',
  59.   404=>'Not found',
  60.   500=>'Internal server error',
  61.   502=>'Bad gateway',
  62.   503=>'Service unavailable'
  63. );
  64. try
  65. {
  66.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  67.  if($code!=200 && $code!=204)
  68.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  69. }
  70. catch(Exception $E)
  71. {
  72.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  73. }

Список задач

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

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)

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

Параметр Тип Описание
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

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/tasks",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 930789,
  12.             responsible_user_id: 504141,
  13.             created_by: 504141,
  14.             created_at: 1508619600,
  15.             updated_at: 1508619600,
  16.             account_id: 13667499,
  17.             group_id: 0,
  18.             element_type: 3,
  19.             element_id: 1099180,
  20.             is_completed: false,
  21.             task_type: 1,
  22.             complete_till_at: 1508878800,
  23.             text: "Не забыть позвонить",
  24.             result: [],
  25.             _links: {
  26.                self: {
  27.                   href: "/api/v2/tasks?id=930789",
  28.                   method: "get"
  29.                }
  30.             }
  31.          },
  32.          {
  33.             id: 930776,
  34.             responsible_user_id: 504141,
  35.             created_by: 504141,
  36.             created_at: 1508659120,
  37.             updated_at: 1508659120,
  38.             account_id: 13667499,
  39.             group_id: 0,
  40.             element_type: 12,
  41.             element_id: 466791,
  42.             is_completed: false,
  43.             task_type: 1,
  44.             complete_till_at: 1508705940,
  45.             text: "Перезвонить",
  46.             result: [],
  47.             _links: {
  48.                self: {
  49.                   href: "/api/v2/tasks?id=930776",
  50.                   method: "get"
  51.                }
  52.             }
  53.          }
  54.       ]
  55.    }
  56. }