Сделки

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

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

URL метода
POST /api/v2/leads

Параметры

Параметр Тип Описание
add array Список добавляемых сделок
update array Обновление существующих сделок
Все параметры, которые описаны в add действуют также и в update
add/name
require
string Название сделки
add/created_at timestamp Дата создания текущей сделки
add/updated_at timestamp Дата изменения текущей сделки
add/status_id int Статус сделки (id этапа продаж см. Воронки и этапы продаж) Чтобы перенести сделку в другую воронку, необходимо установить ей статус из нужной воронки
add/pipeline_id int ID воронки. Указывается в том случае, если выбраны статусы id 142 или 143, т.к. эти статусы не уникальны и обязательны для всех цифровых воронок.
add/responsible_user_id int ID ответственного пользователя
add/sale int Бюджет сделки
add/tags array/string Если вы хотите задать новые теги, перечислите их внутри строковой переменной через запятую. В случае если вам необходимо прикрепить существующие теги, передавайте массив числовых значений id существующих тегов.
add/contacts_id int/array Уникальный идентификатор контакта, для связи с сделкой. Можно передавать несколько id, перечисляя их в массиве через запятую.
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 Тип изменяемого элемента дополнительного поля типа "адрес". Внимание, все типы, которые не были переданы, будут стёрты
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 открепляемой компании

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

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

  1. {
  2.    add: [
  3.       {
  4.          name: "Покупка карандашей",
  5.          created_at: "1508101200",
  6.          updated_at: "1508274000",
  7.          status_id: "13670637",
  8.          responsible_user_id: "957083",
  9.          sale: "5000",
  10.          tags: "pencil, buy",
  11.          contacts_id: [
  12.             "1099149"
  13.             ],
  14.             company_id: "1099148",
  15.             custom_fields: [
  16.                {
  17.                   id: "4399649",
  18.                   values: [
  19.                      "3691615",
  20.                      "3691616",
  21.                      "3691617"
  22.                   ]
  23.                },
  24.                {
  25.                   id: "4399656",
  26.                   values: [
  27.                      {
  28.                         value: "2017-10-26"
  29.                      }
  30.                   ]
  31.                },
  32.                {
  33.                   id: "4399655",
  34.                   values: [
  35.                      {
  36.                         value: "ул. Охотный ряд, 1",
  37.                         subtype: "address_line_1"
  38.                      },
  39.                      {
  40.                         value: "Москва",
  41.                         subtype: "city"
  42.                      },
  43.                      {
  44.                         value: "101010",
  45.                         subtype: "zip"
  46.                      },
  47.                      {
  48.                         value: "RU",
  49.                         subtype: "country"
  50.                      }
  51.                   ]
  52.                }
  53.             ]
  54.       }
  55.    ]
  56. }

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

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

  1. {
  2.    update: [
  3.       {
  4.          id: "1090256",
  5.          updated_at: "1508360400",
  6.          sale: "10000",
  7.          custom_fields: [
  8.             {
  9.                id: "4399664",
  10.                values: [
  11.                   {
  12.                      value: "3691641"
  13.                   }
  14.                ]
  15.             },
  16.             {
  17.                id: "4399665",
  18.                values: [
  19.                   "3691643",
  20.                   "3691644"
  21.                ]
  22.             },
  23.             {
  24.                id: "4399663",
  25.                values: [
  26.                   {
  27.                      value: "пр-т Ленина, д. 2",
  28.                      subtype: "address_line_1"
  29.                   }
  30.                ]
  31.             }
  32.          ]
  33.       }
  34.    ]
  35. }

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

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

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

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

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/leads",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1090255,
  12.             request_id: 0,
  13.             _link: {
  14.                self: {
  15.                   href: "/api/v2/leads?id=1090255",
  16.                   method: "get"
  17.                }
  18.             }
  19.          }
  20.       ]
  21.    }
  22. }

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

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

  1. $leads['add']=array(
  2.   array(
  3.     'name'=>'Сделка по карандашам',
  4.     'created_at'=>1298904164,
  5.     'status_id'=>142,
  6.     'sale'=>300000,
  7.     'responsible_user_id'=>215302,
  8.     'tags' => 'Important, USA', #Теги
  9.    'custom_fields'=>array(
  10.       array(
  11.         'id'=>427496, #Уникальный индентификатор заполняемого дополнительного поля
  12.        'values'=>array( # id значений передаются в массиве values через запятую
  13.            1240665,
  14.             1240664
  15.         )
  16.       ),
  17.       array(
  18.         'id'=>427497, #Уникальный индентификатор заполняемого дополнительного поля
  19.        'values'=>array(
  20.           array(
  21.             'value'=>1240667
  22.           )
  23.         )
  24.       ),
  25.       array(
  26.         'id'=>427231, #Уникальный индентификатор заполняемого дополнительного поля
  27.        'values'=>array(
  28.           array(
  29.             'value'=>'14.06.2014' # в качестве разделителя используется точка
  30.          )
  31.         )
  32.       ),
  33.       array(
  34.         'id'=>458615, #Уникальный индентификатор заполняемого дополнительного поля
  35.        'values'=>array(
  36.           array(
  37.             'value' => 'Address line 1',
  38.             'subtype' => 'address_line_1',
  39.           ),
  40.           array(
  41.             'value' => 'Address line 2',
  42.             'subtype' => 'address_line_2',
  43.           ),
  44.           array(
  45.             'value' => 'Город',
  46.             'subtype' => 'city',
  47.           ),
  48.           array(
  49.             'value' => 'Регион',
  50.             'subtype' => 'state',
  51.           ),
  52.           array(
  53.             'value' => '203',
  54.             'subtype' => 'zip',
  55.           ),
  56.           array(
  57.             'value' => 'RU',
  58.             'subtype' => 'country',
  59.           )
  60.         )
  61.       )
  62.     )
  63.   ),
  64.   array(
  65.     'name'=>'Бумага',
  66.     'created_at'=>1298904164,
  67.     'status_id'=>7087609,
  68.     'sale'=>600200,
  69.     'responsible_user_id'=>215309,
  70.     'custom_fields'=>array(
  71.       array(
  72.         #Нестандартное дополнительное поле типа "мультисписок", которое мы создали
  73.        'id'=>426106,
  74.         'values'=>array(
  75.           1237756,
  76.           1237758
  77.         )
  78.       )
  79.     )
  80.   )
  81. );
  82. /* Теперь подготовим данные, необходимые для запроса к серверу */
  83. $subdomain='test'; #Наш аккаунт - поддомен
  84. #Формируем ссылку для запроса
  85. $link='https://'.$subdomain.'.amocrm.ru/api/v2/leads';
  86. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  87. работе с этой
  88. библиотекой Вы можете прочитать в мануале. */
  89. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  90. #Устанавливаем необходимые опции для сеанса cURL
  91. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  92. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  93. curl_setopt($curl,CURLOPT_URL,$link);
  94. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  95. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($leads));
  96. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  97. curl_setopt($curl,CURLOPT_HEADER,false);
  98. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  99. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  100. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  101. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  102. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  103. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  104. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  105. $code=(int)$code;
  106. $errors=array(
  107.   301=>'Moved permanently',
  108.   400=>'Bad request',
  109.   401=>'Unauthorized',
  110.   403=>'Forbidden',
  111.   404=>'Not found',
  112.   500=>'Internal server error',
  113.   502=>'Bad gateway',
  114.   503=>'Service unavailable'
  115. );
  116. try
  117. {
  118.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  119.  if($code!=200 && $code!=204) {
  120.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  121.   }
  122. }
  123. catch(Exception $E)
  124. {
  125.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  126. }

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

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

URL метода
GET /api/v2/leads

Параметры GET

Параметр Описание
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offsetСдвиг выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан
id Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID
query Поисковый запрос (Осуществляет поиск по заполненым полям сущности)
responsible_user_id Дополнительный фильтр поиска, по ответственному пользователю
(Можно передавать в виде массива)
status Фильтр по ID статуса сделки (Как узнать список доступных ID см. здесь)
(Можно передавать в виде массива)

Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y H:i:s. При передаче этого заголовка будут возвращены сделки, изменённые позже этой даты. Заголовок должен быть передан в часовом поясе UTC.

  1. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 07:07:23 UTC'));

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

Параметр Тип Описание
id int Уникальный идентификатор сделки
name string Название сделки
responsible_user_id int id ответственного пользователя
created_by int id пользователя создавшего сделку
created_at timestamp Время и дата создания сделки
updated_at timestamp Время и дата изменения сделки
account_id int id аккаунта на котором создана сделка
is_deleted bool Удалена сделка или нет. Удалённые сделки могут находиться в "удалённых".
main_contact array Массив содержащий информацию о главном контакте сделки
main_contact/id int id главного контакта сделки
group_id int id группы в которой состоит пользователь ответственный за данную сделку
company array Массив содержащий информацию о компании, которая прикреплена к данной сделке
company/id int id компании, которая прикреплена к данной сделке
company/name string название компании, которая прикреплена к данной сделке
closed_at timestamp Время и дата, когда была завершена данная сделка
closest_task_at timestamp Время ближайшей задачи по данной сделки
tags array Массив содержащий информацию по тегам, прикреплённым к данной сделке
tags/id int id тега, прикреплённого к данной сделке
tags/name string Название тега, прикреплённого к данной сделке
custom_fields array Массив содержащий информацию по дополнительным полям, заданным для данной сделки
custom_fields//id int id дополнительного поля
custom_fields//name string название дополнительного поля
custom_fields//values array Массив содержащий информацию по дополнительным полям, заданным для данной сделки
custom_fields//values//value string Значение дополнительного поля
custom_fields//values//enum string Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
custom_fields//values//subtype string Идентификатор значений дополнительного поля "адрес"
custom_fields//is_system bool Является ли дополнительное поле системным
contacts array Массив содержащий информацию по контактам прикреплённым к данной сделке
contacts/id int id прикреплённого к сделке контакта
status_id int id этапа цифровой воронки, на котором находится данная сделка
sale int Бюджет сделки
pipeline array Массив содержащий информацию по цифровой воронке, в которой находится данная сделка
pipeline/id int id цифровой воронки, в которой находится данная сделка
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

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

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/leads?id=1090256",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1090256,
  12.             name: "Сделка #1090256",
  13.             responsible_user_id: 957084,
  14.             created_by: 957084,
  15.             created_at: 1508400624,
  16.             updated_at: 1508403644,
  17.             account_id: 13670640,
  18.             is_deleted: false,
  19.             main_contact: {
  20.                id: 1099418,
  21.                _links: {
  22.                   self: {
  23.                      href: "/api/v2/contacts?id=1099153",
  24.                      method: "get"
  25.                   }
  26.                }
  27.             },
  28.             group_id: 0,
  29.             company: {
  30.                id: 1099427,
  31.                name: null,
  32.                _links: {
  33.                   self: {
  34.                      href: "/api/v2/companies?id=1099152",
  35.                      method: "get"
  36.                   }
  37.                }
  38.             },
  39.             closed_at: 0,
  40.             closest_task_at: 1508446740,
  41.             tags: [],
  42.             custom_fields: [
  43.                {
  44.                   id: 4399664,
  45.                   name: "Список",
  46.                   values: [
  47.                      {
  48.                         value: "5",
  49.                         enum: "3691641"
  50.                      }
  51.                   ],
  52.                   is_system: false
  53.                },
  54.                {
  55.                   id: 4399665,
  56.                   name: "Мультисписок",
  57.                   values: [
  58.                      {
  59.                         value: "2",
  60.                         enum: "3691643"
  61.                      },
  62.                      {
  63.                         value: "3",
  64.                         enum: "3691644"
  65.                      }
  66.                  ],
  67.                  is_system: false
  68.               },
  69.               {
  70.                  id: 4399666,
  71.                  name: "Текст",
  72.                  values: [
  73.                     {
  74.                        value: "Здесь, к примеру, какие-либо пояснения к сделке"
  75.                     }
  76.                  ],
  77.                  is_system: false
  78.               },
  79.               {
  80.                  id: 4399663,
  81.                  name: "Адрес",
  82.                  values: [
  83.                     {
  84.                        value: "пр-т Мира, д. 3",
  85.                        subtype: "1"
  86.                     },
  87.                     {
  88.                        value: "Москва",
  89.                        subtype: "3"
  90.                     },
  91.                     {
  92.                        value: "101010",
  93.                        subtype: "5"
  94.                     }
  95.                  ],
  96.                  is_system: false
  97.               }
  98.            ],
  99.            contacts: {
  100.               id: [
  101.                  1099418,
  102.                  1099154
  103.               ],
  104.               _links: {
  105.                  self: {
  106.                     href: "/api/v2/contacts?id=1099418,1099154",
  107.                     method: "get"
  108.                  }
  109.               }
  110.            },
  111.            status_id: 13670642,
  112.            sale: 5000,
  113.            pipeline: {
  114.               id: 10273,
  115.               _links: {
  116.                  self: {
  117.                     href: "/api/v2/pipelines?id=10246",
  118.                     method: "get"
  119.                  }
  120.               }
  121.            },
  122.            _links: {
  123.               self: {
  124.                  href: "/api/v2/leads?id=1090256",
  125.                  method: "get"
  126.               }
  127.            }
  128.         }
  129.       ]
  130.    }
  131. }

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

  1. /* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
  2. $subdomain='test'; #Наш аккаунт - поддомен
  3. /* Формируем ссылку для запроса */
  4. $link='https://'.$subdomain.'.amocrm.ru/api/v2/leads';
  5. /* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите документацию
  6. выше).
  7. Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
  8. необходимо. */
  9. $link='https://'.$subdomain.'.amocrm.ru/api/v2/leads?limit_rows=50';
  10. $link='https://'.$subdomain.'.amocrm.ru/api/v2/leads?limit_rows=50&limit_offset=2';
  11. /* Следующий запрос вернёт список сделок, у которых есть почта 'test@mail.com' */
  12. $link='https://'.$subdomain.'.amocrm.ru/api/v2/leads?query=test@mail.com';
  13. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  14. работе с этой
  15. библиотекой Вы можете прочитать в мануале. */
  16. $curl=curl_init();
  17. /* Устанавливаем необходимые опции для сеанса cURL */
  18. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  19. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  20. curl_setopt($curl,CURLOPT_URL,$link);
  21. curl_setopt($curl,CURLOPT_HEADER,false);
  22. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  25. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  26. /* Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y
  27. H:i:s. При
  28. передаче этого заголовка будут возвращены сделки, изменённые позже этой даты. */
  29. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
  30. /* Выполняем запрос к серверу. */
  31. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  32. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  33. curl_close($curl);
  34. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  35. $code=(int)$code;
  36. $errors=array(
  37.   301=>'Moved permanently',
  38.   400=>'Bad request',
  39.   401=>'Unauthorized',
  40.   403=>'Forbidden',
  41.   404=>'Not found',
  42.   500=>'Internal server error',
  43.   502=>'Bad gateway',
  44.   503=>'Service unavailable'
  45. );
  46. try
  47. {
  48.   /* Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке */
  49.   if($code!=200 && $code!=204) {
  50.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  51.   }
  52. }
  53. catch(Exception $E)
  54. {
  55.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  56. }
  57. /*
  58.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  59.  нам придётся перевести ответ в формат, понятный PHP
  60.  */
  61. $Response=json_decode($out,true);
  62. $Response=$Response['_embedded']['items'];

Смотрите также

Коды ошибок API