Сделки

Добавление и обновление сделки

Метод позволяет добавлять сделки по одной или пакетно, а также обновлять данные по уже существующим сделкам.

URL метода

POST /api/v2/leads

Параметры

Параметр Тип Описание
add array Список добавляемых сделок
update array Обновление существующих сделок 
Все параметры, которые описаны в add действуют также и в update
add/name
require
string Название сделки
add/created_at timestamp Дата создания текущей сделки
add/updated_at timestamp Дата изменения текущей сделки
add/status_id int Статус сделки (id этапа продаж см. Воронки и этапы продаж) Чтобы перенести сделку в другую воронку, необходимо установить ей статус из нужной воронки
add/pipeline_id int ID воронки. Указывается в том случае, если выбраны статусы id 142 или 143, т.к. эти статусы не уникальны и обязательны для всех цифровых воронок.
add/responsible_user_id int ID ответственного пользователя
add/sale int Бюджет сделки
add/tags array/string Если вы хотите задать новые теги, перечислите их внутри строковой переменной через запятую. В случае если вам необходимо прикрепить существующие теги, передавайте массив числовых значений id существующих тегов.
add/contacts_id int/array Уникальный идентификатор контакта, для связи с сделкой. Можно передавать несколько id, перечисляя их в массиве через запятую. (Не более 40 контактов у 1 сделки, если вам необходимо большее количество, обратитесь в Техническую Поддержку)
add/company_id int Уникальный идентификатор компании, для связи с сделкой
add/custom_fields array Внутри данного массива находится содержимое каждого заполненного дополнительного поля
add/custom_fields//id int Уникальный идентификатор заполняемого дополнительного поля
add/custom_fields//values array Массив значений
add/custom_fields//values//value string Значение дополнительного поля
add/custom_fields//values//subtype string Тип изменяемого элемента дополнительного поля типа “адрес”. Внимание, все типы, которые не были переданы, будут стёрты
add/catalog_elements_id string Список элементов каталогов для привязки с указанием количества, сгруппированный по ID каталога
update/id
require
int id сделки, в которую будут вноситься изменения
update/updated_at
required
timestamp Время
update/unlink array Массив, содержащий информацию для открепления сделки от других элементов сущностей.
update/unlink/contacts_id array Массив id открепляемых контактов
update/unlink/company_id int id открепляемой компании

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

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


{
	add: [{
		name: "Покупка карандашей",
		created_at: "1508101200",
		updated_at: "1508274000",
		status_id: "13670637",
		responsible_user_id: "957083",
		sale: "5000",
		tags: "pencil, buy",
		contacts_id: [
			"1099149"
		],
		company_id: "1099148",
		catalog_elements_id: {
			99999: {
				111111: 10
			}
		},
		custom_fields: [{
				id: "4399649",
				values: [
					"3691615",
					"3691616",
					"3691617"
				]
			},
			{
				id: "4399656",
				values: [{
					value: "2017-10-26"
				}]
			},
			{
				id: "4399655",
				values: [{
						value: "ул. Охотный ряд, 1",
						subtype: "address_line_1"
					},
					{
						value: "Москва",
						subtype: "city"
					},
					{
						value: "101010",
						subtype: "zip"
					},
					{
						value: "RU",
						subtype: "country"
					}
				]
			}
		]
	}]
}

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

Приведём пример запроса на изменения данных существующей сделки.


{
	update: [{
		id: "1090256",
		updated_at: "1508360400",
		sale: "10000",
		custom_fields: [{
				id: "4399664",
				values: [{
					value: "3691641"
				}]
			},
			{
				id: "4399665",
				values: [
					"3691643",
					"3691644"
				]
			},
			{
				id: "4399663",
				values: [{
					value: "пр-т Ленина, д. 2",
					subtype: "address_line_1"
				}]
			}
		]
	}]
}

Описание параметров ответа

Параметр Описание
id Уникальный идентификатор новой сущности
request_id Уникальный идентификатор сущности в клиентской программе, если request_id не передан в запросе, то он генерируется автоматически
_links Массив содержащий информацию о запросе
_links/self Массив содержащий информацию о текущем запросе
_links/self/href Относительный URL текущего запроса
_links/self/method Метод текущего запроса
_embedded Массив содержащий информацию прилегающую к запросу
_embedded/items Массив содержащий информацию по каждому отдельному элементу

Response Headers содержит следующие заголовки:

  • Content-Type:application/hal+json
  • Runtime-Timestamp:1508320306

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


{
	_links: {
		self: {
			href: "/api/v2/leads",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 1090255,
			request_id: 0,
			_link: {
				self: {
					href: "/api/v2/leads?id=1090255",
					method: "get"
				}
			}
		}]
	}
}

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

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


$leads['add'] = array(
    array(
        'name' => 'Сделка по карандашам',
        'created_at' => 1298904164,
        'status_id' => 142,
        'sale' => 300000,
        'responsible_user_id' => 215302,
        'tags' => 'Important, USA', #Теги
        'custom_fields' => array(
            array(
                'id' => 427496, #Уникальный индентификатор заполняемого дополнительного поля
                'values' => array( # id значений передаются в массиве values через запятую
                1240665,
                    1240664,
                ),
            ),
            array(
                'id' => 427497, #Уникальный индентификатор заполняемого дополнительного поля
                'values' => array(
                    array(
                        'value' => 1240667,
                    ),
                ),
            ),
            array(
                'id' => 427231, #Уникальный индентификатор заполняемого дополнительного поля
                'values' => array(
                    array(
                        'value' => '14.06.2014', # в качестве разделителя используется точка
                    ),
                ),
            ),
            array(
                'id' => 458615, #Уникальный индентификатор заполняемого дополнительного поля
                'values' => array(
                    array(
                        'value' => 'Address line 1',
                        'subtype' => 'address_line_1',
                    ),
                    array(
                        'value' => 'Address line 2',
                        'subtype' => 'address_line_2',
                    ),
                    array(
                        'value' => 'Город',
                        'subtype' => 'city',
                    ),
                    array(
                        'value' => 'Регион',
                        'subtype' => 'state',
                    ),
                    array(
                        'value' => '203',
                        'subtype' => 'zip',
                    ),
                    array(
                        'value' => 'RU',
                        'subtype' => 'country',
                    ),
                ),
            ),
        ),
    ),
    array(
        'name' => 'Бумага',
        'created_at' => 1298904164,
        'status_id' => 7087609,
        'sale' => 600200,
        'responsible_user_id' => 215309,
        'custom_fields' => array(
            array(
                #Нестандартное дополнительное поле типа "мультисписок", которое мы создали
                'id' => 426106,
                'values' => array(
                    1237756,
                    1237758,
                ),
            ),
        ),
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/leads';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($leads));
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());
}

Список сделок

Метод для получения списка сделок с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице (offset) данным – 500 сделок.

URL метода

GET /api/v2/leads

Параметры GET

Параметр Описание
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Сдвиг выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан
id Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID
query Поисковый запрос (Осуществляет поиск по заполненым полям сущности)
responsible_user_id Дополнительный фильтр поиска, по ответственному пользователю
(Можно передавать в виде массива)
with Если в параметре with указать значения (список см. здесь), в ответ придёт информация о сделке по соответствующему значению.
status Фильтр по ID статуса сделки (Как узнать список доступных ID см. здесь)
(Можно передавать в виде массива)
filter/date_create/ Выбрать сделки по дате создания (нужно передавать массив с параметрами from, to)
filter/date_modify/ Выбрать сделки по дате изменения (нужно передавать массив с параметрами from, to)
filter/tasks Выбрать сделки без задач – 1
Выбрать сделки с невыполенными задачами – 2
filter/active Выбрать все активные сделки – 1

Значения для GET параметра

Возможные значения GET параметра with. Указывать можно более одного значения, через “,”.

Пример: https://example.amocrm.ru/api/v2/leads?with=is_price_modified_by_robot,loss_reason_name

Значение Описание
is_price_modified_by_robot Вернёт информацию в соответствующем поле сделок, было ли изменено поле бюджет пользователем роботом (user_id = 0)
loss_reason_name Вернёт помимо 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 аккаунта на котором создана сделка
is_deleted bool Удалена сделка или нет. Удалённые сделки могут находиться в “удалённых”.
main_contact array Массив содержащий информацию о главном контакте сделки
main_contact/id int id главного контакта сделки
group_id int id группы в которой состоит пользователь ответственный за данную сделку
company array Массив содержащий информацию о компании, которая прикреплена к данной сделке
company/id int id компании, которая прикреплена к данной сделке
company/name string название компании, которая прикреплена к данной сделке
closed_at timestamp Время и дата, когда была завершена данная сделка
closest_task_at timestamp Время ближайшей задачи по данной сделки
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 Является ли дополнительное поле системным
contacts array Массив содержащий информацию по контактам прикреплённым к данной сделке
contacts/id int id прикреплённого к сделке контакта
status_id int id этапа цифровой воронки, на котором находится данная сделка
sale int Бюджет сделки
pipeline array Массив содержащий информацию по цифровой воронке, в которой находится данная сделка
pipeline/id int id цифровой воронки, в которой находится данная сделка
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

Response Headers содержит следующие заголовки:

  • Content-Type:application/hal+json
  • Runtime-Timestamp:1508320306

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


{
	_links: {
		self: {
			href: "/api/v2/leads?id=1090256",
			method: "get"
		}
	},
	_embedded: {
		items: [{
			id: 1090256,
			name: "Сделка #1090256",
			responsible_user_id: 957084,
			created_by: 957084,
			created_at: 1508400624,
			updated_at: 1508403644,
			account_id: 13670640,
			is_deleted: false,
			main_contact: {
				id: 1099418,
				_links: {
					self: {
						href: "/api/v2/contacts?id=1099153",
						method: "get"
					}
				}
			},
			group_id: 0,
			company: {
				id: 1099427,
				name: null,
				_links: {
					self: {
						href: "/api/v2/companies?id=1099152",
						method: "get"
					}
				}
			},
			closed_at: 0,
			closest_task_at: 1508446740,
			tags: [],
			custom_fields: [{
					id: 4399664,
					name: "Список",
					values: [{
						value: "5",
						enum: "3691641"
					}],
					is_system: false
				},
				{
					id: 4399665,
					name: "Мультисписок",
					values: [{
							value: "2",
							enum: "3691643"
						},
						{
							value: "3",
							enum: "3691644"
						}
					],
					is_system: false
				},
				{
					id: 4399666,
					name: "Текст",
					values: [{
						value: "Здесь, к примеру, какие-либо пояснения к сделке"
					}],
					is_system: false
				},
				{
					id: 4399663,
					name: "Адрес",
					values: [{
							value: "пр-т Мира, д. 3",
							subtype: "1"
						},
						{
							value: "Москва",
							subtype: "3"
						},
						{
							value: "101010",
							subtype: "5"
						}
					],
					is_system: false
				}
			],
			contacts: {
				id: [
					1099418,
					1099154
				],
				_links: {
					self: {
						href: "/api/v2/contacts?id=1099418,1099154",
						method: "get"
					}
				}
			},
			status_id: 13670642,
			sale: 5000,
			pipeline: {
				id: 10273,
				_links: {
					self: {
						href: "/api/v2/pipelines?id=10246",
						method: "get"
					}
				}
			},
			_links: {
				self: {
					href: "/api/v2/leads?id=1090256",
					method: "get"
				}
			}
		}]
	}
}

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


/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain = 'test'; #Наш аккаунт - поддомен
/* Формируем ссылку для запроса */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/leads';
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите документацию
выше).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
необходимо. */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/leads?limit_rows=50';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/leads?limit_rows=50&limit_offset=2';
/* Следующий запрос вернёт список сделок, у которых есть почта 'test@mail.com' */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/leads?query=test@mail.com';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init();
/* Устанавливаем необходимые опции для сеанса 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);
/* Вы также можете передать дополнительный 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'));
/* Выполняем запрос к серверу. */
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$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