Списки

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

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

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

Параметры

Параметр Тип Описание
add array Перечень добавляемых списков
update array Обновление существующих списков
Все параметры, которые описанны в add действуют также и в update
delete array Перечень удаляемых списков
add/name
require
string Название списка
add/type string Тип списка
"regular" - список, "invoices" - счета
add/can_add_elements bool Добавление счета из интерфейса
add/can_show_in_cards bool Возможность добавить вкладку со списком в карточку сделки/покупателя
add/can_link_multiple bool Возможность привязывать один элемент данного списка к нескольким сделкам/покупателям
add/request_id int Уникальный идентификатор записи в клиентской программе, необязательный параметр (информация о request_id нигде не сохраняется)
update/id
require
int Уникальный идентификатор списка, который указывается с целью его обновления
delete
require
array Массив с уникальными идентификаторами списков, которые указываются с целью удаления

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

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

  1. {
  2.    add: [
  3.       {
  4.          name: "Товары"
  5.       }
  6.    ]
  7. }

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

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

  1. {
  2.    update: [
  3.       {
  4.          id: "2456",
  5.          name: "Товары"
  6.       }
  7.    ]
  8. }

Пример запроса на удаление списков

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

  1. {
  2.    delete: [
  3.       {
  4.          2456,
  5.          2472,
  6.          2483
  7.       }
  8.    ]
  9. }

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

Параметр Описание
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/catalogs",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 4223,
  12.             _link: {
  13.                self: {
  14.                   href: "/api/v2/catalogs?id=4223",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

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

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

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

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

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

Обновление списков

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

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

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

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

Удаление списков

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

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

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

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

Перечень списков

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

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

Параметры GET

Параметр Описание
id Выбрать элемент с заданным ID

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

Параметр Тип Описание
id int Уникальный идентификатор списка
name string Название списка
created_by int ID пользователя, создавшего список
created_at timestamp Дата создания
sort int Параметр указывает на каком месте будет находиться список
_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/catalogs",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 4223,
  12.             name: "Товары",
  13.             created_by: 504141,
  14.             created_at: 1508930391,
  15.             sort: 10,
  16.             _links: {
  17.                self: {
  18.                   href: "/api/v2/catalogs?id=4223",
  19.                   method: "get"
  20.                }
  21.             }
  22.          },
  23.          {
  24.             id: 4222,
  25.             name: "Услуги",
  26.             created_by: 504141,
  27.             created_at: 1508930288,
  28.             sort: 20,
  29.             _links: {
  30.                self: {
  31.                   href: "/api/v2/catalogs?id=4222",
  32.                   method: "get"
  33.                }
  34.             }
  35.          }
  36.       ]
  37.    }
  38. }

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

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