Покупатели

Методы для работы с Покупателями

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

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

Покупатель обладает периодом, который обозначает положение покупателя в жизненном цикле (бизнес-процесс). Список периодов может быть изменен в рамках аккаунта, кроме первого и трех конечных системных периодов.

Добавление, обновление и удаление покупателей

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

URL метода

POST /api/v2/customers

Параметры

Параметр Тип Описание
add array Список добавляемых покупателей
update array Список существующих покупателей, в которых будут заноситься изменения. Все, описанные для add, актуальны также для update
delete array Массив id удаляемых сделок, перечисляются через запятую.
add/name string Название покупателя
add/next_date timestamp Дата и время следующей покупки
add/created_at timestamp Дата и время создания покупателя
add/updated_at timestamp Дата и время изменения покупателя
add/responsible_user_id int id пользователя ответственного за покупателя
add/created_by int id пользователя создавшего покупателя
add/next_price int Ожидаемая сумма
add/periodicity int Периодичность совершаемых покупок
add/tags string Теги, привязываемые к покупателю. Задаются целостной строковой переменной, внутри строки перечисляются через запятую
add/period_id int id периода цифровой воронки покупателя
add/contacts_id array (int) Массив id существующих контактов, которые привяжутся к покупателю
add/company_id int id существующей компании, которая привяжется к покупателю
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/catalog_elements_id string Список элементов каталогов для привязки с указанием количества, сгруппированный по ID каталога
update/id
require
int id покупателя, в которого будут вноситься изменения
update/updated_at
require
timestamp Дата и время изменения
update/unlink array Массив содержащий информацию для открепления покупателя от других элементов сущностей.
update/unlink/contacts_id array Массив id открепляемых контактов
update/unlink/company_id int id открепляемой компании

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

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

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

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


{
	add: [{
		name: "ООО СпецГорСтрой",
		next_date: "1508878800",
		created_at: "1508533200",
		responsible_user_id: "504141",
		created_by: "504141",
		next_price: "5000",
		periodicity: "7",
		tags: "продажи, маркеры",
		period_id: "15489654",
		contacts_id: [
			"496531"
		],
		company_id: "475621",
		catalog_elements_id: {
			99999: {
				111111: 10
			}
		},
		custom_fields: [{
				id: "4400017",
				values: [{
					value: "Очень важный покупатель"
				}]
			},
			{
				id: "4400021",
				values: [
					"3692471",
					"3692472"
				]
			},
			{
				id: "4399655",
				values: [{
						value: "ул. Охотный ряд, 1",
						subtype: "address_line_1"
					},
					{
						value: "Москва",
						subtype: "city"
					},
					{
						value: "101010",
						subtype: "zip"
					},
					{
						value: "RU",
						subtype: "country"
					}
				]
			}
		]
	}]
}

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


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

Пример запроса на изменение нового покупателя.

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


{
	update: [{
		id: "466791",
		updated_at: "1508619600",
		next_date: "1508878800",
		next_price: "1508706000",
		custom_fields: [{
			id: "4400021",
			values: [
				"3692471",
				"3692472",
				"3692473"
			]
		}]
	}]
}

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


{
	_links: {
		self: {
			href: "/api/v2/customers",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 466791,
			request_id: 466791,
			_links: {
				self: {
					href: "/api/v2/customers?id=466791",
					method: "get"
				}
			}
		}]
	}
}

Удаление покупателя

Пример запроса на удаление покупателей.

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


{
	delete: [
		"466812",
		"466811",
		"466891"
	]
}

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


{
	_links: {
		self: {
			href: "/api/v2/customers",
			method: "post"
		}
	},
	_embedded: {
		items: {
			deleted: [{
					id: 466815,
					name: "Елизавета"
				},
				{
					id: 466816,
					name: "Татьяна"
				}
			]
		}
	}
}

Список покупателей

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

URL метода

GET /api/v2/customers

Параметры GET

Параметр Описание
id Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID)
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Оффсет выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан
filter/main_user// Выбрать элемент по ответственному пользователю (нужно передавать массив с ID пользователей.
filter/date Выбрать элемент по дате создания или редактирования (нужно передавать массив с параметрами type, from, to)
filter/date/type Выбрать элемент по дате создания или редактирования. Тип даты: create или modify.
filter/date/from Дата с которой нужно начинать выборку. В формате ММ/ЧЧ/ГГГГ. Параметр задаётся в связке с параметром filter/date/type.
filter/date/to Дата до которой нужно выбирать. В формате ММ/ЧЧ/ГГГГ. Параметр задаётся в связке с параметром filter/date/type.
filter/next_date Выбрать элемент по дате след. покупки (нужно передавать массив с параметрами from, to)
filter/next_date/from Аналогично filter/date/from
filter/next_date/to Аналогично filter/date/to

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

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

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

Параметр Тип Описание
id int Уникальный идентификатор элемента cущности “Покупатель”
name
require
string Название элемента
responsible_user_id int id пользователя, ответственного за данного покупателя
created_by int id пользователя, создавшего покупателя
created_at timestamp Дата и время создания покупателя
updated_at timestamp Дата и время изменения покупателя
account_id int id аккаунта, на котором создан покупатель
updated_by int id пользователя, изменившего покупателя
is_deleted bool Удален покупатель или нет.
main_contact array Массив содержащий информацию о главном контакте покупателя
main_contact/id int id главного контакта покупателя
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/is_system bool Является ли дополнительное поле системным
contacts array Массив содержащий информацию по контактам прикреплённым к данному покупателю
contacts/id int id прикреплённого к сделке контакта
company array Массив содержащий информацию о компании, которая прикреплена к данному покупателю
company/id int id компании, которая прикреплена к данной сделке
company/name string название компании, которая прикреплена к данной сделке
next_price int Ожидаемая сумма
closest_task_at timestamp Время ближайшей задачи по данному покупателю
period_id timestamp Уникальный идентификатор периода, цифровой воронки покупателей
periodicity int Периодичнось
next_date
require
timestamp Дата следующей покупки
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

Пример GET запроса списка покупателей, созданных от 10.10.2017 
https://example.amocrm.ru/api/v2/customers?filter[date][type]=create&filter[date][from]=10.10.2017

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


{
	_links: {
		self: {
			href: "/api/v2/customers",
			method: "get"
		}
	},
	_embedded: {
		items: [{
			id: 466791,
			name: "Екатерина",
			responsible_user_id: 504141,
			created_by: 504141,
			created_at: 1508500193,
			updated_at: 1508659120,
			account_id: 13667499,
			updated_by: 504141,
			is_deleted: false,
			main_contact: {
				id: 1099181,
				_links: {
					self: {
						href: "/api/v2/contacts?id=1099181",
						method: "get"
					}
				}
			},
			tags: [{
					id: 61869,
					name: "Продажи"
				},
				{
					id: 61870,
					name: "Маркеры"
				}
			],
			custom_fields: [{
					id: 4400017,
					name: "Замечания",
					values: [{
						value: "Задерживают оплату"
					}],
					is_system: false
				},
				{
					id: 4400021,
					name: "Мультисписок",
					values: [{
							value: "3",
							enum: "3692471"
						},
						{
							value: "4",
							enum: "3692472"
						},
						{
							value: "5",
							enum: "3692473"
						}
					],
					is_system: false
				},
			],
			contacts: {
				id: [
					1099181
				],
				_links: {
					self: {
						href: "/api/v2/contacts?id=1099181",
						method: "get"
					}
				}
			},
			company: {
				id: 1099180,
				name: ООО СпецГорСтрой,
				_links: {
					self: {
						href: "/api/v2/companies?id=1099180",
						method: "get"
					}
				}
			},
			next_price: 1508706000,
			closest_task_at: 1508705940,
			period_id: 112804,
			periodicity: 0,
			next_date: 1508878800,
			_links: {
				self: {
					href: "/api/v2/customers?id=466791",
					method: "get"
				}
			}
		}]
	}
}

Пример интеграции, работающей с “Покупателем”

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

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


$customers['add'] = array(
    array(
        'name' => 'Людмила',
        'next_date' => '1508792400',
        'created_at' => '1508619600',
        'responsible_user_id' => 504141,
        'created_by' => 504141,
        'next_price' => 7000,
        'periodicity' => 7,
        'tags' => "Продажи,Карандаши",
        'period_id' => 153795,
        'contacts_id' => array(468986, 468979),
        'company_id' => 356463,
        'custom_fields' => array(
            array(
                'id' => 4400017,
                'values' => array(
                    array(
                        'value' => "Важный клиент",
                    ),
                ),
            ),
            array(
                'id' => 4400021,
                'values' => array(
                    "3692469",
                    "3692470",
                    "3692471",
                ),
            ),
            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,
        'next_date' => '1508782500',
        'next_price' => 600200,
        'responsible_user_id' => 215309,
        'custom_fields' => array(
            array(
                #Нестандартное дополнительное поле типа "мультисписок", которое мы создали
                'id' => 426106,
                'values' => array(
                    1237756,
                    1237758,
                ),
            ),
        ),
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/customers';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($customers));
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());
}

Транзакции

Транзакция – это сущность которая описывает основные характеристики покупки (дата и сумма). Является дополнением для “покупателя”.

Добавление и удаление транзакций

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

Параметры

Параметр Тип Описание
add array Список добавляемых транзакций
add/customer_id int Уникальный идентификатор покупателя
add/date timestamp Дата совершенной покупки
add/price int Сумма совершенной покупки
add/comment string Комментарий к покупке
add/next_date timestamp Ожидаемая дата покупки
add/next_price int Ожидаемая сумма покупки
add/elements array Список элементов каталогов для привязки с указанием количества, сгруппированный по ID каталога
delete array(int) Массив с уникальными идентификаторами транзакций, которые указываются с целью удаления

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

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

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

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


{
	add: [{
		customer_id: "466791",
		date: "1507582800",
		price: "15000",
		comment: "Всё прошло успешно",
		next_date: "1508878800",
		next_price: "20000",
		elements: {
			9999: {
				111111: 3
			}
		}
	}]
}

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


{
	_links: {
		self: {
			href: "/api/v2/transactions",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 5396,
			_links: {
				self: {
					href: "/api/v2/transactions?id=5396",
					method: "get"
				}
			}
		}]
	}
}

Пример запроса, на удаление транзакций

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


{
	delete: [
		"4589",
		"4588",
		"4587"
	]
}

Комментирование транзакций

Метод для добавления и изменения комментария существующей транзакции. При изменении комментария у существующей транзакции, сама транзакция не обновляется.

URL метода

POST /api/v2/transactions/

Параметры

Параметр Тип Описание
update array Список добавляемых/изменяемых комментариев
update/transaction_id
require
int Уникальный идентификатор транзакции
update/comment
require
string Текст комментария

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

Параметр Тип Описание
items array Массив добавленных/изменённых комментариев
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

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


{
	update: [{
		transaction_id: "5396",
		comment: "Составить договор"
	}]
}

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


{
	_links: {
		self: {
			href: "/api/v2/transactions",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 5396,
			_links: {
				self: {
					href: "/api/v2/transactions?id=5396",
					method: "get"
				}
			}
		}]
	}
}

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


$transactions['add'] = array(
    array(
        'price' => 3000,
        'date' => 1476813651,
        'customer_id' => 33221355,
        'comment' => "example",
    ),
    array(
        'price' => 9500,
        'date' => 14762143651,
        'customer_id' => 75321111,
        'comment' => "example 2",
    ),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/transactions';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($transactions));
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());
}

Список транзакций

Метод для получения списка транзакций с возможностью фильтрации.

URL метода

GET /api/v2/transactions

Параметры GET

Параметр Описание
id Выбрать транзакцию с заданным id
customer_id Выбрать транзакцию, которая привязана к покупателю с заданным id
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Оффсет выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан

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

Параметр Тип Описание
items array Массив выбранных транзакций
items/id int Уникальный идентификатор транзакции
items/created_by int ID пользователя, создавшего транзакцию
items/created_at timestamp Дата и время создания транзакции
items/updated_at timestamp Дата и время изменения транзакции
items/account_id int id аккаунта на котором создана транзакция
items/updated_by int id пользователя изменившего транзакцию
items/is_deleted bool Удалена транзакция или нет
items/comment string Комментарий
items/price int Сумма покупки
items/date timestamp Дата покупки
items/customer array Массив содержащий информацию о покупателе
items/customer/id int id покупателя
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

Пример GET запроса списка покупателей, созданных от 10.10.2017 
https://example.amocrm.ru/api/v2/transactions?limit_rows=50&customer_id=46879

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


{
	_links: {
		self: {
			href: "/api/v2/transactions",
			method: "get"
		}
	},
	_embedded: {
		items: [{
				id: 5400,
				created_by: 504141,
				created_at: 1508671514,
				updated_at: 1508671514,
				account_id: 13667499,
				updated_by: 504141,
				is_deleted: false,
				comment: "",
				price: 55555,
				date: 1508360400,
				customer: {
					id: 466791,
					_links: {
						self: {
							href: "/api/v2/customers?id=466791",
							method: "get"
						}
					}
				},
				_links: {
					self: {
						href: "/api/v2/transactions?id=5400",
						method: "get"
					}
				}
			},
			{
				id: 5399,
				created_by: 504141,
				created_at: 1508665872,
				updated_at: 1508665872,
				account_id: 13667499,
				updated_by: 504141,
				is_deleted: false,
				comment: "",
				price: 15000,
				date: 1507582800,
				customer: {
					id: 466791,
					_links: {
						self: {
							href: "/api/v2/customers?id=466791",
							method: "get"
						}
					}
				},
				_links: {
					self: {
						href: "/api/v2/transactions?id=5399",
						method: "get"
					}
				}
			}
		]
	}
}

Периоды покупателей

Периоды покупателей – это последовательность шагов, которые проходит потенциальный клиент (покупатель) по воронке покупателей перед покупкой. В amoCRM можно создавать свои периоды для отслеживания хода покупателя. Воронка покупателей может содержать 10 периодов “до покупки” (включая “недавно купили”, “покупка сегодня” и “не купили”). Настроить периоды может администратор аккаунта на странице Digital Pipeline (Цифровая воронка). Эти методы доступны только администратору аккаунта

Добавление, удаление и обновление периодов покупателей

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

URL метода

POST /api/v2/customers_periods

Параметры

Параметр Тип Описание
update array Редактирование периодов покупателя
update//period int Количество дней в периоде. ВАЖНО!!! Данный параметр определяет фиксированную длину периода и не совпадает с количеством дней “до покупки”. Количество дней до покупки вычисляется путем сложения данного параметра у всех периодов начиная от “дня покупки” справа на лево. Например: чтобы получить “90, 30 и 10 дней до покупки” нужно создать 3 периода равных 10, 20 и 60 дней: 1) 10+20=30 дней до покупки. 2) 30+60=90 дней до покупки.
update//id int Уникальный идентификатор воронки. (Если id не передан, то будет создан новый период).
update//color string Цвет периода
update//sort int Порядковый номер периода при отображении (Периоды выводятся справа на лево начиная от “дня покупки”).

Доступные цвета периодов

Код Образец
#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

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

Параметр Тип Описание
items array Массив созданных/изменённых периодов
items/id int Уникальный идентификатор периода
items//type string Тип периода (before, after). Тип after можно только редактировать.
items//period int Количество дней в периоде
items//color string Цвет периода
items//sort int Порядковый номер периода при отображении
items/after_buy int Количество дней после покупки (период “не купили”)
_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

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


{
	update: [{
		period: "5",
		id: "15563",
		color: "#000000",
		sort: "1"
	}]
}

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


{
	_links: {
		self: {
			href: "/api/v2/customers_periods",
			method: "post"
		}
	},
	_embedded: {
		items: [{
			id: 112805,
			type: "after",
			period: 60,
			color: "#fd5598",
			sort: 0,
			after_buy: 60,
			_links: {
				self: {
					href: "/api/v2/customers_periods",
					method: "get"
				}
			}
		}]
	}
}

Пример интеграции работающей с периодами покупателей


$customers_periods['update'] = array(
    [
        "period" => 10,
        "color" => "#fffd7f",
        "sort" => 0,
    ],
    [
        "id" => 110412,
        "period" => 20,
        "color" => "#ffdc7f",
        "sort" => 1,
    ],
    [
        "id" => 110157,
        "period" => 60,
        "color" => "#ccc8f9",
        "sort" => 2,
    ],
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/customers_periods';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($customers_periods));
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());
}

Список периодов покупателей

Метод для получения списка периодов. Запрос GET отправляется без дополнительных параметров.

URL метода

GET /api/v2/customers_periods

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

Параметр Тип Описание
items array Массив созданных/изменённых периодов
items/id int Уникальный идентификатор периода
items//type string Тип периода (before, after). Тип after можно только редактировать.
items//period int Количество дней в периоде
items//color string Цвет периода
items//sort int Порядковый номер периода при отображении
items/after_buy int Количество дней после покупки (период “не купили”)
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

Пример GET запроса списка периодов покупателей 
https://example.amocrm.ru/api/v2/customers_periods

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


{
	_links: {
		self: {
			href: "/api/v2/customers_periods",
			method: "get"
		}
	},
	_embedded: {
		items: [{
				id: 112815,
				type: "before",
				period: 5,
				color: "#e6e8ea",
				sort: 1,
				before_buy: 5
			},
			{
				id: 112805,
				type: "after",
				period: 60,
				color: "#fd5598",
				sort: 0,
				after_buy: 60
			}
		]
	}
}