Списки

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

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

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

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

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

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

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

  1. $catalogs [ 'update' ] = array (
  2.     'id' => 2561 ,
  3.     'name' => 'Products' ,
  4.   ) ,
  5.     'id' => 2562 ,
  6.     'name' => 'Cars' ,
  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. }

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

Для удаления списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида: $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' ] ;