Контакты

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

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 array Массив сделок, привязываемых к контакту.
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