Контакты

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

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

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

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


{
	add: [{
		name: "Александр Крылов",
		responsible_user_id: "504141",
		created_by: "504141",
		created_at: "1509051600",
		tags: "важный,доставка",
		leads_id: [
			"45615",
			"43510"
		],
		company_id: "30615",
		custom_fields: [{
				id: "4396817",
				values: [{
					value: "Менеджер по продажам"
				}]
			},
			{
				id: "4396818",
				values: [{
						value: "89990123456",
						enum: "WORK"
					},
					{
						value: "89997894561",
						enum: "WORKDD"
					},
					{
						value: "89991597532",
						enum: "MOB"
					}
				]
			},
			{
				id: "4396819",
				values: [{
					value: "example@example.moc",
					enum: "WORK"
				}]
			},
			{
				id: "4396821",
				values: [{
					value: "example.example",
					enum: "SKYPE"
				}]
			},
			{
				id: "4400115",
				values: [{
						value: "ул. Ленина, д. 1",
						subtype: "address_line_1"
					},
					{
						value: "Москва",
						subtype: "city"
					},
					{
						value: "101010",
						subtype: "zip"
					},
					{
						value: "RU",
						subtype: "country"
					}
				]
			},
			{
				id: "4400116",
				values: [
					"3692662",
					"3692663"
				]
			}
		]
	}]
}

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

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


{
	update: [{
		id: "41560",
		updated_at: "1508965200",
		custom_fields: [{
			id: "4396819",
			values: [{
				value: "example@example.moc",
				enum: "WORK"
			}]
		}]
	}]
}

Параметры ответа

Параметр Описание
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

Пример ответа


{
	_link: {
		self: {
			href: "/api/v2/contacts",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 1099235,
			_link: {
				self: {
					href: "/api/v2/contacts?id=1099235",
					method: "get"
				}
			}
		}]
	}
}

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

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


$contacts['add'] = array(
    array(
        'name' => 'Александр Крылов',
        'responsible_user_id' => 504141,
        'created_by' => 504141,
        'created_at' => "1509051600",
        'tags' => "важный,доставка",
        'leads_id' => array(
            "45615",
            "43510",
        ),
        'company_id' => 30615,
        'custom_fields' => array(
            array(
                'id' => 4396817,
                'values' => array(
                    array(
                        'value' => "Менеджер по продажам",
                    ),
                ),
            ),
            array(
                'id' => 4396818,
                'values' => array(
                    array(
                        'value' => "89990123456",
                        'enum' => "WORK",
                    ),
                    array(
                        'value' => "89997894561",
                        'enum' => "WORKDD",
                    ),
                    array(
                        'value' => "89991597532",
                        'enum' => "MOB",
                    ),
                ),
            ),
            array(
                'id' => 4396819,
                'values' => array(
                    array(
                        'value' => "example@example.moc",
                        'enum' => "WORK",
                    ),
                ),
            ),
            array(
                'id' => 4396821,
                'values' => array(
                    array(
                        'value' => "example.example",
                        'enum' => "SKYPE",
                    ),
                ),
            ),
            array(
                'id' => 4400115,
                'values' => array(
                    array(
                        'value' => "ул. Ленина, д. 1",
                        'subtype' => "address_line_1",
                    ),
                    array(
                        'value' => "Москва",
                        'subtype' => "city",
                    ),
                    array(
                        'value' => "101010",
                        'subtype' => "zip",
                    ),
                    array(
                        'value' => "RU",
                        'subtype' => "country",
                    ),
                ),
            ),
            array(
                'id' => 4400116,
                'values' => array(
                    "3692662",
                    "3692663",
                ),
            ),
        ),
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/contacts';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($contacts));
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/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.

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

Пример ответа


{
	_links: {
		self: {
			href: "/api/v2/contacts?id=1099181",
			method: "get"
		}
	},
	_embedded: {
		items: [{
			id: 1099181,
			name: "Екатерина Долгорукова",
			responsible_user_id: 504141,
			created_by: 504141,
			created_at: 1508499477,
			updated_at: 1509019136,
			account_id: 13667499,
			updated_by: 504141,
			group_id: 0,
			company: {
				id: 1099180,
				name: "ООО Компания",
				_links: {
					self: {
						href: "/api/v2/companies?id=1099180",
						method: "get"
					}
				}
			},
			leads: {
				id: [
					1090391
				],
				_links: {
					self: {
						href: "/api/v2/leads?id=1090391",
						method: "get"
					}
				}
			},
			closest_task_at: 1509051540,
			tags: [{
					id: 61881,
					name: "доставка"
				},
				{
					id: 61882,
					name: "важный"
				}
			],
			custom_fields: [{
					id: 4396818,
					name: "Телефон",
					values: [{
						value: "89996123232",
						enum: "3685087"
					}],
					is_system: true
				},
				{
					id: 4396821,
					name: "Мгн. сообщения",
					values: [{
						value: "example.example",
						enum: "3685096"
					}],
					is_system: true
				},
				{
					id: 4400115,
					name: "Адрес",
					values: [{
							value: "ул. Ленина, д. 1, г. Москва",
							subtype: "1"
						},
						{
							value: "RU",
							subtype: "6"
						}
					],
					is_system: false
				},
				{
					id: 4400116,
					name: "Мультисписок",
					values: [{
							value: "2",
							enum: "3692663"
						},
						{
							value: "3",
							enum: "3692664"
						}
					],
					is_system: false
				}
			],
			customers: {
				id: [
					466791
				],
				_links: {
					self: {
						href: "/api/v2/customers?id=466791",
						method: "get"
					}
				}
			},
			_links: {
				self: {
					href: "/api/v2/contacts?id=1099181",
					method: "get"
				}
			}
		}]
	}
}

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


/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/contacts/';
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
документацию).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
необходимо. */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/contacts/';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/contacts/?limit_rows=15';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/contacts/?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'];

Смотрите также

КОДЫ ОШИБОК API