Задачи

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

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 необходимо передать массив типов задачи. (типы задач см. здесь))

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

  1. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[date_create][from]=1514754000&filter[date_create][to]=1514836800' ;
  2. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[date_modify][from]=1514754000&filter[date_modify][to]=1514836800' ;
  3. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[pipe][14711][]=17089695&filter[pipe][14711][]=17089694&filter[pipe][14718][]=17089756' ;
  4. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[status][]=0' ;
  5. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/tasks?filter[created_by][]=962470&filter[created_by][]=958030' ;
  6. $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

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

  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. }