Если у вас еще нет amoCRM
Создать прямо сейчасМетод позволяет добавлять сделки по одной или пакетно, а также обновлять данные по уже существующим сделкам.
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 | array | Список элементов каталогов для привязки с указанием количества, сгруппированный по 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 содержит следующие заголовки:
{
_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 сделок.
GET /api/v2/leads
| Параметр | Описание |
|---|---|
| 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 параметра 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, название причины отказа |
| only_deleted | Если передать данный параметр, то в ответе на запрос метода, вернутся удаленные сделки, которые еще находятся в корзине. В ответ вы получите дату изменения, id пользователя сделавшего последнее изменение, id сделки и параметр is_deleted = true. |
| catalog_elements_links | Данный параметр добавит к сделке информацию о связанных элементах каталогов (id каталога, 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 | Время ближайшей задачи по данной сделки |
| _embedded/items//_embedded/catalog_elements_links/ | array | Массив с объектами, в которых передается информация о привязанных элементах каталогов. В объекте доступны ключи – id, catalog_id, quantity. Доступен при передаче параметра with. |
| 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 содержит следующие заголовки:
{
_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'];