Воронки и этапы продаж

Добавление и обновление воронок и этапов продаж

Этапы продаж – это последовательность шагов, которые проходит потенциальный клиент (лид) по воронке продаж перед покупкой. В amoCRM можно создавать несколько воронок продаж в одном аккаунте и задавать свои этапы для отслеживания хода сделки в каждой воронке. В amoCRM можно настроить до 10-и воронок в аккаунте. Каждая воронка может содержать до 100 этапов (включая успешный и неуспешный статусы). Настроить воронки и этапы продаж может администратор аккаунт на странице Настройки->Этапы продаж.

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

URL метода

POST /private/api/v2/json/pipelines/set

Параметры

Параметр Тип Описание
add array Список добавляемых воронок, если возникнет ошибка, то этот ключ будет указан в описании к ошибке
update array Обновление существующей воронки 
Все параметры, которые описаны в add действуют также и в update
add/name 
require
string Имя воронки
add/sort int Порядковый номер воронки при отображении
add/is_main string Является ли воронка “главной” (необходимо передать значение “on”, если является)
add/statuses array Этапы воронки, необходимо передать хотя бы один этап, кроме успешно/неуспешно завершенного. 
В качестве ключа необходимо передать идентификатор этапа, если он существует. Для этапов успешно/неуспешно завершенно (id 142/143 соответственно) возможно передать только поле name
add/statuses// array Внутри него будет описание каждого этапа
add/statuses//name string Название этапа
add/statuses//sort int Порядковый номер этапа при отображении (автоматически пересчитывается после добавления)
add/statuses//color string Цвет этапа (подробнее можно узнать здесь)
update/id 
require
int Уникальный идентификатор воронки, который указывается с целью её обновления
update/statuses//id 
require
int Уникальный идентификатор этапа, который указывается с целью её обновления

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


{
	"request": {
		"pipelines": {
			"add": [{
				"name": "Test Pipeline",
				"statuses": {
					"0": {
						"color": "#fffeb2",
						"name": "Status #0",
						"sort": 0
					},
					"1": {
						"color": "#fffeb2",
						"name": "Status #1",
						"sort": 10
					},
					"2": {
						"color": "#d6eaff",
						"name": "Status #2",
						"sort": 20
					},
					"3": {
						"color": "#f3beff",
						"name": "Status #3",
						"sort": 30
					},
					"142": {
						"name": "Success"
					},
					"143": {
						"name": "Failed"
					}
				},
				"is_main": "false"
			}]
		},
		"update": {
			"2521": {
				"id": 2521,
				"name": "Retest Pipeline",
				"sort": 12,
				"is_main": "on",
				"statuses": {
					"10223179": {
						"id": 10223179,
						"name": "Status #0",
						"sort": 10,
						"color": "#fffeb2"
					},
					"10223183": {
						"id": 10223183,
						"name": "Status #4",
						"sort": 50,
						"color": "#deff81"
					},
					"10223184": {
						"id": 10223184,
						"name": "Status #5",
						"sort": 60,
						"color": "#d6eaff"
					},
					"10223185": {
						"id": 10223185,
						"name": "Status #6",
						"sort": 70,
						"color": "#fffd7f"
					}
				}
			}
		}
	}
}

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

Параметр Описание
add/pipelines//id Уникальный идентификатор воронки
add/pipelines//value Уникальный идентификатор воронки
add/pipelines//label Название воронки
add/pipelines//name Название воронки
add/pipelines//sort Порядковый номер воронки при отображении
add/pipelines//is_main Является ли воронка “главной”
add/pipelines//statuses//id Уникальный идентификатор этапа
add/pipelines//statuses//name Название этапа
add/pipelines//statuses//pipeline_id Уникальный идентификатор воронки
add/pipelines//statuses//sort Порядковый номер этапа при отображении
add/pipelines//statuses//color Цвет этапа (подробнее можно узнать здесь)
add/pipelines//statuses//editable Есть ли возможность изменить или удалить этот этап, возможные значения: “Y” или “N”
add/pipelines//leads Количество сделок, находящихся в этой воронке
update// Ассоциативный массив, где ключ – ID воронки, а значение – удалось ли применить изменение к воронке с этим идентификатором
server_time Временная метка текущего серверного времени со смещением на часовой пояс аккаунта (передается в формате timestamp)

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


{
	"response": {
		"pipelines": {
			"add": {
				"pipelines": {
					"2116": {
						"id": 2116,
						"value": 2116,
						"label": "Pipeline",
						"name": "Pipeline",
						"sort": 1,
						"is_main": true,
						"statuses": {
							"142": {
								"id": 142,
								"name": "Closed - won",
								"color": "#CCFF66",
								"sort": 10000,
								"editable": "N",
								"pipeline_id": 2116
							},
							"143": {
								"id": 143,
								"name": "Closed - lost",
								"color": "#D5D8DB",
								"sort": 11000,
								"editable": "N",
								"pipeline_id": 2116
							},
							"10216993": {
								"id": 10216993,
								"name": "Initial Contact",
								"pipeline_id": 2116,
								"sort": 10,
								"color": "#99ccff",
								"editable": "Y"
							},
							"10216994": {
								"id": 10216994,
								"name": "Offer made",
								"pipeline_id": 2116,
								"sort": 20,
								"color": "#ffff99",
								"editable": "Y"
							},
							"10216995": {
								"id": 10216995,
								"name": "Negotiation",
								"pipeline_id": 2116,
								"sort": 30,
								"color": "#ffcc66",
								"editable": "Y"
							},
							"10216996": {
								"id": 10216996,
								"name": "Contract Negotiation",
								"pipeline_id": 2116,
								"sort": 40,
								"color": "#ffcccc",
								"editable": "Y"
							}
						},
						"leads": 14
					}
				}
			},
			"update": {
				"2521": true
			}
		}
	}
}

Добавление воронки

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

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


$pipelines['request']['pipelines']['add'] = array(
    array(
        'name' => 'Test Pipeline',
        'statuses' => array(
            array(
                'color' => '#deff81',
                'name' => 'Status #0',
                'sort' => 0,
            ),
            array(
                'color' => '#ffeab2',
                'name' => 'Status #1',
                'sort' => 10,
            ),
            array(
                'color' => '#ffdc7f',
                'name' => 'Status #2',
                'sort' => 20,
            ),
            array(
                'color' => '#deff81',
                'name' => 'Status #3',
                'sort' => 30,
            ),
            array(
                'color' => '#ebffb1',
                'name' => 'Status #4',
                'sort' => 40,
            ),
            array(
                'color' => '#fffeb2',
                'name' => 'Status #5',
                'sort' => 50,
            ),
            array(
                'color' => '#ffc8c8',
                'name' => 'Status #6',
                'sort' => 60,
            ),
            array(
                'color' => '#c1e0ff',
                'name' => 'Status #7',
                'sort' => 70,
            ),
            array(
                'color' => '#f3beff',
                'name' => 'Status #8',
                'sort' => 80,
            ),
            array(
                'color' => '#ccc8f9',
                'name' => 'Status #9',
                'sort' => 90,
            ),
        ),
        'is_main' => 'on',
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/private/api/v2/json/pipelines/set';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($pipelines));
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['response']['pipelines']['add'];
$output = 'ID добавленных воронок:' . PHP_EOL;
$output .= implode(PHP_EOL, array_keys($Response));
return $output;

Обновление воронок

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

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


$pipelines['request']['pipelines']['update'] = array(
    2116 => array(
        'id' => 2116,
        'name' => 'Renamed Pipeline',
        'sort' => 1,
        'is_main' => false,
        'statuses' => array(
            10216993 => array(
                'id' => 10216993,
                'name' => 'Initial Contact',
                'sort' => 10,
                'color' => '#99ccff',
            ),
            10216994 => array(
                'id' => 10216994,
                'name' => 'Offer made',
                'sort' => 20,
                'color' => '#ffff99',
            ),
            10216995 => array(
                'id' => 10216995,
                'name' => 'Negotiation',
                'sort' => 30,
                'color' => '#ffcc66',
            ),
            array(
                'name' => 'New status#1',
                'sort' => 40,
                'color' => '#ffff99',
            ),
            array(
                'name' => 'New status#2',
                'sort' => 50,
                'color' => '#99ccff',
            ),
            array(
                'name' => 'New status#3',
                'sort' => 60,
                'color' => '#ffcccc',
            ),
            142 => array(
                'name' => 'Closed_won',
            ),
            143 => array(
                'name' => 'Closed_lost',
            ),
        ),
        'leads' => 14,
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/private/api/v2/json/pipelines/set';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($pipelines));
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());
}

Удаление воронок

Метод позволяет удалять воронки по одной или пакетно.

Удаление одной воронки в аккаунте невозможно, при удалении последней воронки выдается ошибка “Impossible to delete last pipeline”

URL метода

POST /private/api/v2/json/pipelines/delete

Параметры

Параметр Тип Описание
id array ID воронок, которые необходимо удалить. Можно передать как единственное число, так и массив чисел.

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

{ "request": { "id": 123 } }
{ "request": { "id": [ 123, 456 ] } }

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

Параметр Описание
response// Ассоциативный массив, где ключом является id воронки, а значением – удалось ли удалить воронку
response//errors Если удалить воронку не удалось, то здесь будет написана причина.
server_time Временная метка текущего серверного времени со смещением на часовой пояс аккаунта (передается в формате timestamp)

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


{
	"response": {
		123: true,
		456: {
			"errors": "Impossible to delete last pipeline"
		}
	}
}

Удаление воронки

Для удаления воронки необходимо описать массив, содержащий идентификатор(ы) удаляемой воронки и поместить его в массив вида: $pipelines[‘request’][‘id’]

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


$pipelines['request']['id'] = array(123);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/private/api/v2/json/pipelines/delete';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($pipelines));
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['response'];
$output = 'Результат запроса:' . PHP_EOL;
foreach ($Response as $pipeline_id => $result) {
    if (isset($result['errors'])) {
        $output .= 'Воронка "' . $pipeline_id . '" не удалена, причина: "' . $result['errors'] . '"' . PHP_EOL;
    } else {
        $output .= 'Воронка "' . $pipeline_id . '" удалена' . PHP_EOL;
    }
}
return $output;

Список воронок и этапов продаж

Метод для получения списка воронок и этапов продаж.

URL метода

GET /api/v2/pipelines

Параметры GET

Параметр Описание
id Выбрать воронку с заданным ID

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

Параметр Тип Описание
id int Уникальный идентификатор воронки
name string Название воронки
sort int Порядковый номер воронки при отображении
is_main bool Является ли воронка “главной”
statuses array Массив содержащий информацию о этапах продаж
statuses//id int Уникальный идентификатор этапа
statuses//name string Название этапа
statuses//color string Цвет этапа
statuses//sort int Порядковый номер этапа при отображении
statuses//is_editable bool Есть ли возможность изменить или удалить этот этап
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

Цвета этапов продаж

Код Пример
#fffeb2 color example
#fffd7f color example
#fff000 color example
#ffeab2 color example
#ffdc7f color example
#ffce5a color example
#ffdbdb color example
#ffc8c8 color example
#ff8f92 color example
#d6eaff color example
#c1e0ff color example
#98cbff color example
#ebffb1 color example
#deff81 color example
#87f2c0 color example
#f9deff color example
#f3beff color example
#ccc8f9 color example
#eb93ff color example
#f2f3f4 color example
#e6e8ea color example

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


{
	_links: {
		self: {
			href: "/api/v2/pipelines",
			method: "get"
		}
	},
	_embedded: {
		items: {
			10104: {
				id: 10104,
				name: "Воронка",
				sort: 1,
				is_main: true,
				statuses: {
					142: {
						id: 142,
						name: "Успешно реализовано",
						color: "#CCFF66",
						sort: 10000,
						is_editable: false
					},
					143: {
						id: 143,
						name: "Закрыто и не реализовано",
						color: "#D5D8DB",
						sort: 11000,
						is_editable: false
					},
					13667501: {
						id: 13667501,
						name: "Первичный контакт",
						color: "#99ccff",
						sort: 10,
						is_editable: true
					},
					13667502: {
						id: 13667502,
						name: "Переговоры",
						color: "#ffff99",
						sort: 20,
						is_editable: true
					},
					13667503: {
						id: 13667503,
						name: "Принимают решение",
						color: "#ffcc66",
						sort: 30,
						is_editable: true
					},
					13667504: {
						id: 13667504,
						name: "Согласование договора",
						color: "#ffcccc",
						sort: 40,
						is_editable: true
					}
				}
			}
		}
	}
}

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


$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/pipelines';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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_HTTPHEADER, ['Accept: application/json']);
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_HEADER, false);
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);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$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'];