Полностью аналогична сущности "контакт". Состоит из предустановленного набора полей и дополнительных, создаваемых
администратором
аккаунта. Каждая компания может участвовать в одной и более сделке или может быть вообще не связана ни с одной.
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 открепляемых покупателей |
Приведём пример запроса на добавление новой компании.
Пример запроса
{
add: [
{
name: "ООО Компания",
responsible_user_id: "504141",
created_by: "504141",
created_at: "1509051600",
tags: "недвижимость,застройка,аренда",
leads_id: [
"45615",
"43510"
],
custom_fields: [
{
id: "4396817",
values: [
{
value: "5"
}
]
},
{
id: "4396818",
values: [
{
value: "89999517535",
enum: "WORK"
},
{
value: "89991237895",
enum: "MOB"
}
]
},
{
id: "4396819",
values: [
{
value: "company@company.moc",
enum: "WORK"
}
]
},
{
id: "4396820",
values: [
{
value: "company.moc"
}
]
},
{
id: "4400115",
values: [
{
value: "ул. Октябрьская, д. 2",
subtype: "address_line_1"
},
{
value: "Москва",
subtype: "city"
},
{
value: "102030",
subtype: "zip"
},
{
value: "RU",
subtype: "country"
}
]
}
]
}
]
}
Приведём пример запроса на обновление компании.
Пример запроса
{
update: [
{
id: "41389",
updated_at: "1508965200",
custom_fields: [
{
id: "315289",
values: [
{
value: "example.moc",
enum: "WEB"
}
]
}
]
}
]
}
Параметры ответа
Параметр |
Описание |
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
Пример ответа
{
_links: {
self: {
href: "/api/v2/companies",
method: "post"
}
},
_embedded: {
items: [
{
id: 1099264,
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
}
}
]
}
}
Пример интеграции
Для добавления компании необходимо описать массив, содержащий информацию о компании, и поместить его в массив
следующего вида:
$companies['add']. Наше API также поддерживает одновременное добавление сразу нескольких компаний. Для этого мы помещаем в
массив
$companies['add'] несколько массивов, каждый из которых описывает необходимые данные для создания соответствующего
контакта.
'name' => 'ООО Компания',
'responsible_user_id' => 504141,
'created_by' => 504141,
'created_at' => "1509051600",
'tags' => "недвижимость,застройка,аренда",
"45615",
"43510"
),
'custom_fields' => array(
'id' => 4396818,
'value' => "89993456872",
'enum' => "WORK"
),
'value' => "89998495162",
'enum' => "MOB"
)
)
),
'id' => 4396819,
'value' => "company@company.moc",
'enum' => "WORK"
)
)
),
'id' => 4400115,
'value' => "ул. Октябрьская, д. 2",
'subtype' => "address_line_1"
),
value: "Москва",
subtype: "city"
),
value: "102030",
subtype: "zip"
),
value: "RU",
subtype: "country"
)
)
),
'id' => 3789654,
"2615948",
"2648159",
"2653867"
)
)
)
)
)
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain='test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link='https://'.$subdomain.'.amocrm.ru/api/v2/companies';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl=curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl,CURLOPT_USERAGENT
,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_COOKIEFILE
,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR
,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
$out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code=(int)$code;
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
if($code!=200 && $code!=204)
throw new Exception
(isset($errors[$code]) ?
$errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
die('Ошибка: '.$E->getMessage().PHP_EOL
.'Код ошибки: '.$E->getCode());
}
/*
Данные получаем в формате JSON, поэтому, для получения читаемых данных,
нам придётся перевести ответ в формат, понятный PHP
*/
$Response=$Response[_embedded']['items'];
$output='ID добавленных контактов:'.PHP_EOL;
foreach($Response as $v)
if(is_array($v))
$output.=$v['id'].PHP_EOL;
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.
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
Пример ответа
{
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
},
_embedded: {
items: [
{
id: 1099264,
name: "ООО Компания",
responsible_user_id: 504141,
created_by: 504141,
created_at: 1508965200,
updated_at: 1509028320,
account_id: 13667499,
updated_by: 504141,
group_id: 0,
leads: {
id: [
1090408,
1090409,
1090410
],
_links: {
self: {
href: "/api/v2/leads?id=1090408,1090409,1090410",
method: "get"
}
}
},
closest_task_at: 0,
tags: [
{
id: 61883,
name: "недвижимость"
},
{
id: 61884,
name: "застройка"
},
{
id: 61885,
name: "аренда"
}
],
custom_fields: [
{
id: 4396818,
name: "Телефон",
values: [
{
value: "89999517535",
enum: "3685087"
},
{
value: "89991237895",
enum: "3685089"
}
],
is_system: true
},
{
id: 4396819,
name: "Email",
values: [
{
value: "company@company.moc",
enum: "3685093"
}
],
is_system: true
},
{
id: 4396820,
name: "Web",
values: [
{
value: http://company.moc
}
],
is_system: true
}
],
contacts: {
id: [
1099181,
1099268,
1099269
],
_links: {
self: {
href: "/api/v2/contacts?id=1099181,1099268,1099269",
method: "get"
}
}
},
customers: [],
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
}
}
]
}
}
Пример интеграции
/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain='test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link='https://'.$subdomain.'.amocrm.ru/api/v2/companies';
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
документацию).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
необходимо. */
$link='https://'.$subdomain.'.amocrm.ru/api/v2/companies';
$link='https://'.$subdomain.'.amocrm.ru/api/v2/companies?limit_rows=15';
$link='https://'.$subdomain.'.amocrm.ru/api/v2/companies?limit_rows=15&limit_offset=2';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl=curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl,CURLOPT_USERAGENT
,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_COOKIEFILE
,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR
,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
$out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
/* Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y
H:i:s. При
передаче этого заголовка будут возвращены контакты, изменённые позже этой даты. */
curl_setopt($curl,CURLOPT_HTTPHEADER
,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code=(int)$code;
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
if($code!=200 && $code!=204)
throw new Exception
(isset($errors[$code]) ?
$errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
die('Ошибка: '.$E->getMessage().PHP_EOL
.'Код ошибки: '.$E->getCode());
}
/*
Данные получаем в формате JSON, поэтому, для получения читаемых данных,
нам придётся перевести ответ в формат, понятный PHP
*/
$Response=$Response['_embedded']['items'];