Если у вас еще нет amoCRM
Создать прямо сейчасОдна из основных сущностей системы. Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждый контакт может участвовать в одной и более сделке или может быть вообще не связан ни с одной. Каждый контакт может быть прикреплен к одной компании.
E-mail контакта и телефон используются как уникальные идентификаторы в связке с другими системами. К примеру, именно в события контакта попадает информация о совершенных звонках, о e-mail-переписке.
Каждому контакту может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.
Метод позволяет добавлять контакты по одному или пакетно, а также обновлять данные по уже существующим контактам.
POST /api/v2/contacts
| Параметр | Тип | Описание |
|---|---|---|
| add | array | Список добавляемых контактов |
| update | array | Список существующих контактов, в который будут заноситься изменения. Все параметры, описанные для add, актуальны также для update |
| add/name require |
string | Название контакта, автоматическое распознавание имени и фамилии, если имя и фамилия будут найдены запишутся в поля first_name и last_name. |
| add/first_name | string | Имя контакта |
| add/last_name | 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 содержит следующие заголовки:
{
_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’] несколько массивов, каждый из которых описывает необходимые данные для создания соответствующего контакта.
<?php
$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 контактов.
GET /api/v2/contacts/
| Параметр | Описание |
|---|---|
| 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 | Название контакта (полное имя контакта) |
| first_name | string | Имя контакта |
| last_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 содержит следующие заголовки:
{
_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"
}
}
}]
}
}
<?php
/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$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'];