Компании

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

E-mail и телефон используются как идентификаторы в связке с другими системами

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

Добавление и обновление компаний

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

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

Параметры

Параметр Тип Описание
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/tags string Теги, привязываемые к компании. Задаются целостной строковой переменной, внутри строки перечисляются через запятую.
add/leads_id string Сделки, привязываемые к компании. Перечисляются id через запятую.
add/customers_id string Покупатели, привязываемые к компании. Перечисляются id через запятую.
add/contacts_id array Массив контактов, привязываемых к компании.
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/contacts_id array Массив id открепляемых контактов
update/unlink/leads_id array Массив 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.          custom_fields: [
  14.             {
  15.                id: "4396817" ,
  16.                values: [
  17.                   {
  18.                      value: "5"
  19.                   }
  20.                ]
  21.             } ,
  22.             {
  23.                id: "4396818" ,
  24.                values: [
  25.                   {
  26.                      value: "89999517535" ,
  27.                      enum : "WORK"
  28.                   } ,
  29.                   {
  30.                      value: "89991237895" ,
  31.                      enum : "MOB"
  32.                   }
  33.                ]
  34.             } ,
  35.             {
  36.                id: "4396819" ,
  37.                values: [
  38.                   {
  39.                      value: "company@company.moc" ,
  40.                      enum : "WORK"
  41.                   }
  42.                ]
  43.             } ,
  44.             {
  45.                id: "4396820" ,
  46.                values: [
  47.                   {
  48.                      value: "company.moc"
  49.                   }
  50.                ]
  51.             } ,
  52.             {
  53.                id: "4400115" ,
  54.                values: [
  55.                   {
  56.                      value: "ул. Октябрьская, д. 2" ,
  57.                      subtype: "address_line_1"
  58.                   } ,
  59.                   {
  60.                      value: "Москва" ,
  61.                      subtype: "city"
  62.                   } ,
  63.                   {
  64.                      value: "102030" ,
  65.                      subtype: "zip"
  66.                   } ,
  67.                   {
  68.                      value: "RU" ,
  69.                      subtype: "country"
  70.                   }
  71.                ]
  72.             }
  73.          ]
  74.       }
  75.    ]
  76. }

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

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

  1. {
  2.    update: [
  3.       {
  4.          id: "41389" ,
  5.          updated_at: "1508965200" ,
  6.          custom_fields: [
  7.             {
  8.                id: "315289" ,
  9.                values: [
  10.                   {
  11.                      value: "example.moc" ,
  12.                      enum : "WEB"
  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.    _links: {
  3.       self: {
  4.          href: "/api/v2/companies" ,
  5.          method: "post"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099264 ,
  12.             _links: {
  13.                self: {
  14.                   href: "/api/v2/companies?id=1099264" ,
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

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

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

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

Список компаний

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

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

GET параметры

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

Вы также можете передать дополнительный 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 группы в которой состоит пользователь ответственный за данную компнаию
contacts array Массив, содержащий информацию о контактах, которые прикреплены к данной компании
contacts/id int id контакта, который прикреплён к данной компании
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/companies?id=1099264" ,
  5.          method: "get"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099264 ,
  12.             name: "ООО Компания" ,
  13.             responsible_user_id: 504141 ,
  14.             created_by: 504141 ,
  15.             created_at: 1508965200 ,
  16.             updated_at: 1509028320 ,
  17.             account_id: 13667499 ,
  18.             updated_by: 504141 ,
  19.             group_id: 0 ,
  20.             leads: {
  21.                id: [
  22.                   1090408 ,
  23.                   1090409 ,
  24.                   1090410
  25.                ] ,
  26.                _links: {
  27.                   self: {
  28.                      href: "/api/v2/leads?id=1090408,1090409,1090410" ,
  29.                      method: "get"
  30.                  }
  31.                }
  32.             } ,
  33.             closest_task_at: 0 ,
  34.             tags: [
  35.                {
  36.                   id: 61883 ,
  37.                   name: "недвижимость"
  38.                } ,
  39.                {
  40.                   id: 61884 ,
  41.                   name: "застройка"
  42.                } ,
  43.                {
  44.                   id: 61885 ,
  45.                   name: "аренда"
  46.                }
  47.             ] ,
  48.             custom_fields: [
  49.                {
  50.                   id: 4396818 ,
  51.                   name: "Телефон" ,
  52.                   values: [
  53.                      {
  54.                         value: "89999517535" ,
  55.                         enum : "3685087"
  56.                      } ,
  57.                      {
  58.                         value: "89991237895" ,
  59.                         enum : "3685089"
  60.                      }
  61.                   ] ,
  62.                   is_system: true
  63.                } ,
  64.                {
  65.                   id: 4396819 ,
  66.                   name: "Email" ,
  67.                   values: [
  68.                      {
  69.                         value: "company@company.moc" ,
  70.                         enum : "3685093"
  71.                      }
  72.                   ] ,
  73.                   is_system: true
  74.                } ,
  75.                {
  76.                   id: 4396820 ,
  77.                   name: "Web" ,
  78.                   values: [
  79.                      {
  80.                         value: http: //company.moc
  81.                      }
  82.                   ] ,
  83.                   is_system: true
  84.                }
  85.             ] ,
  86.             contacts: {
  87.                id: [
  88.                   1099181 ,
  89.                   1099268 ,
  90.                   1099269
  91.                ] ,
  92.                _links: {
  93.                   self: {
  94.                      href: "/api/v2/contacts?id=1099181,1099268,1099269" ,
  95.                      method: "get"
  96.                   }
  97.                }
  98.             } ,
  99.             customers: [ ] ,
  100.             _links: {
  101.                self: {
  102.                   href: "/api/v2/companies?id=1099264" ,
  103.                   method: "get"
  104.                }
  105.             }
  106.          }
  107.       ]
  108.    }
  109. }

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

  1. /* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
  2. $subdomain = 'test' ; #Наш аккаунт - поддомен
  3. #Формируем ссылку для запроса
  4. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies' ;
  5. /* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
  6. документацию).
  7. Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
  8. необходимо. */
  9. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies' ;
  10. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies?limit_rows=15' ;
  11. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies?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. catch(Exception $E )
  51. {
  52.   die ( 'Ошибка: ' . $E -> getMessage ( ) .PHP_EOL. 'Код ошибки: ' . $E -> getCode ( ) ) ;
  53. }
  54. /*
  55.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  56.  нам придётся перевести ответ в формат, понятный PHP
  57.  */
  58. $Response = json_decode ( $out , true ) ;
  59. $Response = $Response [ '_embedded' ] [ 'items' ] ;