Работа с компаниями

Компании

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

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 открепляемых покупателей

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

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


{
	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’] несколько массивов, каждый из которых описывает необходимые данные для создания соответствующего контакта.


$companies['add'] = array(
    array(
        'name' => 'ООО Компания',
        'responsible_user_id' => 504141,
        'created_by' => 504141,
        'created_at' => "1509051600",
        'tags' => "недвижимость,застройка,аренда",
        'leads_id' => array(
            "45615",
            "43510",
        ),
        'custom_fields' => array(
            array(
                'id' => 4396818,
                'values' => array(
                    array(
                        'value' => "89993456872",
                        'enum' => "WORK",
                    ),
                    array(
                        'value' => "89998495162",
                        'enum' => "MOB",
                    ),
                ),
            ),
            array(
                'id' => 4396819,
                'values' => array(
                    array(
                        'value' => "company@company.moc",
                        'enum' => "WORK",
                    ),
                ),
            ),
            array(
                'id' => 4400115,
                'values' => array(
                    array(
                        'value' => "ул. Октябрьская, д. 2",
                        'subtype' => "address_line_1",
                    ),
                    array(
                        'value' => "Москва",
                        'subtype' => "city",
                    ),
                    array(
                        'value' => "102030",
                        'subtype' => "zip",
                    ),
                    array(
                        'value' => "RU",
                        'subtype' => "country",
                    ),
                ),
            ),
            array(
                'id' => 3789654,
                'values' => array(
                    "2615948",
                    "2648159",
                    "2653867",
                ),
            ),
        ),
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($companies));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($curl, CURLOPT_HEADER, false);
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__
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int) $code;
$errors = array(
    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 = json_decode($out, true);
$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_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_HEADER, false);
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__
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/* Вы также можете передать дополнительный 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;
$errors = array(
    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 = json_decode($out, true);
$Response = $Response['_embedded']['items'];