Если у вас еще нет amoCRM
Создать прямо сейчасАналогичен сущности “сделка”. Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждый покупатель может быть прикреплен к одному и более контакту или не прикреплен ни к одному.
Каждому покупателю может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.
Покупатель обладает периодом, который обозначает положение покупателя в жизненном цикле (бизнес-процесс). Список периодов может быть изменен в рамках аккаунта, кроме первого и трех конечных системных периодов.
Метод позволяет добавлять покупателей по одному или пакетно, а также обновлять данные по уже существующим покупателям и удалять их.
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 содержит следующие заголовки:
Пример запроса на добавление нового покупателя.
{
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: "Татьяна"
}
]
}
}
}
Метод для получения списка покупателей с возможностью фильтрации и постраничной выборки.
GET /api/v2/customers
| Параметр | Описание |
|---|---|
| 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 |
| with | Если в параметре with указать значения (список см. здесь), в ответ придёт информация о покупателе по соответствующему значению. |
Возможные значения GET параметра with. Указывать можно более одного значения, через “,”.
Пример: https://example.amocrm.ru/api/v2/customers?with=is_price_modified_by_robot,loss_reason_name
| Значение | Описание |
|---|---|
| catalog_elements_links | Данный параметр добавит к покупателю информацию о связанных элементах каталогов (id каталога, id элемента каталога, количество). |
Response Headeres содержит следующие заголовки:
| Параметр | Тип | Описание |
|---|---|---|
| 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 содержит следующие заголовки:
Пример запроса на добавление транзакции
{
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"
]
}
Метод для добавления и изменения комментария существующей транзакции. При изменении комментария у существующей транзакции, сама транзакция не обновляется.
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 содержит следующие заголовки:
{
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());
}
Метод для получения списка транзакций с возможностью фильтрации.
GET /api/v2/transactions
| Параметр | Описание |
|---|---|
| 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 (Цифровая воронка). Эти методы доступны только администратору аккаунта
Метод позволяет изменять данные по периодам. При изменении необходимо передать полный список периодов, включая уже существующие. При удалении периода нужно исключить его из запроса.
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 содержит следующие заголовки:
{
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 отправляется без дополнительных параметров.
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
}
]
}
}