Контакты

Одна из основных сущностей системы. Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждый контакт может участвовать в одной и более сделке или может быть вообще не связан ни с одной. Каждый контакт может быть прикреплен к одной компании.

E-mail контакта и телефон используются как уникальные идентификаторы в связке с другими системами. К примеру, именно в события контакта попадает информация о совершенных звонках, о e-mail-переписке.

Каждому контакту может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.

Добавление и обновление контактов

Метод позволяет добавлять контакты по одному или пакетно, а также обновлять данные по уже существующим контактам.

URL метода
POST /api/v2/contacts

Параметры

Параметр Тип Описание
add array Список добавляемых контактов
update array Список существующих контактов, в который будут заноситься изменения. Все параметры, описанные для add, актуальны также для update
add/name
require
string Название контакта
add/created_at timestamp Дата и время создания контакта
add/updated_at timestamp Дата и время обновления контакта. Обязательно при обновлении сущности.
add/responsible_user_id int id пользователя ответственного за контакт
add/created_by int id пользователя создавшего контакт
add/company_name string Название новой компании. Параметр указывается для создания новой компании и привязке к ней контакта. Для привязки контакта к уже существующей компании, необходимо использовать параметр company_id
add/tags string Теги, привязываемые к контакту. Задаются целостной строковой переменной, внутри строки перечисляются через запятую
add/leads_id string Сделки, привязываемые к контакту. Перечисляются через запятую.
add/customers_id string Покупатели, привязываемые к контакту. Перечисляются через запятую.
add/company_id string Компании, привязываемые к контакту. Перечисляются через запятую.
add/custom_fields array Массив дополнительных полей сущности "Контакт"
add/custom_fields//id int id дополнительного поля сущности "Контакт"
add/custom_fields//values array Массив значений дополнительного поля
add/custom_fields//values//value string Значение дополнительного поля
add/custom_fields//values//enum string Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
add/custom_fields//values//subtype string Тип изменяемого элемента дополнительного поля типа "адрес". Внимание, все не указанные типы будут стёрты
update/id
require
int id контакта, в которого будут вноситься изменения
update/updated_at
require
timestamp Дата и время изменения
update/unlink array Массив, содержащий информацию для открепления контакта от других элементов сущностей.
update/unlink/leads_id array Массив id открепляемых сделок
update/unlink/company_id int id открепляемой компании
update/unlink/customers_id array Массив id открепляемых покупателей

Приведём пример запроса на добавление нового контакта.

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

  1. {
  2.       add: [
  3.          {
  4.             name: "Александр Крылов",
  5.             responsible_user_id: "504141",
  6.             created_by: "504141",
  7.             created_at: "1509051600",
  8.             tags: "важный,доставка",
  9.             leads_id: [
  10.                "45615",
  11.                "43510"
  12.             ],
  13.             company_id: "30615",
  14.             custom_fields: [
  15.                {
  16.                   id: "4396817",
  17.                   values: [
  18.                      {
  19.                         value: "Менеджер по продажам"
  20.                      }
  21.                   ]
  22.                },
  23.                {
  24.                   id: "4396818",
  25.                   values: [
  26.                      {
  27.                         value: "89990123456",
  28.                         enum: "WORK"
  29.                      },
  30.                      {
  31.                         value: "89997894561",
  32.                         enum: "WORKDD"
  33.                      },
  34.                      {
  35.                         value: "89991597532",
  36.                         enum: "MOB"
  37.                      }
  38.                   ]
  39.                },
  40.                {
  41.                   id: "4396819",
  42.                   values: [
  43.                      {
  44.                         value: "example@example.moc",
  45.                         enum: "WORK"
  46.                      }
  47.                   ]
  48.                },
  49.                {
  50.                   id: "4396821",
  51.                   values: [
  52.                      {
  53.                         value: "example.example",
  54.                         enum: "SKYPE"
  55.                      }
  56.                   ]
  57.                },
  58.                {
  59.                   id: "4400115",
  60.                   values: [
  61.                      {
  62.                         value: "ул. Ленина, д. 1",
  63.                         subtype: "address_line_1"
  64.                      },
  65.                      {
  66.                         value: "Москва",
  67.                         subtype: "city"
  68.                      },
  69.                      {
  70.                         value: "101010",
  71.                         subtype: "zip"
  72.                      },
  73.                      {
  74.                         value: "RU",
  75.                         subtype: "country"
  76.                      }
  77.                   ]
  78.                },
  79.                {
  80.                   id: "4400116",
  81.                      values: [
  82.                         "3692662",
  83.                         "3692663"
  84.                      ]
  85.                }
  86.             ]
  87.          }
  88.       ]
  89.    }

Приведём пример запроса на обновление контакта.

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

  1. {
  2.    update: [
  3.       {
  4.          id: "41560",
  5.          updated_at: "1508965200",
  6.          custom_fields: [
  7.             {
  8.                id: "4396819",
  9.                values: [
  10.                   {
  11.                      value: "example@example.moc",
  12.                      enum: "WORK"
  13.                   }
  14.                ]
  15.             }
  16.          ]
  17.       }
  18.    ]
  19. }

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

Параметр Описание
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.    _link: {
  3.       self: {
  4.          href: "/api/v2/contacts",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099235,
  12.             _link: {
  13.                self: {
  14.                   href: "/api/v2/contacts?id=1099235",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

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

Для добавления контакта необходимо описать массив, содержащий информацию о контакте и поместить его в массив следующего вида: $contacts['add'] Наше API также поддерживает одновременное добавление сразу нескольких контактов. Для этого мы помещаем в массив $contacts['add'] несколько массивов, каждый из которых описывает необходимые данные для создания соответствующего контакта.

  1. $contacts['add']=array(
  2.    array(
  3.       'name' => 'Александр Крылов',
  4.       'responsible_user_id' => 504141,
  5.       'created_by' => 504141,
  6.       'created_at' => "1509051600",
  7.       'tags' => "важный,доставка",
  8.       'leads_id' => array(
  9.          "45615",
  10.          "43510"
  11.       ),
  12.       'company_id' => 30615,
  13.       'custom_fields' => array(
  14.          array(
  15.             'id' => 4396817,
  16.             'values' => array(
  17.                array(
  18.                   'value' => "Менеджер по продажам"
  19.                )
  20.             )
  21.          ),
  22.          array(
  23.             'id' => 4396818,
  24.             'values' => array(
  25.                array(
  26.                   'value' => "89990123456",
  27.                   'enum' => "WORK"
  28.                ),
  29.                array(
  30.                   'value' => "89997894561",
  31.                   'enum' => "WORKDD"
  32.                ),
  33.                array(
  34.                   'value' => "89991597532",
  35.                   'enum' => "MOB"
  36.                )
  37.             )
  38.          ),
  39.          array(
  40.             'id' => 4396819,
  41.             'values' => array(
  42.                array(
  43.                   'value' => "example@example.moc",
  44.                   'enum' => "WORK"
  45.                )
  46.             )
  47.          ),
  48.          array(
  49.             'id' => 4396821,
  50.             'values' => array(
  51.                array(
  52.                   'value' => "example.example",
  53.                   'enum' => "SKYPE"
  54.                )
  55.             )
  56.          ),
  57.          array(
  58.             'id' => 4400115,
  59.             'values' => array(
  60.                array(
  61.                   'value' => "ул. Ленина, д. 1",
  62.                   'subtype' => "address_line_1"
  63.                ),
  64.                array(
  65.                   value: "Москва",
  66.                   subtype: "city"
  67.                ),
  68.                array(
  69.                   value: "101010",
  70.                   subtype: "zip"
  71.                ),
  72.                array(
  73.                   value: "RU",
  74.                   subtype: "country"
  75.                )
  76.             )
  77.          ),
  78.          array(
  79.             'id' => 4400116,
  80.             'values' => array(
  81.                "3692662",
  82.                "3692663"
  83.             )
  84.          )
  85.       )
  86.    )
  87. )
  88. );
  89. /* Теперь подготовим данные, необходимые для запроса к серверу */
  90. $subdomain='test'; #Наш аккаунт - поддомен
  91. #Формируем ссылку для запроса
  92. $link='https://'.$subdomain.'.amocrm.ru/api/v2/contacts';
  93. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  94. работе с этой
  95. библиотекой Вы можете прочитать в мануале. */
  96. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  97. #Устанавливаем необходимые опции для сеанса cURL
  98. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  99. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  100. curl_setopt($curl,CURLOPT_URL,$link);
  101. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  102. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($contacts));
  103. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  104. curl_setopt($curl,CURLOPT_HEADER,false);
  105. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  106. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  107. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  108. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  109. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  110. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  111. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  112. $code=(int)$code;
  113. $errors=array(
  114.   301=>'Moved permanently',
  115.   400=>'Bad request',
  116.   401=>'Unauthorized',
  117.   403=>'Forbidden',
  118.   404=>'Not found',
  119.   500=>'Internal server error',
  120.   502=>'Bad gateway',
  121.   503=>'Service unavailable'
  122. );
  123. try
  124. {
  125.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  126.  if($code!=200 && $code!=204) {
  127.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  128.   }
  129. }
  130. catch(Exception $E)
  131. {
  132.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  133. }
  134. /*
  135.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  136.  нам придётся перевести ответ в формат, понятный PHP
  137.  */
  138. $Response=json_decode($out,true);
  139. $Response=$Response[_embedded']['items'];
  140. $output='ID добавленных контактов:'.PHP_EOL;
  141. foreach($Response as $v)
  142.  if(is_array($v))
  143.    $output.=$v['id'].PHP_EOL;
  144. return $output;

Список контактов

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

URL метода
GET /api/v2/contacts/

Параметры GET

Параметр Описание
id Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Сдвиг выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан
responsible_user_id Выбрать элемент по ответственному пользователю (можно передавать массив с ID пользователей).
query Поисковый запрос (Осуществляет поиск по заполненным полям сущности).

Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y H:i:s. При передаче этого заголовка будут возвращены сделки, изменённые позже этой даты. Заголовок должен быть передан в часовом поясе UTC.

  1. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 07:07:23 UTC'));

Описание параметров ответа

Параметр Тип Описание
id int Уникальный идентификатор контакта
name string Название контакта
responsible_user_id int id ответственного пользователя
created_by int id пользователя создавшего контакт
created_at timestamp Время и дата создания контакта
updated_at timestamp Время и дата изменения контакта
account_id int id аккаунта на котором создан контакт
updated_by int id пользователя обновившего контакт
group_id int id группы в которой состоит пользователь ответственный за данный контакт
company array Массив, содержащий информацию о компании, которая прикреплена к данному контакту
company/id int id компании, которая прикреплена к данному контакту
company/name string Название компании, которая прикреплена к данному контакту
leads array Массив, содержащий информацию о сделках, которые прикреплены к данному контакту
leads/id int id сделки, которая прикреплена к данному контакту
closest_task_at int Время ближайшей задачи по данному контакту
tags array Массив, содержащий информацию по тегам, прикреплённым к данному контакту
tags/id int id тега, прикреплённого к данному контакту
tags/name string Название тега, прикреплённого к данному контакту
custom_fields array Массив, содержащий информацию по дополнительным полям, заданным для данного контакта
custom_fields//id int id дополнительного поля
custom_fields//name string Название дополнительного поля
custom_fields//values array Массив, содержащий информацию по дополнительным полям, заданным для данного контакта
custom_fields//values//value string Значение дополнительного поля
custom_fields//values//enum string Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
custom_fields//values//subtype string Идентификатор значений дополнительного поля "адрес"
custom_fields//is_system bool Является ли дополнительное поле системным
customers array Массив, содержащий информацию о покупателях, которые прикреплены к данному контакту
customers/id int id покупателя, прикреплённого к данному контакту
_links array Массив, содержащий информацию о запросе
_links/self array Массив, содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив, содержащий информацию прилегающую к запросу
_embedded/items array Массив, содержащий информацию по каждому отдельному элементу

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

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

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/contacts?id=1099181",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099181,
  12.             name: "Екатерина Долгорукова",
  13.             responsible_user_id: 504141,
  14.             created_by: 504141,
  15.             created_at: 1508499477,
  16.             updated_at: 1509019136,
  17.             account_id: 13667499,
  18.             updated_by: 504141,
  19.             group_id: 0,
  20.             company: {
  21.                id: 1099180,
  22.                name: "ООО Компания",
  23.                _links: {
  24.                   self: {
  25.                      href: "/api/v2/companies?id=1099180",
  26.                      method: "get"
  27.                   }
  28.                }
  29.             },
  30.             leads: {
  31.                id: [
  32.                   1090391
  33.                ],
  34.                _links: {
  35.                   self: {
  36.                      href: "/api/v2/leads?id=1090391",
  37.                      method: "get"
  38.                   }
  39.                }
  40.             },
  41.             closest_task_at: 1509051540,
  42.             tags: [
  43.                {
  44.                   id: 61881,
  45.                   name: "доставка"
  46.                },
  47.                {
  48.                   id: 61882,
  49.                   name: "важный"
  50.                }
  51.             ],
  52.             custom_fields: [
  53.                {
  54.                   id: 4396818,
  55.                   name: "Телефон",
  56.                   values: [
  57.                      {
  58.                         value: "89996123232",
  59.                         enum: "3685087"
  60.                      }
  61.                   ],
  62.                   is_system: true
  63.                },
  64.                {
  65.                   id: 4396821,
  66.                   name: "Мгн. сообщения",
  67.                   values: [
  68.                      {
  69.                         value: "example.example",
  70.                         enum: "3685096"
  71.                      }
  72.                   ],
  73.                   is_system: true
  74.                },
  75.                {
  76.                   id: 4400115,
  77.                   name: "Адрес",
  78.                   values: [
  79.                      {
  80.                         value: "ул. Ленина, д. 1, г. Москва",
  81.                         subtype: "1"
  82.                      },
  83.                      {
  84.                         value: "RU",
  85.                         subtype: "6"
  86.                      }
  87.                   ],
  88.                   is_system: false
  89.                },
  90.                {
  91.                   id: 4400116,
  92.                   name: "Мультисписок",
  93.                      values: [
  94.                         {
  95.                            value: "2",
  96.                            enum: "3692663"
  97.                         },
  98.                         {
  99.                            value: "3",
  100.                            enum: "3692664"
  101.                         }
  102.                      ],
  103.                      is_system: false
  104.                }
  105.             ],
  106.             customers: {
  107.                id: [
  108.                   466791
  109.                ],
  110.                _links: {
  111.                   self: {
  112.                      href: "/api/v2/customers?id=466791",
  113.                      method: "get"
  114.                   }
  115.                }
  116.             },
  117.             _links: {
  118.                self: {
  119.                   href: "/api/v2/contacts?id=1099181",
  120.                   method: "get"
  121.                }
  122.             }
  123.          }
  124.       ]
  125.    }
  126. }

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

  1. /* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
  2. $subdomain='test'; #Наш аккаунт - поддомен
  3. #Формируем ссылку для запроса
  4. $link='https://'.$subdomain.'.amocrm.ru/api/v2/contacts/';
  5. /* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
  6. документацию).
  7. Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
  8. необходимо. */
  9. $link='https://'.$subdomain.'.amocrm.ru/api/v2/contacts/';
  10. $link='https://'.$subdomain.'.amocrm.ru/api/v2/contacts/?limit_rows=15';
  11. $link='https://'.$subdomain.'.amocrm.ru/api/v2/contacts/?limit_rows=15&limit_offset=2';
  12. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  13. работе с этой
  14. библиотекой Вы можете прочитать в мануале. */
  15. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  16. #Устанавливаем необходимые опции для сеанса cURL
  17. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  18. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  19. curl_setopt($curl,CURLOPT_URL,$link);
  20. curl_setopt($curl,CURLOPT_HEADER,false);
  21. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  22. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  25. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  26. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  27. curl_close($curl);
  28. /* Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y
  29. H:i:s. При
  30. передаче этого заголовка будут возвращены контакты, изменённые позже этой даты. */
  31. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
  32. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  33. $code=(int)$code;
  34. $errors=array(
  35.   301=>'Moved permanently',
  36.   400=>'Bad request',
  37.   401=>'Unauthorized',
  38.   403=>'Forbidden',
  39.   404=>'Not found',
  40.   500=>'Internal server error',
  41.   502=>'Bad gateway',
  42.   503=>'Service unavailable'
  43. );
  44. try
  45. {
  46.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  47.  if($code!=200 && $code!=204) {
  48.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  49.   }
  50. }
  51. catch(Exception $E)
  52. {
  53.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  54. }
  55. /*
  56.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  57.  нам придётся перевести ответ в формат, понятный PHP
  58.  */
  59. $Response=json_decode($out,true);
  60. $Response=$Response['_embedded']['items'];

Смотрите также

Коды ошибок API