Методы элементов списка

Добавление, обновление и удаление элементов списка

Эти методы доступны только пользователям, у которые есть права на доступ к спискам.

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

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

Параметры

Параметр Тип Описание
add array Список добавляемых элементов списка
update array Обновление существующих элементов списка
Все параметры, которые описанны в add действуют также и в update
delete array Массив удаляемых элементов списков
add/catalog_id
require
string ID списка
add/name
require
string Название элемента
add/request_id int Уникальный идентификатор записи в клиентской программе, необязательный параметр (информация о request_id нигде не сохраняется)
add/custom_fields array Дополнительные поля
add/custom_fields// array Внутри него будет описание каждого доп поля
add/custom_fields//id int Уникальный идентификатор заполняемого дополнительного поля (см. Информация аккаунта)
add/custom_fields//values array Внутри будет еще один массив, с описанием value
add/custom_fields//values// array Здесь будут описаны значения доп. поля, и, если нужно, дополнительный тип (для полей типа "мультисписок" просто перечисляем id выбранных значений)
add/custom_fields//values//value string Значение дополнительного поля
add/custom_fields//values//enum string Выбираемый тип дополнительного поля (например телефон домашний, рабочий и т. д.)
add/custom_fields//values//subtype string Тип изменяемого элемента дополнительного поля. Внимание, все не указанные типы будут стёрты
update/id
require
int Уникальный идентификатор элемента списка, который указывается с целью его обновления
update/updated_at
require
int Уникальный идентификатор элемента списка, который указывается с целью его обновления

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

  1. {
  2.    add: [
  3.       {
  4.          catalog_id: "4220",
  5.          name: "Карандаш",
  6.          custom_fields: [
  7.             {
  8.                id: "4400050",
  9.                values: [
  10.                   {
  11.                      value: "100"
  12.                   }
  13.                ]
  14.             },
  15.             {
  16.                id: "4400062",
  17.                values: [
  18.                   "3692539",
  19.                   "3692540"
  20.                ]
  21.             }
  22.          ]
  23.       }
  24.    ]
  25. }

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

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

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

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

Добавление элементов

Для создания нового элемента списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида: $catalog_elements['add']

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

Здесь можно посмотреть структуру кастомных полей на примере массива элемента списка.

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

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

Обновление элементов

Для обновления элемента списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида: $catalog_elements['update']

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

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

  1. $catalog_elements['update']=array(
  2.   array(
  3.       'catalog_id'=>2534,
  4.     'id'=> 35431,
  5.     'name'=>'Explosive Galaxy Note 7',
  6.   ),
  7.   array(
  8.     'catalog_id'=>2534,
  9.     'id'=> 35431,
  10.     'name'=>'MacBook Pro 2016',
  11.   )
  12. );
  13. /* Теперь подготовим данные, необходимые для запроса к серверу */
  14. $subdomain='test'; #Наш аккаунт - поддомен
  15. #Формируем ссылку для запроса
  16. $link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements';
  17. Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  18. работе с этой
  19. библиотекой Вы можете прочитать в мануале.
  20. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  21. #Устанавливаем необходимые опции для сеанса cURL
  22. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  23. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  24. curl_setopt($curl,CURLOPT_URL,$link);
  25. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  26. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($catalog_elements));
  27. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  28. curl_setopt($curl,CURLOPT_HEADER,false);
  29. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  30. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  31. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  32. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  33. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  34. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  35. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  36. $code=(int)$code;
  37. $errors=array(
  38.   301=>'Moved permanently',
  39.   400=>'Bad request',
  40.   401=>'Unauthorized',
  41.   403=>'Forbidden',
  42.   404=>'Not found',
  43.   500=>'Internal server error',
  44.   502=>'Bad gateway',
  45.   503=>'Service unavailable'
  46. );
  47. try
  48. {
  49.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  50.  if($code!=200 && $code!=204)
  51.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  52. }
  53. catch(Exception $E)
  54. {
  55.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  56. }

Удаление элементов

Для удаления элемента списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида: $catalog_elements['delete']

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

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

  1. $catalog_elements['delete']=array(
  2.   35159,
  3.   35164
  4. );
  5. /* Теперь подготовим данные, необходимые для запроса к серверу */
  6. $subdomain='test'; #Наш аккаунт - поддомен
  7. #Формируем ссылку для запроса
  8. $link='https://'.$subdomain.'.amocrm.ru/api/v2/catalog_elements';
  9. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  10. работе с этой
  11. библиотекой Вы можете прочитать в мануале. */
  12. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  13. #Устанавливаем необходимые опции для сеанса cURL
  14. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  15. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  16. curl_setopt($curl,CURLOPT_URL,$link);
  17. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  18. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($catalog_elements));
  19. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  20. curl_setopt($curl,CURLOPT_HEADER,false);
  21. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  22. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  25. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  26. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  27. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  28. $code=(int)$code;
  29. $errors=array(
  30.   301=>'Moved permanently',
  31.   400=>'Bad request',
  32.   401=>'Unauthorized',
  33.   403=>'Forbidden',
  34.   404=>'Not found',
  35.   500=>'Internal server error',
  36.   502=>'Bad gateway',
  37.   503=>'Service unavailable'
  38. );
  39. try
  40. {
  41.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  42.  if($code!=200 && $code!=204)
  43.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  44. }
  45. catch(Exception $E)
  46. {
  47.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  48. }

Перечень элементов списка

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

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

Параметры GET

Параметр Описание
id Выбрать элемент с заданным id
catalog_id
require
Выбрать данные из определенного списка
term Поисковый запрос по названию элемента
PAGEN_1 Страница выборки

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

Параметр Тип Описание
id int Уникальный идентификатор элемента
name string Название элемента
created_at timestamp Дата создания
updated_at timestamp Дата изменения
catalog_id int id списка, в котором находится элемент
created_by id id пользователя, создавшего сделку
is_deleted bool Удалён элемент или нет
custom_fields array Массив дополнительных полей элемента списка
custom_fields//id int Уникальный идентификатор дополнительного поля
custom_fields//name string Название дополнительного поля
custom_fields//values array Массив, значений текущего доп поля
custom_fields//values//value string Значение текущего доп поля
custom_fields//values//enum string Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
custom_fields//is_system bool Является дополнительное поле системным или нет
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/catalog_elements?catalog_id=4220",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 41873,
  12.             name: "Маркеры",
  13.             created_by: 504141,
  14.             created_at: 1509003163,
  15.             updated_at: 1509003163,
  16.             updated_by: 504141,
  17.             is_deleted: false,
  18.             custom_fields: [
  19.                {
  20.                   id: 4400049,
  21.                   name: "Артикул",
  22.                   values: [
  23.                      {
  24.                         value: "416"
  25.                      }
  26.                   ],
  27.                   is_system: true
  28.                },
  29.                {
  30.                   id: 4400050,
  31.                   name: "Количество",
  32.                   values: [
  33.                      {
  34.                         value: "250"
  35.                      }
  36.                   ],
  37.                   is_system: true
  38.                },
  39.                {
  40.                   id: 4400051,
  41.                   name: "Цена",
  42.                   values: [
  43.                      {
  44.                         value: "80"
  45.                      }
  46.                   ],
  47.                   is_system: true
  48.                },
  49.                {
  50.                   id: 4400062,
  51.                   name: "Мультисписок",
  52.                   values: [
  53.                      {
  54.                         value: "2",
  55.                         enum: "3692540"
  56.                      },
  57.                      {
  58.                         value: "3",
  59.                         enum: "3692541"
  60.                      }
  61.                   ],
  62.                   is_system: false
  63.                }
  64.             ],
  65.             catalog_id: 4220,
  66.             _links: {
  67.                self: {
  68.                   href: "/api/v2/catalog_elements?id=41873&catalog_id=4220",
  69.                   method: "get"
  70.                }
  71.             }
  72.          },
  73.          {
  74.             id: 41872,
  75.             name: "Карандаши",
  76.             created_by: 504141,
  77.             created_at: 1509003145,
  78.             updated_at: 1509003145,
  79.             updated_by: 504141,
  80.             is_deleted: false,
  81.             custom_fields: [
  82.                {
  83.                   id: 4400049,
  84.                   name: "Артикул",
  85.                   values: [
  86.                      {
  87.                         value: "415"
  88.                      }
  89.                   ],
  90.                   is_system: true
  91.                },
  92.                {
  93.                   id: 4400050,
  94.                   name: "Количество",
  95.                   values: [
  96.                      {
  97.                         value: "300"
  98.                      }
  99.                   ],
  100.                   is_system: true
  101.                },
  102.                {
  103.                   id: 4400051,
  104.                   name: "Цена",
  105.                   values: [
  106.                      {
  107.                         value: "75"
  108.                      }
  109.                   ],
  110.                   is_system: true
  111.                },
  112.                {
  113.                   id: 4400062,
  114.                   name: "Мультисписок",
  115.                   values: [
  116.                      {
  117.                         value: "1",
  118.                         enum: "3692539"
  119.                      },
  120.                      {
  121.                         value: "2",
  122.                         enum: "3692540"
  123.                      }
  124.                   ],
  125.                   is_system: false
  126.                }
  127.             ],
  128.             catalog_id: 4220,
  129.             _links: {
  130.                self: {
  131.                   href: "/api/v2/catalog_elements?id=41872&catalog_id=4220",
  132.                   method: "get"
  133.                }
  134.             }
  135.          }
  136.       ]
  137.    }
  138. }

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

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