Компании

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

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 string Контакты, привязываемые к компании. Перечисляются id через запятую.
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'];